third_party/shaderc/shaderc.h

// Copyright 2015 The Shaderc Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#ifndef SHADERC_H_
#define SHADERC_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

typedef enum {
  // Forced shader kinds. These shader kinds force the compiler to compile the
  // source code as the specified kind of shader.
  shaderc_glsl_vertex_shader,
  shaderc_glsl_fragment_shader,
  shaderc_glsl_compute_shader,
  shaderc_glsl_geometry_shader,
  shaderc_glsl_tess_control_shader,
  shaderc_glsl_tess_evaluation_shader,
  // Deduce the shader kind from #pragma annotation in the source code. Compiler
  // will emit error if #pragma annotation is not found.
  shaderc_glsl_infer_from_source,
  // Default shader kinds. Compiler will fall back to compile the source code as
  // the specified kind of shader when #pragma annotation is not found in the
  // source code.
  shaderc_glsl_default_vertex_shader,
  shaderc_glsl_default_fragment_shader,
  shaderc_glsl_default_compute_shader,
  shaderc_glsl_default_geometry_shader,
  shaderc_glsl_default_tess_control_shader,
  shaderc_glsl_default_tess_evaluation_shader,
} shaderc_shader_kind;

typedef enum {
  shaderc_target_env_vulkan,         // create SPIR-V under Vulkan semantics
  shaderc_target_env_opengl,         // create SPIR-V under OpenGL semantics
  shaderc_target_env_opengl_compat,  // create SPIR-V under OpenGL semantics,
                                     // including compatibility profile
                                     // functions
  shaderc_target_env_default = shaderc_target_env_vulkan
} shaderc_target_env;

typedef enum {
  shaderc_profile_none,  // Used if and only if GLSL version did not specify
                         // profiles.
  shaderc_profile_core,
  shaderc_profile_compatibility,
  shaderc_profile_es,
} shaderc_profile;

// Used in the result module (shaderc_spv_module) to indicate the status of an
// compilation.
typedef enum {
  shaderc_compilation_status_success = 0,
  shaderc_compilation_status_invalid_stage,  // error stage deduction
  shaderc_compilation_status_compilation_error,
  shaderc_compilation_status_internal_error, // unexpected failure
  shaderc_compilation_status_null_result_module,
} shaderc_compilation_status;

// Usage examples:
//
// Aggressively release compiler resources, but spend time in initialization
// for each new use.
//      shaderc_compiler_t compiler = shaderc_compiler_initialize();
//      shader_spv_module_t module = shaderc_compile_into_spv(compiler,
//                    "int main() {}", 13, shaderc_glsl_vertex_shader, "main");
//      // Do stuff with module compilation results.
//      shaderc_module_release(module);
//      shaderc_compiler_release(compiler);
//
// Keep the compiler object around for a long time, but pay for extra space
// occupied.
//      shaderc_compiler_t compiler = shaderc_compiler_initialize();
//      // On the same, other or multiple simultaneous threads.
//      shader_spv_module_t module = shaderc_compile_into_spv(compiler,
//                    "int main() {}", 13, shaderc_glsl_vertex_shader, "main");
//      // Do stuff with module compilation results.
//      shaderc_module_release(module);
//      // Once no more compilations are to happen.
//      shaderc_compiler_release(compiler);

// An opaque handle to an object that manages all compiler state.
typedef struct shaderc_compiler* shaderc_compiler_t;

// Returns a shaderc_compiler_t that can be used to compile modules.
// A return of NULL indicates that there was an error initializing the compiler.
// Any function operating on shaderc_compiler_t must offer the basic
// thread-safety guarantee.
// [http://herbsutter.com/2014/01/13/gotw-95-solution-thread-safety-and-synchronization/]
// That is: concurrent invocation of these functions on DIFFERENT objects needs
// no synchronization; concurrent invocation of these functions on the SAME
// object requires synchronization IF AND ONLY IF some of them take a non-const
// argument.
shaderc_compiler_t shaderc_compiler_initialize(void);

// Releases the resources held by the shaderc_compiler_t.
// After this call it is invalid to make any future calls to functions
// involving this shaderc_compiler_t.
void shaderc_compiler_release(shaderc_compiler_t);

// An opaque handle to an object that manages options to a single compilation
// result.
typedef struct shaderc_compile_options* shaderc_compile_options_t;

// Returns a default-initialized shaderc_compile_options_t that can be used
// to modify the functionality of a compiled module.
// A return of NULL indicates that there was an error initializing the options.
// Any function operating on shaderc_compile_options_t must offer the
// basic thread-safety guarantee.
shaderc_compile_options_t shaderc_compile_options_initialize(void);

