OLD | NEW |
| (Empty) |
1 // Copyright 2015 The Shaderc Authors. All rights reserved. | |
2 // | |
3 // Licensed under the Apache License, Version 2.0 (the "License"); | |
4 // you may not use this file except in compliance with the License. | |
5 // You may obtain a copy of the License at | |
6 // | |
7 // http://www.apache.org/licenses/LICENSE-2.0 | |
8 // | |
9 // Unless required by applicable law or agreed to in writing, software | |
10 // distributed under the License is distributed on an "AS IS" BASIS, | |
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
12 // See the License for the specific language governing permissions and | |
13 // limitations under the License. | |
14 | |
15 #ifndef SHADERC_H_ | |
16 #define SHADERC_H_ | |
17 | |
18 #ifdef __cplusplus | |
19 extern "C" { | |
20 #endif | |
21 | |
22 #include <stdbool.h> | |
23 #include <stddef.h> | |
24 #include <stdint.h> | |
25 | |
26 typedef enum { | |
27 // Forced shader kinds. These shader kinds force the compiler to compile the | |
28 // source code as the specified kind of shader. | |
29 shaderc_glsl_vertex_shader, | |
30 shaderc_glsl_fragment_shader, | |
31 shaderc_glsl_compute_shader, | |
32 shaderc_glsl_geometry_shader, | |
33 shaderc_glsl_tess_control_shader, | |
34 shaderc_glsl_tess_evaluation_shader, | |
35 // Deduce the shader kind from #pragma annotation in the source code. Compiler | |
36 // will emit error if #pragma annotation is not found. | |
37 shaderc_glsl_infer_from_source, | |
38 // Default shader kinds. Compiler will fall back to compile the source code as | |
39 // the specified kind of shader when #pragma annotation is not found in the | |
40 // source code. | |
41 shaderc_glsl_default_vertex_shader, | |
42 shaderc_glsl_default_fragment_shader, | |
43 shaderc_glsl_default_compute_shader, | |
44 shaderc_glsl_default_geometry_shader, | |
45 shaderc_glsl_default_tess_control_shader, | |
46 shaderc_glsl_default_tess_evaluation_shader, | |
47 } shaderc_shader_kind; | |
48 | |
49 typedef enum { | |
50 shaderc_target_env_vulkan, // create SPIR-V under Vulkan semantics | |
51 shaderc_target_env_opengl, // create SPIR-V under OpenGL semantics | |
52 shaderc_target_env_opengl_compat, // create SPIR-V under OpenGL semantics, | |
53 // including compatibility profile | |
54 // functions | |
55 shaderc_target_env_default = shaderc_target_env_vulkan | |
56 } shaderc_target_env; | |
57 | |
58 typedef enum { | |
59 shaderc_profile_none, // Used if and only if GLSL version did not specify | |
60 // profiles. | |
61 shaderc_profile_core, | |
62 shaderc_profile_compatibility, | |
63 shaderc_profile_es, | |
64 } shaderc_profile; | |
65 | |
66 // Used in the result module (shaderc_spv_module) to indicate the status of an | |
67 // compilation. | |
68 typedef enum { | |
69 shaderc_compilation_status_success = 0, | |
70 shaderc_compilation_status_invalid_stage, // error stage deduction | |
71 shaderc_compilation_status_compilation_error, | |
72 shaderc_compilation_status_internal_error, // unexpected failure | |
73 shaderc_compilation_status_null_result_module, | |
74 } shaderc_compilation_status; | |
75 | |
76 // Usage examples: | |
77 // | |
78 // Aggressively release compiler resources, but spend time in initialization | |
79 // for each new use. | |
80 // shaderc_compiler_t compiler = shaderc_compiler_initialize(); | |
81 // shader_spv_module_t module = shaderc_compile_into_spv(compiler, | |
82 // "int main() {}", 13, shaderc_glsl_vertex_shader, "main"); | |
83 // // Do stuff with module compilation results. | |
84 // shaderc_module_release(module); | |
85 // shaderc_compiler_release(compiler); | |
86 // | |
87 // Keep the compiler object around for a long time, but pay for extra space | |
88 // occupied. | |
89 // shaderc_compiler_t compiler = shaderc_compiler_initialize(); | |
90 // // On the same, other or multiple simultaneous threads. | |
91 // shader_spv_module_t module = shaderc_compile_into_spv(compiler, | |
92 // "int main() {}", 13, shaderc_glsl_vertex_shader, "main"); | |
93 // // Do stuff with module compilation results. | |
94 // shaderc_module_release(module); | |
95 // // Once no more compilations are to happen. | |
96 // shaderc_compiler_release(compiler); | |
97 | |
98 // An opaque handle to an object that manages all compiler state. | |
99 typedef struct shaderc_compiler* shaderc_compiler_t; | |
100 | |
101 // Returns a shaderc_compiler_t that can be used to compile modules. | |
102 // A return of NULL indicates that there was an error initializing the compiler. | |
103 // Any function operating on shaderc_compiler_t must offer the basic | |
104 // thread-safety guarantee. | |
105 // [http://herbsutter.com/2014/01/13/gotw-95-solution-thread-safety-and-synchron
ization/] | |
106 // That is: concurrent invocation of these functions on DIFFERENT objects needs | |
107 // no synchronization; concurrent invocation of these functions on the SAME | |
108 // object requires synchronization IF AND ONLY IF some of them take a non-const | |
109 // argument. | |
110 shaderc_compiler_t shaderc_compiler_initialize(void); | |
111 | |
112 // Releases the resources held by the shaderc_compiler_t. | |
113 // After this call it is invalid to make any future calls to functions | |
114 // involving this shaderc_compiler_t. | |
115 void shaderc_compiler_release(shaderc_compiler_t); | |
116 | |
117 // An opaque handle to an object that manages options to a single compilation | |
118 // result. | |
119 typedef struct shaderc_compile_options* shaderc_compile_options_t; | |
120 | |
121 // Returns a default-initialized shaderc_compile_options_t that can be used | |
122 // to modify the functionality of a compiled module. | |
123 // A return of NULL indicates that there was an error initializing the options. | |
124 // Any function operating on shaderc_compile_options_t must offer the | |
125 // basic thread-safety guarantee. | |
126 shaderc_compile_options_t shaderc_compile_options_initialize(void); | |
127 | |
128 // Returns a copy of the given shaderc_compile_options_t. | |
129 // If NULL is passed as the parameter the call is the same as | |
130 // shaderc_compile_options_init. | |
131 shaderc_compile_options_t shaderc_compile_options_clone( | |
132 const shaderc_compile_options_t options); | |
133 | |
134 // Releases the compilation options. It is invalid to use the given | |
135 // shaderc_compile_options_t object in any future calls. It is safe to pass | |
136 // NULL to this function, and doing such will have no effect. | |
137 void shaderc_compile_options_release(shaderc_compile_options_t options); | |
138 | |
139 // Adds a predefined macro to the compilation options. This has the | |
140 // same effect as passing -Dname=value to the command-line compiler. | |
141 // If value is NULL, it has the effect same as passing -Dname to the | |
142 // command-line compiler. If a macro definition with the same name has | |
143 // previously been added, the value is replaced with the new value. | |
144 // The null-terminated strings that the name and value parameters point to | |
145 // must remain valid for the duration of the call, but can be modified or | |
146 // deleted after this function has returned. | |
147 void shaderc_compile_options_add_macro_definition( | |
148 shaderc_compile_options_t options, const char* name, const char* value); | |
149 | |
150 // Sets the compiler mode to generate debug information in the output. | |
151 void shaderc_compile_options_set_generate_debug_info( | |
152 shaderc_compile_options_t options); | |
153 | |
154 // Sets the compiler mode to emit a disassembly text instead of a binary. In | |
155 // this mode, the byte array result in the shaderc_spv_module returned | |
156 // from shaderc_compile_into_spv() will consist of SPIR-V assembly text. | |
157 // Note the preprocessing only mode overrides this option, and this option | |
158 // overrides the default mode generating a SPIR-V binary. | |
159 void shaderc_compile_options_set_disassembly_mode( | |
160 shaderc_compile_options_t options); | |
161 | |
162 // Forces the GLSL language version and profile to a given pair. The version | |
163 // number is the same as would appear in the #version annotation in the source. | |
164 // Version and profile specified here overrides the #version annotation in the | |
165 // source. Use profile: 'shaderc_profile_none' for GLSL versions that do not | |
166 // define profiles, e.g. versions below 150. | |
167 void shaderc_compile_options_set_forced_version_profile( | |
168 shaderc_compile_options_t options, int version, shaderc_profile profile); | |
169 | |
170 // To support file inclusion, libshaderc invokes a callback into its client to | |
171 // resolve the full path and content of the included file. | |
172 // The client callback should follow the specified function signature below, and | |
173 // it should be passed to libshaderc through the corresponding setter function. | |
174 // When the including of a file is done, libshaderc will call another client | |
175 // callback to clean up the resources used for the including process. The client | |
176 // should implement the clean up method and pass it to libshaderc together with | |
177 // the response method. | |
178 | |
179 // The struct that contains the information to be returned to the libshaderc. | |
180 // The client-side implemented response method should return a pointer of this | |
181 // struct. The underlying data is owned by client code. | |
182 struct shaderc_includer_response { | |
183 const char* path; | |
184 size_t path_length; | |
185 const char* content; | |
186 size_t content_length; | |
187 }; | |
188 | |
189 // The function signature of the client-side implemented response method. It | |
190 // returns a pointer to shaderc_includer_response struct. | |
191 typedef shaderc_includer_response* (*shaderc_includer_response_get_fn)( | |
192 void* user_data, const char* filename); | |
193 | |
194 // The function signature of the client-side implemented clean-up method. | |
195 // Includer will call this callback function when the including process is done | |
196 // with the fullpath and content data. | |
197 typedef void (*shaderc_includer_response_release_fn)( | |
198 void* user_data, shaderc_includer_response* data); | |
199 | |
200 // Sets the callback functions for the includer. When the includer queries for | |
201 // the full path and content of a file, client's method will be called to | |
202 // response. And when the query is done, client will be notified to clean up. | |
203 // TODO: File inclusion needs to be context-aware. | |
204 // e.g. | |
205 // In file: /path/to/main_shader.vert: | |
206 // #include "include/a" | |
207 // In file: /path/to/include/a": | |
208 // #include "b" | |
209 // When compiling /path/to/main_shader.vert, the compiler should be able to | |
210 // go to /path/to/include/b to find the file b. | |
211 // This needs context info from compiler to client includer, and may needs | |
212 // interface changes. | |
213 void shaderc_compile_options_set_includer_callbacks( | |
214 shaderc_compile_options_t options, shaderc_includer_response_get_fn getter, | |
215 shaderc_includer_response_release_fn releasor, void* user_data); | |
216 | |
217 // Sets the compiler mode to do only preprocessing. The byte array result in the | |
218 // module returned by the compilation is the text of the preprocessed shader. | |
219 // This option overrides all other compilation modes, such as disassembly mode | |
220 // and the default mode of compilation to SPIR-V binary. | |
221 void shaderc_compile_options_set_preprocessing_only_mode( | |
222 shaderc_compile_options_t options); | |
223 | |
224 // Sets the compiler mode to suppress warnings, overriding warnings-as-errors | |
225 // mode. When both suppress-warnings and warnings-as-errors modes are | |
226 // turned on, warning messages will be inhibited, and will not be emitted | |
227 // as error messages. | |
228 void shaderc_compile_options_set_suppress_warnings( | |
229 shaderc_compile_options_t options); | |
230 | |
231 // Sets the target shader environment, affecting which warnings or errors will | |
232 // be issued. The version will be for distinguishing between different versions | |
233 // of the target environment. "0" is the only supported version at this point | |
234 void shaderc_compile_options_set_target_env(shaderc_compile_options_t options, | |
235 shaderc_target_env target, | |
236 uint32_t version); | |
237 | |
238 // Sets the compiler mode to treat all warnings as errors. Note the | |
239 // suppress-warnings mode overrides this option, i.e. if both | |
240 // warning-as-errors and suppress-warnings modes are set, warnings will not | |
241 // be emitted as error messages. | |
242 void shaderc_compile_options_set_warnings_as_errors( | |
243 shaderc_compile_options_t options); | |
244 | |
245 // An opaque handle to the results of a call to shaderc_compile_into_spv(). | |
246 typedef struct shaderc_spv_module* shaderc_spv_module_t; | |
247 | |
248 // Takes a GLSL source string and the associated shader kind, input file | |
249 // name, compiles it according to the given additional_options. If the shader | |
250 // kind is not set to a specified kind, but shaderc_glslc_infer_from_source, | |
251 // the compiler will try to deduce the shader kind from the source | |
252 // string and a failure in deducing will generate an error. Currently only | |
253 // #pragma annotation is supported. If the shader kind is set to one of the | |
254 // default shader kinds, the compiler will fall back to the default shader | |
255 // kind in case it failed to deduce the shader kind from source string. | |
256 // The input_file_name is a null-termintated string. It is used as a tag to | |
257 // identify the source string in cases like emitting error messages. It | |
258 // doesn't have to be a 'file name'. | |
259 // By default the source string will be compiled into SPIR-V binary | |
260 // and a shaderc_spv_module will be returned to hold the results of the | |
261 // compilation. When disassembly mode or preprocessing only mode is enabled | |
262 // in the additional_options, the source string will be compiled into char | |
263 // strings and held by the returned shaderc_spv_module. The entry_point_name | |
264 // null-terminated string defines the name of the entry point to associate | |
265 // with this GLSL source. If the additional_options parameter is not NULL, | |
266 // then the compilation is modified by any options present. May be safely | |
267 // called from multiple threads without explicit synchronization. If there | |
268 // was failure in allocating the compiler object NULL will be returned. | |
269 shaderc_spv_module_t shaderc_compile_into_spv( | |
270 const shaderc_compiler_t compiler, const char* source_text, | |
271 size_t source_text_size, shaderc_shader_kind shader_kind, | |
272 const char* input_file_name, const char* entry_point_name, | |
273 const shaderc_compile_options_t additional_options); | |
274 | |
275 // The following functions, operating on shaderc_spv_module_t objects, offer | |
276 // only the basic thread-safety guarantee. | |
277 | |
278 // Releases the resources held by module. It is invalid to use module for any | |
279 // further operations. | |
280 void shaderc_module_release(shaderc_spv_module_t module); | |
281 | |
282 // Returns true if the result in module was a successful compilation. | |
283 bool shaderc_module_get_success(const shaderc_spv_module_t module); | |
284 | |
285 // Returns the number of bytes in a SPIR-V module result string. When the module | |
286 // is compiled with disassembly mode or preprocessing only mode, the result | |
287 // string is a char string. Otherwise, the result string is binary string. | |
288 size_t shaderc_module_get_length(const shaderc_spv_module_t module); | |
289 | |
290 // Returns the number of warnings generated during the compilation. | |
291 size_t shaderc_module_get_num_warnings(const shaderc_spv_module_t module); | |
292 | |
293 // Returns the number of errors generated during the compilation. | |
294 size_t shaderc_module_get_num_errors(const shaderc_spv_module_t module); | |
295 | |
296 // Returns the compilation status, indicating whether the compilation succeeded, | |
297 // or failed due to some reasons, like invalid shader stage or compilation | |
298 // errors. | |
299 shaderc_compilation_status shaderc_module_get_compilation_status( | |
300 const shaderc_spv_module_t); | |
301 | |
302 // Returns a pointer to the start of the SPIR-V bytes, either SPIR-V binary or | |
303 // char string. When the source string is compiled into SPIR-V binary, this is | |
304 // guaranteed to be castable to a uint32_t*. If the source string is compiled in | |
305 // disassembly mode or preprocessing only mode, the pointer will point to the | |
306 // result char string. | |
307 const char* shaderc_module_get_bytes(const shaderc_spv_module_t module); | |
308 | |
309 // Returns a null-terminated string that contains any error messages generated | |
310 // during the compilation. | |
311 const char* shaderc_module_get_error_message(const shaderc_spv_module_t module); | |
312 | |
313 // Provides the version & revision of the SPIR-V which will be produced | |
314 void shaderc_get_spv_version(unsigned int* version, unsigned int* revision); | |
315 | |
316 // Parses the version and profile from a given null-terminated string | |
317 // containing both version and profile, like: '450core'. Returns false if | |
318 // the string can not be parsed. Returns true when the parsing succeeds. The | |
319 // parsed version and profile are returned through arguments. | |
320 bool shaderc_parse_version_profile(const char* str, int* version, | |
321 shaderc_profile* profile); | |
322 | |
323 #ifdef __cplusplus | |
324 } | |
325 #endif // __cplusplus | |
326 | |
327 #endif // SHADERC_H_ | |
OLD | NEW |