Home | History | Annotate | Download | only in shaderc
      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_spirv_assembly,
     48 } shaderc_shader_kind;
     49 
     50 typedef enum {
     51   shaderc_target_env_vulkan,         // create SPIR-V under Vulkan semantics
     52   shaderc_target_env_opengl,         // create SPIR-V under OpenGL semantics
     53   shaderc_target_env_opengl_compat,  // create SPIR-V under OpenGL semantics,
     54                                      // including compatibility profile
     55                                      // functions
     56   shaderc_target_env_default = shaderc_target_env_vulkan
     57 } shaderc_target_env;
     58 
     59 typedef enum {
     60   shaderc_profile_none,  // Used if and only if GLSL version did not specify
     61                          // profiles.
     62   shaderc_profile_core,
     63   shaderc_profile_compatibility,
     64   shaderc_profile_es,
     65 } shaderc_profile;
     66 
     67 // Indicate the status of a 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_object,
     74   shaderc_compilation_status_invalid_assembly,
     75 } shaderc_compilation_status;
     76 
     77 // Usage examples:
     78 //
     79 // Aggressively release compiler resources, but spend time in initialization
     80 // for each new use.
     81 //      shaderc_compiler_t compiler = shaderc_compiler_initialize();
     82 //      shaderc_compilation_result_t result = shaderc_compile_into_spv(
     83 //          compiler, "int main() {}", 13, shaderc_glsl_vertex_shader, "main");
     84 //      // Do stuff with compilation results.
     85 //      shaderc_result_release(result);
     86 //      shaderc_compiler_release(compiler);
     87 //
     88 // Keep the compiler object around for a long time, but pay for extra space
     89 // occupied.
     90 //      shaderc_compiler_t compiler = shaderc_compiler_initialize();
     91 //      // On the same, other or multiple simultaneous threads.
     92 //      shaderc_compilation_result_t result = shaderc_compile_into_spv(
     93 //          compiler, "int main() {}", 13, shaderc_glsl_vertex_shader, "main");
     94 //      // Do stuff with compilation results.
     95 //      shaderc_result_release(result);
     96 //      // Once no more compilations are to happen.
     97 //      shaderc_compiler_release(compiler);
     98 
     99 // An opaque handle to an object that manages all compiler state.
    100 typedef struct shaderc_compiler* shaderc_compiler_t;
    101 
    102 // Returns a shaderc_compiler_t that can be used to compile modules.
    103 // A return of NULL indicates that there was an error initializing the compiler.
    104 // Any function operating on shaderc_compiler_t must offer the basic
    105 // thread-safety guarantee.
    106 // [http://herbsutter.com/2014/01/13/gotw-95-solution-thread-safety-and-synchronization/]
    107 // That is: concurrent invocation of these functions on DIFFERENT objects needs
    108 // no synchronization; concurrent invocation of these functions on the SAME
    109 // object requires synchronization IF AND ONLY IF some of them take a non-const
    110 // argument.
    111 shaderc_compiler_t shaderc_compiler_initialize(void);
    112 
    113 // Releases the resources held by the shaderc_compiler_t.
    114 // After this call it is invalid to make any future calls to functions
    115 // involving this shaderc_compiler_t.
    116 void shaderc_compiler_release(shaderc_compiler_t);
    117 
    118 // An opaque handle to an object that manages options to a single compilation
    119 // result.
    120 typedef struct shaderc_compile_options* shaderc_compile_options_t;
    121 
    122 // Returns a default-initialized shaderc_compile_options_t that can be used
    123 // to modify the functionality of a compiled module.
    124 // A return of NULL indicates that there was an error initializing the options.
    125 // Any function operating on shaderc_compile_options_t must offer the
    126 // basic thread-safety guarantee.
    127 shaderc_compile_options_t shaderc_compile_options_initialize(void);
    128 
    129 // Returns a copy of the given shaderc_compile_options_t.
    130 // If NULL is passed as the parameter the call is the same as
    131 // shaderc_compile_options_init.
    132 shaderc_compile_options_t shaderc_compile_options_clone(
    133     const shaderc_compile_options_t options);
    134 
    135 // Releases the compilation options. It is invalid to use the given
    136 // shaderc_compile_options_t object in any future calls. It is safe to pass
    137 // NULL to this function, and doing such will have no effect.
    138 void shaderc_compile_options_release(shaderc_compile_options_t options);
    139 
    140 // Adds a predefined macro to the compilation options. This has the same
    141 // effect as passing -Dname=value to the command-line compiler.  If value
    142 // is NULL, it has the same effect as passing -Dname to the command-line
    143 // compiler. If a macro definition with the same name has previously been
    144 // added, the value is replaced with the new value. The macro name and
    145 // value are passed in with char pointers, which point to their data, and
    146 // the lengths of their data. The strings that the name and value pointers
    147 // point to must remain valid for the duration of the call, but can be
    148 // modified or deleted after this function has returned. In case of adding
    149 // a valueless macro, the value argument should be a null pointer or the
    150 // value_length should be 0u.
    151 void shaderc_compile_options_add_macro_definition(
    152     shaderc_compile_options_t options, const char* name, size_t name_length,
    153     const char* value, size_t value_length);
    154 
    155 // Sets the compiler mode to generate debug information in the output.
    156 void shaderc_compile_options_set_generate_debug_info(
    157     shaderc_compile_options_t options);
    158 
    159 // Forces the GLSL language version and profile to a given pair. The version
    160 // number is the same as would appear in the #version annotation in the source.
    161 // Version and profile specified here overrides the #version annotation in the
    162 // source. Use profile: 'shaderc_profile_none' for GLSL versions that do not
    163 // define profiles, e.g. versions below 150.
    164 void shaderc_compile_options_set_forced_version_profile(
    165     shaderc_compile_options_t options, int version, shaderc_profile profile);
    166 
    167 // Source text inclusion via #include is supported with a pair of callbacks
    168 // to an "includer" on the client side.  The first callback processes an
    169 // inclusion request, and returns an include result.  The includer owns
    170 // the contents of the result, and those contents must remain valid until the
    171 // second callback is invoked to release the result.  Both callbacks take a
    172 // user_data argument to specify the client context.
    173 
    174 // An include result.
    175 typedef struct shaderc_include_result {
    176   // The name of the source file.  The name should be fully resolved
    177   // in the sense that it should be a unique name in the context of the
    178   // includer.  For example, if the includer maps source names to files in
    179   // a filesystem, then this name should be the absolute path of the file.
    180   const char* source_name;
    181   size_t source_name_length;
    182   // The text contents of the source file.
    183   const char* content;
    184   size_t content_length;
    185   // User data to be passed along with this request.
    186   void* user_data;
    187 } shaderc_include_result;
    188 
    189 // The kinds of include requests.
    190 enum shaderc_include_type {
    191   shaderc_include_type_relative,  // E.g. #include "source"
    192   shaderc_include_type_standard   // E.g. #include <source>
    193 };
    194 
    195 // An includer callback type for mapping an #include request to an include
    196 // result.  The user_data parameter specifies the client context.  The
    197 // requested_source parameter specifies the name of the source being requested.
    198 // The type parameter specifies the kind of inclusion request being made.
    199 // The requesting_source parameter specifies the name of the source containing
    200 // the #include request.  The includer owns the result object and its contents,
    201 // and both must remain valid until the release callback is called on the result
    202 // object.
    203 typedef shaderc_include_result* (*shaderc_include_resolve_fn)(
    204     void* user_data, const char* requested_source, int type,
    205     const char* requesting_source, size_t include_depth);
    206 
    207 // An includer callback type for destroying an include result.
    208 typedef void (*shaderc_include_result_release_fn)(
    209     void* user_data, shaderc_include_result* include_result);
    210 
    211 // Sets includer callback functions.
    212 void shaderc_compile_options_set_include_callbacks(
    213     shaderc_compile_options_t options, shaderc_include_resolve_fn resolver,
    214     shaderc_include_result_release_fn result_releaser, void* user_data);
    215 
    216 // Sets the compiler mode to suppress warnings, overriding warnings-as-errors
    217 // mode. When both suppress-warnings and warnings-as-errors modes are
    218 // turned on, warning messages will be inhibited, and will not be emitted
    219 // as error messages.
    220 void shaderc_compile_options_set_suppress_warnings(
    221     shaderc_compile_options_t options);
    222 
    223 // Sets the target shader environment, affecting which warnings or errors will
    224 // be issued.  The version will be for distinguishing between different versions
    225 // of the target environment.  "0" is the only supported version at this point
    226 void shaderc_compile_options_set_target_env(shaderc_compile_options_t options,
    227                                             shaderc_target_env target,
    228                                             uint32_t version);
    229 
    230 // Sets the compiler mode to treat all warnings as errors. Note the
    231 // suppress-warnings mode overrides this option, i.e. if both
    232 // warning-as-errors and suppress-warnings modes are set, warnings will not
    233 // be emitted as error messages.
    234 void shaderc_compile_options_set_warnings_as_errors(
    235     shaderc_compile_options_t options);
    236 
    237 // An opaque handle to the results of a call to any shaderc_compile_into_*()
    238 // function.
    239 typedef struct shaderc_compilation_result* shaderc_compilation_result_t;
    240 
    241 // Takes a GLSL source string and the associated shader kind, input file
    242 // name, compiles it according to the given additional_options. If the shader
    243 // kind is not set to a specified kind, but shaderc_glslc_infer_from_source,
    244 // the compiler will try to deduce the shader kind from the source
    245 // string and a failure in deducing will generate an error. Currently only
    246 // #pragma annotation is supported. If the shader kind is set to one of the
    247 // default shader kinds, the compiler will fall back to the default shader
    248 // kind in case it failed to deduce the shader kind from source string.
    249 // The input_file_name is a null-termintated string. It is used as a tag to
    250 // identify the source string in cases like emitting error messages. It
    251 // doesn't have to be a 'file name'.
    252 // The source string will be compiled into SPIR-V binary and a
    253 // shaderc_compilation_result will be returned to hold the results.
    254 // The entry_point_name null-terminated string defines the name of the entry
    255 // point to associate with this GLSL source. If the additional_options
    256 // parameter is not null, then the compilation is modified by any options
    257 // present.  May be safely called from multiple threads without explicit
    258 // synchronization. If there was failure in allocating the compiler object,
    259 // null will be returned.
    260 shaderc_compilation_result_t shaderc_compile_into_spv(
    261     const shaderc_compiler_t compiler, const char* source_text,
    262     size_t source_text_size, shaderc_shader_kind shader_kind,
    263     const char* input_file_name, const char* entry_point_name,
    264     const shaderc_compile_options_t additional_options);
    265 
    266 // Like shaderc_compile_into_spv, but the result contains SPIR-V assembly text
    267 // instead of a SPIR-V binary module.  The SPIR-V assembly syntax is as defined
    268 // by the SPIRV-Tools open source project.
    269 shaderc_compilation_result_t shaderc_compile_into_spv_assembly(
    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 // Like shaderc_compile_into_spv, but the result contains preprocessed source
    276 // code instead of a SPIR-V binary module
    277 shaderc_compilation_result_t shaderc_compile_into_preprocessed_text(
    278     const shaderc_compiler_t compiler, const char* source_text,
    279     size_t source_text_size, shaderc_shader_kind shader_kind,
    280     const char* input_file_name, const char* entry_point_name,
    281     const shaderc_compile_options_t additional_options);
    282 
    283 // Takes an assembly string of the format defined in the SPIRV-Tools project
    284 // (https://github.com/KhronosGroup/SPIRV-Tools/blob/master/syntax.md),
    285 // assembles it into SPIR-V binary and a shaderc_compilation_result will be
    286 // returned to hold the results.
    287 // May be safely called from multiple threads without explicit synchronization.
    288 // If there was failure in allocating the compiler object, null will be
    289 // returned.
    290 shaderc_compilation_result_t shaderc_assemble_into_spv(
    291     const shaderc_compiler_t compiler, const char* source_assembly,
    292     size_t source_assembly_size);
    293 
    294 // The following functions, operating on shaderc_compilation_result_t objects,
    295 // offer only the basic thread-safety guarantee.
    296 
    297 // Releases the resources held by the result object. It is invalid to use the
    298 // result object for any further operations.
    299 void shaderc_result_release(shaderc_compilation_result_t result);
    300 
    301 // Returns the number of bytes of the compilation output data in a result
    302 // object.
    303 size_t shaderc_result_get_length(const shaderc_compilation_result_t result);
    304 
    305 // Returns the number of warnings generated during the compilation.
    306 size_t shaderc_result_get_num_warnings(
    307     const shaderc_compilation_result_t result);
    308 
    309 // Returns the number of errors generated during the compilation.
    310 size_t shaderc_result_get_num_errors(const shaderc_compilation_result_t result);
    311 
    312 // Returns the compilation status, indicating whether the compilation succeeded,
    313 // or failed due to some reasons, like invalid shader stage or compilation
    314 // errors.
    315 shaderc_compilation_status shaderc_result_get_compilation_status(
    316     const shaderc_compilation_result_t);
    317 
    318 // Returns a pointer to the start of the compilation output data bytes, either
    319 // SPIR-V binary or char string. When the source string is compiled into SPIR-V
    320 // binary, this is guaranteed to be castable to a uint32_t*. If the result
    321 // contains assembly text or preprocessed source text, the pointer will point to
    322 // the resulting array of characters.
    323 const char* shaderc_result_get_bytes(const shaderc_compilation_result_t result);
    324 
    325 // Returns a null-terminated string that contains any error messages generated
    326 // during the compilation.
    327 const char* shaderc_result_get_error_message(
    328     const shaderc_compilation_result_t result);
    329 
    330 // Provides the version & revision of the SPIR-V which will be produced
    331 void shaderc_get_spv_version(unsigned int* version, unsigned int* revision);
    332 
    333 // Parses the version and profile from a given null-terminated string
    334 // containing both version and profile, like: '450core'. Returns false if
    335 // the string can not be parsed. Returns true when the parsing succeeds. The
    336 // parsed version and profile are returned through arguments.
    337 bool shaderc_parse_version_profile(const char* str, int* version,
    338                                    shaderc_profile* profile);
    339 
    340 #ifdef __cplusplus
    341 }
    342 #endif  // __cplusplus
    343 
    344 #endif  // SHADERC_SHADERC_H_
    345