// Returns a copy of the given shaderc_compile_options_t.
// If NULL is passed as the parameter the call is the same as
// shaderc_compile_options_init.
shaderc_compile_options_t shaderc_compile_options_clone(
    const shaderc_compile_options_t options);

// Releases the compilation options. It is invalid to use the given
// shaderc_compile_options_t object in any future calls. It is safe to pass
// NULL to this function, and doing such will have no effect.
void shaderc_compile_options_release(shaderc_compile_options_t options);

// Adds a predefined macro to the compilation options. This has the
// same effect as passing -Dname=value to the command-line compiler.
// If value is NULL, it has the effect same as passing -Dname to the
// command-line compiler. If a macro definition with the same name has
// previously been added, the value is replaced with the new value.
// The null-terminated strings that the name and value parameters point to
// must remain valid for the duration of the call, but can be modified or
// deleted after this function has returned.
void shaderc_compile_options_add_macro_definition(
    shaderc_compile_options_t options, const char* name, const char* value);

// Sets the compiler mode to generate debug information in the output.
void shaderc_compile_options_set_generate_debug_info(
    shaderc_compile_options_t options);

// Sets the compiler mode to emit a disassembly text instead of a binary. In
// this mode, the byte array result in the shaderc_spv_module returned
// from shaderc_compile_into_spv() will consist of SPIR-V assembly text.
// Note the preprocessing only mode overrides this option, and this option
// overrides the default mode generating a SPIR-V binary.
void shaderc_compile_options_set_disassembly_mode(
    shaderc_compile_options_t options);

// Forces the GLSL language version and profile to a given pair. The version
// number is the same as would appear in the #version annotation in the source.
// Version and profile specified here overrides the #version annotation in the
// source. Use profile: 'shaderc_profile_none' for GLSL versions that do not
// define profiles, e.g. versions below 150.
void shaderc_compile_options_set_forced_version_profile(
    shaderc_compile_options_t options, int version, shaderc_profile profile);

// To support file inclusion, libshaderc invokes a callback into its client to
// resolve the full path and content of the included file.
// The client callback should follow the specified function signature below, and
// it should be passed to libshaderc through the corresponding setter function.
// When the including of a file is done, libshaderc will call another client
// callback to clean up the resources used for the including process. The client
// should implement the clean up method and pass it to libshaderc together with
// the response method.

// The struct that contains the information to be returned to the libshaderc.
// The client-side implemented response method should return a pointer of this
// struct. The underlying data is owned by client code.
struct shaderc_includer_response {
  const char* path;
  size_t path_length;
  const char* content;
  size_t content_length;
};

// The function signature of the client-side implemented response method. It
// returns a pointer to shaderc_includer_response struct.
typedef shaderc_includer_response* (*shaderc_includer_response_get_fn)(
    void* user_data, const char* filename);

// The function signature of the client-side implemented clean-up method.
// Includer will call this callback function when the including process is done
// with the fullpath and content data.
typedef void (*shaderc_includer_response_release_fn)(
    void* user_data, shaderc_includer_response* data);

// Sets the callback functions for the includer. When the includer queries for
// the full path and content of a file, client's method will be called to
// response. And when the query is done, client will be notified to clean up.
// TODO: File inclusion needs to be context-aware.
// e.g.
//  In file: /path/to/main_shader.vert:
//  #include "include/a"
//  In file: /path/to/include/a":
//  #include "b"
//  When compiling /path/to/main_shader.vert, the compiler should be able to
//  go to /path/to/include/b to find the file b.
//  This needs context info from compiler to client includer, and may needs
//  interface changes.
void shaderc_compile_options_set_includer_callbacks(
    shaderc_compile_options_t options, shaderc_includer_response_get_fn getter,
    shaderc_includer_response_release_fn releasor, void* user_data);

// Sets the compiler mode to do only preprocessing. The byte array result in the
// module returned by the compilation is the text of the preprocessed shader.
// This option overrides all other compilation modes, such as disassembly mode
// and the default mode of compilation to SPIR-V binary.
void shaderc_compile_options_set_preprocessing_only_mode(
    shaderc_compile_options_t options);

// Sets the compiler mode to suppress warnings, overriding warnings-as-errors
// mode. When both suppress-warnings and warnings-as-errors modes are
// turned on, warning messages will be inhibited, and will not be emitted
// as error messages.
void shaderc_compile_options_set_suppress_warnings(
    shaderc_compile_options_t options);

