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_SHADERC_H_ |
| 16 #define SHADERC_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 // Indicate the status of a compilation. |
| 67 typedef enum { |
| 68 shaderc_compilation_status_success = 0, |
| 69 shaderc_compilation_status_invalid_stage, // error stage deduction |
| 70 shaderc_compilation_status_compilation_error, |
| 71 shaderc_compilation_status_internal_error, // unexpected failure |
| 72 shaderc_compilation_status_null_result_object, |
| 73 } shaderc_compilation_status; |
| 74 |
| 75 // Usage examples: |
| 76 // |
| 77 // Aggressively release compiler resources, but spend time in initialization |
| 78 // for each new use. |
| 79 // shaderc_compiler_t compiler = shaderc_compiler_initialize(); |
| 80 // shaderc_compilation_result_t result = shaderc_compile_into_spv( |
| 81 // compiler, "int main() {}", 13, shaderc_glsl_vertex_shader, "main"); |
| 82 // // Do stuff with compilation results. |
| 83 // shaderc_result_release(result); |
| 84 // shaderc_compiler_release(compiler); |
| 85 // |
| 86 // Keep the compiler object around for a long time, but pay for extra space |
| 87 // occupied. |
| 88 // shaderc_compiler_t compiler = shaderc_compiler_initialize(); |
| 89 // // On the same, other or multiple simultaneous threads. |
| 90 // shaderc_compilation_result_t result = shaderc_compile_into_spv( |
| 91 // compiler, "int main() {}", 13, shaderc_glsl_vertex_shader, "main"); |
| 92 // // Do stuff with compilation results. |
| 93 // shaderc_result_release(result); |
| 94 // // Once no more compilations are to happen. |
| 95 // shaderc_compiler_release(compiler); |
| 96 |
| 97 // An opaque handle to an object that manages all compiler state. |
| 98 typedef struct shaderc_compiler* shaderc_compiler_t; |
| 99 |
| 100 // Returns a shaderc_compiler_t that can be used to compile modules. |
| 101 // A return of NULL indicates that there was an error initializing the compiler. |
| 102 // Any function operating on shaderc_compiler_t must offer the basic |
| 103 // thread-safety guarantee. |
| 104 // [http://herbsutter.com/2014/01/13/gotw-95-solution-thread-safety-and-synchron
ization/] |
| 105 // That is: concurrent invocation of these functions on DIFFERENT objects needs |
| 106 // no synchronization; concurrent invocation of these functions on the SAME |
| 107 // object requires synchronization IF AND ONLY IF some of them take a non-const |
| 108 // argument. |
| 109 shaderc_compiler_t shaderc_compiler_initialize(void); |
| 110 |
| 111 // Releases the resources held by the shaderc_compiler_t. |
| 112 // After this call it is invalid to make any future calls to functions |
| 113 // involving this shaderc_compiler_t. |
| 114 void shaderc_compiler_release(shaderc_compiler_t); |
| 115 |
| 116 // An opaque handle to an object that manages options to a single compilation |
| 117 // result. |
| 118 typedef struct shaderc_compile_options* shaderc_compile_options_t; |
| 119 |
| 120 // Returns a default-initialized shaderc_compile_options_t that can be used |
| 121 // to modify the functionality of a compiled module. |
| 122 // A return of NULL indicates that there was an error initializing the options. |
| 123 // Any function operating on shaderc_compile_options_t must offer the |
| 124 // basic thread-safety guarantee. |
| 125 shaderc_compile_options_t shaderc_compile_options_initialize(void); |
| 126 |
| 127 // Returns a copy of the given shaderc_compile_options_t. |
| 128 // If NULL is passed as the parameter the call is the same as |
| 129 // shaderc_compile_options_init. |
| 130 shaderc_compile_options_t shaderc_compile_options_clone( |
| 131 const shaderc_compile_options_t options); |
| 132 |
| 133 // Releases the compilation options. It is invalid to use the given |
| 134 // shaderc_compile_options_t object in any future calls. It is safe to pass |
| 135 // NULL to this function, and doing such will have no effect. |
| 136 void shaderc_compile_options_release(shaderc_compile_options_t options); |
| 137 |
| 138 // Adds a predefined macro to the compilation options. This has the same |
| 139 // effect as passing -Dname=value to the command-line compiler. If value |
| 140 // is NULL, it has the same effect as passing -Dname to the command-line |
| 141 // compiler. If a macro definition with the same name has previously been |
| 142 // added, the value is replaced with the new value. The macro name and |
| 143 // value are passed in with char pointers, which point to their data, and |
| 144 // the lengths of their data. The strings that the name and value pointers |
| 145 // point to must remain valid for the duration of the call, but can be |
| 146 // modified or deleted after this function has returned. In case of adding |
| 147 // a valueless macro, the value argument should be a null pointer or the |
| 148 // value_length should be 0u. |
| 149 void shaderc_compile_options_add_macro_definition( |
| 150 shaderc_compile_options_t options, const char* name, size_t name_length, |
| 151 const char* value, size_t value_length); |
| 152 |
| 153 // Sets the compiler mode to generate debug information in the output. |
| 154 void shaderc_compile_options_set_generate_debug_info( |
| 155 shaderc_compile_options_t options); |
| 156 |
| 157 // Forces the GLSL language version and profile to a given pair. The version |
| 158 // number is the same as would appear in the #version annotation in the source. |
| 159 // Version and profile specified here overrides the #version annotation in the |
| 160 // source. Use profile: 'shaderc_profile_none' for GLSL versions that do not |
| 161 // define profiles, e.g. versions below 150. |
| 162 void shaderc_compile_options_set_forced_version_profile( |
| 163 shaderc_compile_options_t options, int version, shaderc_profile profile); |
| 164 |
| 165 // Response to a request for #include content. "Includer" is client code that |
| 166 // resolves #include arguments into objects of this type. |
| 167 // |
| 168 // TODO: File inclusion needs to be context-aware. |
| 169 // e.g. |
| 170 // In file: /path/to/main_shader.vert: |
| 171 // #include "include/a" |
| 172 // In file: /path/to/include/a": |
| 173 // #include "b" |
| 174 // When compiling /path/to/main_shader.vert, the compiler should be able to |
| 175 // go to /path/to/include/b to find the file b. |
| 176 // This needs context info from compiler to client includer, and may needs |
| 177 // interface changes. |
| 178 struct shaderc_includer_response { |
| 179 const char* path; |
| 180 size_t path_length; |
| 181 const char* content; |
| 182 size_t content_length; |
| 183 }; |
| 184 |
| 185 // A function mapping a #include argument to its includer response. The |
| 186 // includer retains memory ownership of the response object. |
| 187 typedef shaderc_includer_response* (*shaderc_includer_response_get_fn)( |
| 188 void* user_data, const char* filename); |
| 189 |
| 190 // A function to destroy an includer response when it's no longer needed. |
| 191 typedef void (*shaderc_includer_response_release_fn)( |
| 192 void* user_data, shaderc_includer_response* data); |
| 193 |
| 194 // Sets includer callback functions. When a compiler encounters a #include in |
| 195 // the source, it will query the includer by invoking getter on user_data and |
| 196 // the #include argument. The includer must respond with a |
| 197 // shaderc_includer_response object that remains valid until releaser is invoked |
| 198 // on it. When the compiler is done processing the response, it will invoke |
| 199 // releaser on user_data and the response pointer. |
| 200 void shaderc_compile_options_set_includer_callbacks( |
| 201 shaderc_compile_options_t options, shaderc_includer_response_get_fn getter, |
| 202 shaderc_includer_response_release_fn releaser, void* user_data); |
| 203 |
| 204 // Sets the compiler mode to suppress warnings, overriding warnings-as-errors |
| 205 // mode. When both suppress-warnings and warnings-as-errors modes are |
| 206 // turned on, warning messages will be inhibited, and will not be emitted |
| 207 // as error messages. |
| 208 void shaderc_compile_options_set_suppress_warnings( |
| 209 shaderc_compile_options_t options); |
| 210 |
| 211 // Sets the target shader environment, affecting which warnings or errors will |
| 212 // be issued. The version will be for distinguishing between different versions |
| 213 // of the target environment. "0" is the only supported version at this point |
| 214 void shaderc_compile_options_set_target_env(shaderc_compile_options_t options, |
| 215 shaderc_target_env target, |
| 216 uint32_t version); |
| 217 |
| 218 // Sets the compiler mode to treat all warnings as errors. Note the |
| 219 // suppress-warnings mode overrides this option, i.e. if both |
| 220 // warning-as-errors and suppress-warnings modes are set, warnings will not |
| 221 // be emitted as error messages. |
| 222 void shaderc_compile_options_set_warnings_as_errors( |
| 223 shaderc_compile_options_t options); |
| 224 |
| 225 // An opaque handle to the results of a call to any shaderc_compile_into_*() |
| 226 // function. |
| 227 typedef struct shaderc_compilation_result* shaderc_compilation_result_t; |
| 228 |
| 229 // Takes a GLSL source string and the associated shader kind, input file |
| 230 // name, compiles it according to the given additional_options. If the shader |
| 231 // kind is not set to a specified kind, but shaderc_glslc_infer_from_source, |
| 232 // the compiler will try to deduce the shader kind from the source |
| 233 // string and a failure in deducing will generate an error. Currently only |
| 234 // #pragma annotation is supported. If the shader kind is set to one of the |
| 235 // default shader kinds, the compiler will fall back to the default shader |
| 236 // kind in case it failed to deduce the shader kind from source string. |
| 237 // The input_file_name is a null-termintated string. It is used as a tag to |
| 238 // identify the source string in cases like emitting error messages. It |
| 239 // doesn't have to be a 'file name'. |
| 240 // The source string will be compiled into SPIR-V binary and a |
| 241 // shaderc_compilation_result will be returned to hold the results. |
| 242 // The entry_point_name null-terminated string defines the name of the entry |
| 243 // point to associate with this GLSL source. If the additional_options |
| 244 // parameter is not null, then the compilation is modified by any options |
| 245 // present. May be safely called from multiple threads without explicit |
| 246 // synchronization. If there was failure in allocating the compiler object, |
| 247 // null will be returned. |
| 248 shaderc_compilation_result_t shaderc_compile_into_spv( |
| 249 const shaderc_compiler_t compiler, const char* source_text, |
| 250 size_t source_text_size, shaderc_shader_kind shader_kind, |
| 251 const char* input_file_name, const char* entry_point_name, |
| 252 const shaderc_compile_options_t additional_options); |
| 253 |
| 254 // Like shaderc_compile_into_spv, but the result contains SPIR-V assembly text |
| 255 // instead of a SPIR-V binary module. The SPIR-V assembly syntax is as defined |
| 256 // by the SPIRV-Tools open source project. |
| 257 shaderc_compilation_result_t shaderc_compile_into_spv_assembly( |
| 258 const shaderc_compiler_t compiler, const char* source_text, |
| 259 size_t source_text_size, shaderc_shader_kind shader_kind, |
| 260 const char* input_file_name, const char* entry_point_name, |
| 261 const shaderc_compile_options_t additional_options); |
| 262 |
| 263 // Like shaderc_compile_into_spv, but the result contains preprocessed source |
| 264 // code instead of a SPIR-V binary module |
| 265 shaderc_compilation_result_t shaderc_compile_into_preprocessed_text( |
| 266 const shaderc_compiler_t compiler, const char* source_text, |
| 267 size_t source_text_size, shaderc_shader_kind shader_kind, |
| 268 const char* input_file_name, const char* entry_point_name, |
| 269 const shaderc_compile_options_t additional_options); |
| 270 |
| 271 // The following functions, operating on shaderc_compilation_result_t objects, |
| 272 // offer only the basic thread-safety guarantee. |
| 273 |
| 274 // Releases the resources held by the result object. It is invalid to use the |
| 275 // result object for any further operations. |
| 276 void shaderc_result_release(shaderc_compilation_result_t result); |
| 277 |
| 278 // Returns the number of bytes of the compilation output data in a result |
| 279 // object. |
| 280 size_t shaderc_result_get_length(const shaderc_compilation_result_t result); |
| 281 |
| 282 // Returns the number of warnings generated during the compilation. |
| 283 size_t shaderc_result_get_num_warnings( |
| 284 const shaderc_compilation_result_t result); |
| 285 |
| 286 // Returns the number of errors generated during the compilation. |
| 287 size_t shaderc_result_get_num_errors(const shaderc_compilation_result_t result); |
| 288 |
| 289 // Returns the compilation status, indicating whether the compilation succeeded, |
| 290 // or failed due to some reasons, like invalid shader stage or compilation |
| 291 // errors. |
| 292 shaderc_compilation_status shaderc_result_get_compilation_status( |
| 293 const shaderc_compilation_result_t); |
| 294 |
| 295 // Returns a pointer to the start of the compilation output data bytes, either |
| 296 // SPIR-V binary or char string. When the source string is compiled into SPIR-V |
| 297 // binary, this is guaranteed to be castable to a uint32_t*. If the result |
| 298 // contains assembly text or preprocessed source text, the pointer will point to |
| 299 // the resulting array of characters. |
| 300 const char* shaderc_result_get_bytes(const shaderc_compilation_result_t result); |
| 301 |
| 302 // Returns a null-terminated string that contains any error messages generated |
| 303 // during the compilation. |
| 304 const char* shaderc_result_get_error_message( |
| 305 const shaderc_compilation_result_t result); |
| 306 |
| 307 // Provides the version & revision of the SPIR-V which will be produced |
| 308 void shaderc_get_spv_version(unsigned int* version, unsigned int* revision); |
| 309 |
| 310 // Parses the version and profile from a given null-terminated string |
| 311 // containing both version and profile, like: '450core'. Returns false if |
| 312 // the string can not be parsed. Returns true when the parsing succeeds. The |
| 313 // parsed version and profile are returned through arguments. |
| 314 bool shaderc_parse_version_profile(const char* str, int* version, |
| 315 shaderc_profile* profile); |
| 316 |
| 317 #ifdef __cplusplus |
| 318 } |
| 319 #endif // __cplusplus |
| 320 |
| 321 #endif // SHADERC_SHADERC_H_ |
OLD | NEW |