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 19extern "C" { 20#endif 21 22#include <stdbool.h> 23#include <stddef.h> 24#include <stdint.h> 25 26// Source language kind. 27typedef enum { 28 shaderc_source_language_glsl, 29 shaderc_source_language_hlsl, 30} shaderc_source_language; 31 32typedef enum { 33 // Forced shader kinds. These shader kinds force the compiler to compile the 34 // source code as the specified kind of shader. 35 shaderc_vertex_shader, 36 shaderc_fragment_shader, 37 shaderc_compute_shader, 38 shaderc_geometry_shader, 39 shaderc_tess_control_shader, 40 shaderc_tess_evaluation_shader, 41 42 shaderc_glsl_vertex_shader = shaderc_vertex_shader, 43 shaderc_glsl_fragment_shader = shaderc_fragment_shader, 44 shaderc_glsl_compute_shader = shaderc_compute_shader, 45 shaderc_glsl_geometry_shader = shaderc_geometry_shader, 46 shaderc_glsl_tess_control_shader = shaderc_tess_control_shader, 47 shaderc_glsl_tess_evaluation_shader = shaderc_tess_evaluation_shader, 48 // Deduce the shader kind from #pragma annotation in the source code. Compiler 49 // will emit error if #pragma annotation is not found. 50 shaderc_glsl_infer_from_source, 51 // Default shader kinds. Compiler will fall back to compile the source code as 52 // the specified kind of shader when #pragma annotation is not found in the 53 // source code. 54 shaderc_glsl_default_vertex_shader, 55 shaderc_glsl_default_fragment_shader, 56 shaderc_glsl_default_compute_shader, 57 shaderc_glsl_default_geometry_shader, 58 shaderc_glsl_default_tess_control_shader, 59 shaderc_glsl_default_tess_evaluation_shader, 60 shaderc_spirv_assembly, 61} shaderc_shader_kind; 62 63typedef enum { 64 shaderc_target_env_vulkan, // create SPIR-V under Vulkan semantics 65 shaderc_target_env_opengl, // create SPIR-V under OpenGL semantics 66 shaderc_target_env_opengl_compat, // create SPIR-V under OpenGL semantics, 67 // including compatibility profile 68 // functions 69 shaderc_target_env_default = shaderc_target_env_vulkan 70} shaderc_target_env; 71 72typedef enum { 73 shaderc_profile_none, // Used if and only if GLSL version did not specify 74 // profiles. 75 shaderc_profile_core, 76 shaderc_profile_compatibility, 77 shaderc_profile_es, 78} shaderc_profile; 79 80// Indicate the status of a compilation. 81typedef enum { 82 shaderc_compilation_status_success = 0, 83 shaderc_compilation_status_invalid_stage, // error stage deduction 84 shaderc_compilation_status_compilation_error, 85 shaderc_compilation_status_internal_error, // unexpected failure 86 shaderc_compilation_status_null_result_object, 87 shaderc_compilation_status_invalid_assembly, 88} shaderc_compilation_status; 89 90// Optimization level. 91typedef enum { 92 shaderc_optimization_level_zero, // no optimization 93 shaderc_optimization_level_size, // optimize towards reducing code size 94} shaderc_optimization_level; 95 96// Resource limits. 97typedef enum { 98 shaderc_limit_max_lights, 99 shaderc_limit_max_clip_planes, 100 shaderc_limit_max_texture_units, 101 shaderc_limit_max_texture_coords, 102 shaderc_limit_max_vertex_attribs, 103 shaderc_limit_max_vertex_uniform_components, 104 shaderc_limit_max_varying_floats, 105 shaderc_limit_max_vertex_texture_image_units, 106 shaderc_limit_max_combined_texture_image_units, 107 shaderc_limit_max_texture_image_units, 108 shaderc_limit_max_fragment_uniform_components, 109 shaderc_limit_max_draw_buffers, 110 shaderc_limit_max_vertex_uniform_vectors, 111 shaderc_limit_max_varying_vectors, 112 shaderc_limit_max_fragment_uniform_vectors, 113 shaderc_limit_max_vertex_output_vectors, 114 shaderc_limit_max_fragment_input_vectors, 115 shaderc_limit_min_program_texel_offset, 116 shaderc_limit_max_program_texel_offset, 117 shaderc_limit_max_clip_distances, 118 shaderc_limit_max_compute_work_group_count_x, 119 shaderc_limit_max_compute_work_group_count_y, 120 shaderc_limit_max_compute_work_group_count_z, 121 shaderc_limit_max_compute_work_group_size_x, 122 shaderc_limit_max_compute_work_group_size_y, 123 shaderc_limit_max_compute_work_group_size_z, 124 shaderc_limit_max_compute_uniform_components, 125 shaderc_limit_max_compute_texture_image_units, 126 shaderc_limit_max_compute_image_uniforms, 127 shaderc_limit_max_compute_atomic_counters, 128 shaderc_limit_max_compute_atomic_counter_buffers, 129 shaderc_limit_max_varying_components, 130 shaderc_limit_max_vertex_output_components, 131 shaderc_limit_max_geometry_input_components, 132 shaderc_limit_max_geometry_output_components, 133 shaderc_limit_max_fragment_input_components, 134 shaderc_limit_max_image_units, 135 shaderc_limit_max_combined_image_units_and_fragment_outputs, 136 shaderc_limit_max_combined_shader_output_resources, 137 shaderc_limit_max_image_samples, 138 shaderc_limit_max_vertex_image_uniforms, 139 shaderc_limit_max_tess_control_image_uniforms, 140 shaderc_limit_max_tess_evaluation_image_uniforms, 141 shaderc_limit_max_geometry_image_uniforms, 142 shaderc_limit_max_fragment_image_uniforms, 143 shaderc_limit_max_combined_image_uniforms, 144 shaderc_limit_max_geometry_texture_image_units, 145 shaderc_limit_max_geometry_output_vertices, 146 shaderc_limit_max_geometry_total_output_components, 147 shaderc_limit_max_geometry_uniform_components, 148 shaderc_limit_max_geometry_varying_components, 149 shaderc_limit_max_tess_control_input_components, 150 shaderc_limit_max_tess_control_output_components, 151 shaderc_limit_max_tess_control_texture_image_units, 152 shaderc_limit_max_tess_control_uniform_components, 153 shaderc_limit_max_tess_control_total_output_components, 154 shaderc_limit_max_tess_evaluation_input_components, 155 shaderc_limit_max_tess_evaluation_output_components, 156 shaderc_limit_max_tess_evaluation_texture_image_units, 157 shaderc_limit_max_tess_evaluation_uniform_components, 158 shaderc_limit_max_tess_patch_components, 159 shaderc_limit_max_patch_vertices, 160 shaderc_limit_max_tess_gen_level, 161 shaderc_limit_max_viewports, 162 shaderc_limit_max_vertex_atomic_counters, 163 shaderc_limit_max_tess_control_atomic_counters, 164 shaderc_limit_max_tess_evaluation_atomic_counters, 165 shaderc_limit_max_geometry_atomic_counters, 166 shaderc_limit_max_fragment_atomic_counters, 167 shaderc_limit_max_combined_atomic_counters, 168 shaderc_limit_max_atomic_counter_bindings, 169 shaderc_limit_max_vertex_atomic_counter_buffers, 170 shaderc_limit_max_tess_control_atomic_counter_buffers, 171 shaderc_limit_max_tess_evaluation_atomic_counter_buffers, 172 shaderc_limit_max_geometry_atomic_counter_buffers, 173 shaderc_limit_max_fragment_atomic_counter_buffers, 174 shaderc_limit_max_combined_atomic_counter_buffers, 175 shaderc_limit_max_atomic_counter_buffer_size, 176 shaderc_limit_max_transform_feedback_buffers, 177 shaderc_limit_max_transform_feedback_interleaved_components, 178 shaderc_limit_max_cull_distances, 179 shaderc_limit_max_combined_clip_and_cull_distances, 180 shaderc_limit_max_samples, 181} shaderc_limit; 182 183// Uniform resource kinds. 184// In Vulkan, uniform resources are bound to the pipeline via descriptors 185// with numbered bindings and sets. 186typedef enum { 187 // Image and image buffer. 188 shaderc_uniform_kind_image, 189 // Pure sampler. 190 shaderc_uniform_kind_sampler, 191 // Sampled texture in GLSL, and Shader Resource View in HLSL. 192 shaderc_uniform_kind_texture, 193 // Uniform Buffer Object (UBO) in GLSL. Cbuffer in HLSL. 194 shaderc_uniform_kind_buffer, 195 // Shader Storage Buffer Object (SSBO) in GLSL. 196 shaderc_uniform_kind_storage_buffer, 197 // Unordered Access View, in HLSL. (Writable storage image or storage 198 // buffer.) 199 shaderc_uniform_kind_unordered_access_view, 200} shaderc_uniform_kind; 201 202// Usage examples: 203// 204// Aggressively release compiler resources, but spend time in initialization 205// for each new use. 206// shaderc_compiler_t compiler = shaderc_compiler_initialize(); 207// shaderc_compilation_result_t result = shaderc_compile_into_spv( 208// compiler, "#version 450\nvoid main() {}", 27, 209// shaderc_glsl_vertex_shader, "main.vert", "main", nullptr); 210// // Do stuff with compilation results. 211// shaderc_result_release(result); 212// shaderc_compiler_release(compiler); 213// 214// Keep the compiler object around for a long time, but pay for extra space 215// occupied. 216// shaderc_compiler_t compiler = shaderc_compiler_initialize(); 217// // On the same, other or multiple simultaneous threads. 218// shaderc_compilation_result_t result = shaderc_compile_into_spv( 219// compiler, "#version 450\nvoid main() {}", 27, 220// shaderc_glsl_vertex_shader, "main.vert", "main", nullptr); 221// // Do stuff with compilation results. 222// shaderc_result_release(result); 223// // Once no more compilations are to happen. 224// shaderc_compiler_release(compiler); 225 226// An opaque handle to an object that manages all compiler state. 227typedef struct shaderc_compiler* shaderc_compiler_t; 228 229// Returns a shaderc_compiler_t that can be used to compile modules. 230// A return of NULL indicates that there was an error initializing the compiler. 231// Any function operating on shaderc_compiler_t must offer the basic 232// thread-safety guarantee. 233// [http://herbsutter.com/2014/01/13/gotw-95-solution-thread-safety-and-synchronization/] 234// That is: concurrent invocation of these functions on DIFFERENT objects needs 235// no synchronization; concurrent invocation of these functions on the SAME 236// object requires synchronization IF AND ONLY IF some of them take a non-const 237// argument. 238shaderc_compiler_t shaderc_compiler_initialize(void); 239 240// Releases the resources held by the shaderc_compiler_t. 241// After this call it is invalid to make any future calls to functions 242// involving this shaderc_compiler_t. 243void shaderc_compiler_release(shaderc_compiler_t); 244 245// An opaque handle to an object that manages options to a single compilation 246// result. 247typedef struct shaderc_compile_options* shaderc_compile_options_t; 248 249// Returns a default-initialized shaderc_compile_options_t that can be used 250// to modify the functionality of a compiled module. 251// A return of NULL indicates that there was an error initializing the options. 252// Any function operating on shaderc_compile_options_t must offer the 253// basic thread-safety guarantee. 254shaderc_compile_options_t shaderc_compile_options_initialize(void); 255 256// Returns a copy of the given shaderc_compile_options_t. 257// If NULL is passed as the parameter the call is the same as 258// shaderc_compile_options_init. 259shaderc_compile_options_t shaderc_compile_options_clone( 260 const shaderc_compile_options_t options); 261 262// Releases the compilation options. It is invalid to use the given 263// shaderc_compile_options_t object in any future calls. It is safe to pass 264// NULL to this function, and doing such will have no effect. 265void shaderc_compile_options_release(shaderc_compile_options_t options); 266 267// Adds a predefined macro to the compilation options. This has the same 268// effect as passing -Dname=value to the command-line compiler. If value 269// is NULL, it has the same effect as passing -Dname to the command-line 270// compiler. If a macro definition with the same name has previously been 271// added, the value is replaced with the new value. The macro name and 272// value are passed in with char pointers, which point to their data, and 273// the lengths of their data. The strings that the name and value pointers 274// point to must remain valid for the duration of the call, but can be 275// modified or deleted after this function has returned. In case of adding 276// a valueless macro, the value argument should be a null pointer or the 277// value_length should be 0u. 278void shaderc_compile_options_add_macro_definition( 279 shaderc_compile_options_t options, const char* name, size_t name_length, 280 const char* value, size_t value_length); 281 282// Sets the source language. The default is GLSL. 283void shaderc_compile_options_set_source_language( 284 shaderc_compile_options_t options, shaderc_source_language lang); 285 286// Sets the compiler mode to generate debug information in the output. 287void shaderc_compile_options_set_generate_debug_info( 288 shaderc_compile_options_t options); 289 290// Sets the compiler optimization level to the given level. Only the last one 291// takes effect if multiple calls of this function exist. 292void shaderc_compile_options_set_optimization_level( 293 shaderc_compile_options_t options, shaderc_optimization_level level); 294 295// Forces the GLSL language version and profile to a given pair. The version 296// number is the same as would appear in the #version annotation in the source. 297// Version and profile specified here overrides the #version annotation in the 298// source. Use profile: 'shaderc_profile_none' for GLSL versions that do not 299// define profiles, e.g. versions below 150. 300void shaderc_compile_options_set_forced_version_profile( 301 shaderc_compile_options_t options, int version, shaderc_profile profile); 302 303// Source text inclusion via #include is supported with a pair of callbacks 304// to an "includer" on the client side. The first callback processes an 305// inclusion request, and returns an include result. The includer owns 306// the contents of the result, and those contents must remain valid until the 307// second callback is invoked to release the result. Both callbacks take a 308// user_data argument to specify the client context. 309// To return an error, set the source_name to an empty string and put your 310// error message in content. 311 312// An include result. 313typedef struct shaderc_include_result { 314 // The name of the source file. The name should be fully resolved 315 // in the sense that it should be a unique name in the context of the 316 // includer. For example, if the includer maps source names to files in 317 // a filesystem, then this name should be the absolute path of the file. 318 // For a failed inclusion, this string is empty. 319 const char* source_name; 320 size_t source_name_length; 321 // The text contents of the source file in the normal case. 322 // For a failed inclusion, this contains the error message. 323 const char* content; 324 size_t content_length; 325 // User data to be passed along with this request. 326 void* user_data; 327} shaderc_include_result; 328 329// The kinds of include requests. 330enum shaderc_include_type { 331 shaderc_include_type_relative, // E.g. #include "source" 332 shaderc_include_type_standard // E.g. #include <source> 333}; 334 335// An includer callback type for mapping an #include request to an include 336// result. The user_data parameter specifies the client context. The 337// requested_source parameter specifies the name of the source being requested. 338// The type parameter specifies the kind of inclusion request being made. 339// The requesting_source parameter specifies the name of the source containing 340// the #include request. The includer owns the result object and its contents, 341// and both must remain valid until the release callback is called on the result 342// object. 343typedef shaderc_include_result* (*shaderc_include_resolve_fn)( 344 void* user_data, const char* requested_source, int type, 345 const char* requesting_source, size_t include_depth); 346 347// An includer callback type for destroying an include result. 348typedef void (*shaderc_include_result_release_fn)( 349 void* user_data, shaderc_include_result* include_result); 350 351// Sets includer callback functions. 352void shaderc_compile_options_set_include_callbacks( 353 shaderc_compile_options_t options, shaderc_include_resolve_fn resolver, 354 shaderc_include_result_release_fn result_releaser, void* user_data); 355 356// Sets the compiler mode to suppress warnings, overriding warnings-as-errors 357// mode. When both suppress-warnings and warnings-as-errors modes are 358// turned on, warning messages will be inhibited, and will not be emitted 359// as error messages. 360void shaderc_compile_options_set_suppress_warnings( 361 shaderc_compile_options_t options); 362 363// Sets the target shader environment, affecting which warnings or errors will 364// be issued. The version will be for distinguishing between different versions 365// of the target environment. "0" is the only supported version at this point 366void shaderc_compile_options_set_target_env(shaderc_compile_options_t options, 367 shaderc_target_env target, 368 uint32_t version); 369 370// Sets the compiler mode to treat all warnings as errors. Note the 371// suppress-warnings mode overrides this option, i.e. if both 372// warning-as-errors and suppress-warnings modes are set, warnings will not 373// be emitted as error messages. 374void shaderc_compile_options_set_warnings_as_errors( 375 shaderc_compile_options_t options); 376 377// Sets a resource limit. 378void shaderc_compile_options_set_limit( 379 shaderc_compile_options_t options, shaderc_limit limit, int value); 380 381// Sets whether the compiler should automatically assign bindings to uniforms 382// that aren't already explicitly bound in the shader source. 383void shaderc_compile_options_set_auto_bind_uniforms( 384 shaderc_compile_options_t options, bool auto_bind); 385 386// Sets whether the compiler should use HLSL IO mapping rules for bindings. 387// Defaults to false. 388void shaderc_compile_options_set_hlsl_io_mapping( 389 shaderc_compile_options_t options, bool hlsl_iomap); 390 391// Sets whether the compiler should determine block member offsets using HLSL 392// packing rules instead of standard GLSL rules. Defaults to false. Only 393// affects GLSL compilation. HLSL rules are always used when compiling HLSL. 394void shaderc_compile_options_set_hlsl_offsets( 395 shaderc_compile_options_t options, bool hlsl_offsets); 396 397// Sets the base binding number used for for a uniform resource type when 398// automatically assigning bindings. For GLSL compilation, sets the lowest 399// automatically assigned number. For HLSL compilation, the regsiter number 400// assigned to the resource is added to this specified base. 401void shaderc_compile_options_set_binding_base(shaderc_compile_options_t options, 402 shaderc_uniform_kind kind, 403 uint32_t base); 404 405// Like shaderc_compile_options_set_binding_base, but only takes effect when 406// compiling a given shader stage. The stage is assumed to be one of vertex, 407// fragment, tessellation evaluation, tesselation control, geometry, or compute. 408void shaderc_compile_options_set_binding_base_for_stage( 409 shaderc_compile_options_t options, shaderc_shader_kind shader_kind, 410 shaderc_uniform_kind kind, uint32_t base); 411 412// Sets a descriptor set and binding for an HLSL register in the given stage. 413// This method keeps a copy of the string data. 414void shaderc_compile_options_set_hlsl_register_set_and_binding_for_stage( 415 shaderc_compile_options_t options, shaderc_shader_kind shader_kind, 416 const char* reg, const char* set, const char* binding); 417 418// Like shaderc_compile_options_set_hlsl_register_set_and_binding_for_stage, 419// but affects all shader stages. 420void shaderc_compile_options_set_hlsl_register_set_and_binding( 421 shaderc_compile_options_t options, const char* reg, const char* set, 422 const char* binding); 423 424// An opaque handle to the results of a call to any shaderc_compile_into_*() 425// function. 426typedef struct shaderc_compilation_result* shaderc_compilation_result_t; 427 428// Takes a GLSL source string and the associated shader kind, input file 429// name, compiles it according to the given additional_options. If the shader 430// kind is not set to a specified kind, but shaderc_glslc_infer_from_source, 431// the compiler will try to deduce the shader kind from the source 432// string and a failure in deducing will generate an error. Currently only 433// #pragma annotation is supported. If the shader kind is set to one of the 434// default shader kinds, the compiler will fall back to the default shader 435// kind in case it failed to deduce the shader kind from source string. 436// The input_file_name is a null-termintated string. It is used as a tag to 437// identify the source string in cases like emitting error messages. It 438// doesn't have to be a 'file name'. 439// The source string will be compiled into SPIR-V binary and a 440// shaderc_compilation_result will be returned to hold the results. 441// The entry_point_name null-terminated string defines the name of the entry 442// point to associate with this GLSL source. If the additional_options 443// parameter is not null, then the compilation is modified by any options 444// present. May be safely called from multiple threads without explicit 445// synchronization. If there was failure in allocating the compiler object, 446// null will be returned. 447shaderc_compilation_result_t shaderc_compile_into_spv( 448 const shaderc_compiler_t compiler, const char* source_text, 449 size_t source_text_size, shaderc_shader_kind shader_kind, 450 const char* input_file_name, const char* entry_point_name, 451 const shaderc_compile_options_t additional_options); 452 453// Like shaderc_compile_into_spv, but the result contains SPIR-V assembly text 454// instead of a SPIR-V binary module. The SPIR-V assembly syntax is as defined 455// by the SPIRV-Tools open source project. 456shaderc_compilation_result_t shaderc_compile_into_spv_assembly( 457 const shaderc_compiler_t compiler, const char* source_text, 458 size_t source_text_size, shaderc_shader_kind shader_kind, 459 const char* input_file_name, const char* entry_point_name, 460 const shaderc_compile_options_t additional_options); 461 462// Like shaderc_compile_into_spv, but the result contains preprocessed source 463// code instead of a SPIR-V binary module 464shaderc_compilation_result_t shaderc_compile_into_preprocessed_text( 465 const shaderc_compiler_t compiler, const char* source_text, 466 size_t source_text_size, shaderc_shader_kind shader_kind, 467 const char* input_file_name, const char* entry_point_name, 468 const shaderc_compile_options_t additional_options); 469 470// Takes an assembly string of the format defined in the SPIRV-Tools project 471// (https://github.com/KhronosGroup/SPIRV-Tools/blob/master/syntax.md), 472// assembles it into SPIR-V binary and a shaderc_compilation_result will be 473// returned to hold the results. 474// The assembling will pick options suitable for assembling specified in the 475// additional_options parameter. 476// May be safely called from multiple threads without explicit synchronization. 477// If there was failure in allocating the compiler object, null will be 478// returned. 479shaderc_compilation_result_t shaderc_assemble_into_spv( 480 const shaderc_compiler_t compiler, const char* source_assembly, 481 size_t source_assembly_size, 482 const shaderc_compile_options_t additional_options); 483 484// The following functions, operating on shaderc_compilation_result_t objects, 485// offer only the basic thread-safety guarantee. 486 487// Releases the resources held by the result object. It is invalid to use the 488// result object for any further operations. 489void shaderc_result_release(shaderc_compilation_result_t result); 490 491// Returns the number of bytes of the compilation output data in a result 492// object. 493size_t shaderc_result_get_length(const shaderc_compilation_result_t result); 494 495// Returns the number of warnings generated during the compilation. 496size_t shaderc_result_get_num_warnings( 497 const shaderc_compilation_result_t result); 498 499// Returns the number of errors generated during the compilation. 500size_t shaderc_result_get_num_errors(const shaderc_compilation_result_t result); 501 502// Returns the compilation status, indicating whether the compilation succeeded, 503// or failed due to some reasons, like invalid shader stage or compilation 504// errors. 505shaderc_compilation_status shaderc_result_get_compilation_status( 506 const shaderc_compilation_result_t); 507 508// Returns a pointer to the start of the compilation output data bytes, either 509// SPIR-V binary or char string. When the source string is compiled into SPIR-V 510// binary, this is guaranteed to be castable to a uint32_t*. If the result 511// contains assembly text or preprocessed source text, the pointer will point to 512// the resulting array of characters. 513const char* shaderc_result_get_bytes(const shaderc_compilation_result_t result); 514 515// Returns a null-terminated string that contains any error messages generated 516// during the compilation. 517const char* shaderc_result_get_error_message( 518 const shaderc_compilation_result_t result); 519 520// Provides the version & revision of the SPIR-V which will be produced 521void shaderc_get_spv_version(unsigned int* version, unsigned int* revision); 522 523// Parses the version and profile from a given null-terminated string 524// containing both version and profile, like: '450core'. Returns false if 525// the string can not be parsed. Returns true when the parsing succeeds. The 526// parsed version and profile are returned through arguments. 527bool shaderc_parse_version_profile(const char* str, int* version, 528 shaderc_profile* profile); 529 530#ifdef __cplusplus 531} 532#endif // __cplusplus 533 534#endif // SHADERC_SHADERC_H_ 535