// Sets the target shader environment, affecting which warnings or errors will
// be issued.  The version will be for distinguishing between different versions
// of the target environment.  "0" is the only supported version at this point
void shaderc_compile_options_set_target_env(shaderc_compile_options_t options,
                                            shaderc_target_env target,
                                            uint32_t version);

// Sets the compiler mode to treat all warnings as errors. Note the
// suppress-warnings mode overrides this option, i.e. if both
// warning-as-errors and suppress-warnings modes are set, warnings will not
// be emitted as error messages.
void shaderc_compile_options_set_warnings_as_errors(
    shaderc_compile_options_t options);

// An opaque handle to the results of a call to shaderc_compile_into_spv().
typedef struct shaderc_spv_module* shaderc_spv_module_t;

// Takes a GLSL source string and the associated shader kind, input file
// name, compiles it according to the given additional_options. If the shader
// kind is not set to a specified kind, but shaderc_glslc_infer_from_source,
// the compiler will try to deduce the shader kind from the source
// string and a failure in deducing will generate an error. Currently only
// #pragma annotation is supported. If the shader kind is set to one of the
// default shader kinds, the compiler will fall back to the default shader
// kind in case it failed to deduce the shader kind from source string.
// The input_file_name is a null-termintated string. It is used as a tag to
// identify the source string in cases like emitting error messages. It
// doesn't have to be a 'file name'.
// By default the source string will be compiled into SPIR-V binary
// and a shaderc_spv_module will be returned to hold the results of the
// compilation. When disassembly mode or preprocessing only mode is enabled
// in the additional_options, the source string will be compiled into char
// strings and held by the returned shaderc_spv_module.  The entry_point_name
// null-terminated string defines the name of the entry point to associate
// with this GLSL source. If the additional_options parameter is not NULL,
// then the compilation is modified by any options present. May be safely
// called from multiple threads without explicit synchronization. If there
// was failure in allocating the compiler object NULL will be returned.
shaderc_spv_module_t shaderc_compile_into_spv(
    const shaderc_compiler_t compiler, const char* source_text,
    size_t source_text_size, shaderc_shader_kind shader_kind,
    const char* input_file_name, const char* entry_point_name,
    const shaderc_compile_options_t additional_options);

// The following functions, operating on shaderc_spv_module_t objects, offer
// only the basic thread-safety guarantee.

// Releases the resources held by module.  It is invalid to use module for any
// further operations.
void shaderc_module_release(shaderc_spv_module_t module);

// Returns true if the result in module was a successful compilation.
bool shaderc_module_get_success(const shaderc_spv_module_t module);

// Returns the number of bytes in a SPIR-V module result string. When the module
// is compiled with disassembly mode or preprocessing only mode, the result
// string is a char string. Otherwise, the result string is binary string.
size_t shaderc_module_get_length(const shaderc_spv_module_t module);

// Returns the number of warnings generated during the compilation.
size_t shaderc_module_get_num_warnings(const shaderc_spv_module_t module);

// Returns the number of errors generated during the compilation.
size_t shaderc_module_get_num_errors(const shaderc_spv_module_t module);

// Returns the compilation status, indicating whether the compilation succeeded,
// or failed due to some reasons, like invalid shader stage or compilation
// errors.
shaderc_compilation_status shaderc_module_get_compilation_status(
    const shaderc_spv_module_t);

// Returns a pointer to the start of the SPIR-V bytes, either SPIR-V binary or
// char string. When the source string is compiled into SPIR-V binary, this is
// guaranteed to be castable to a uint32_t*. If the source string is compiled in
// disassembly mode or preprocessing only mode, the pointer will point to the
// result char string.
const char* shaderc_module_get_bytes(const shaderc_spv_module_t module);

// Returns a null-terminated string that contains any error messages generated
// during the compilation.
const char* shaderc_module_get_error_message(const shaderc_spv_module_t module);

// Provides the version & revision of the SPIR-V which will be produced
void shaderc_get_spv_version(unsigned int* version, unsigned int* revision);

// Parses the version and profile from a given null-terminated string
// containing both version and profile, like: '450core'. Returns false if
// the string can not be parsed. Returns true when the parsing succeeds. The
// parsed version and profile are returned through arguments.
bool shaderc_parse_version_profile(const char* str, int* version,
                                   shaderc_profile* profile);

#ifdef __cplusplus
}
#endif  // __cplusplus

#endif  // SHADERC_H_