michael@0: //
michael@0: // Copyright (c) 2002-2013 The ANGLE Project Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: //
michael@0: #ifndef _COMPILER_INTERFACE_INCLUDED_
michael@0: #define _COMPILER_INTERFACE_INCLUDED_
michael@0: 
michael@0: #if defined(COMPONENT_BUILD)
michael@0: #if defined(_WIN32) || defined(_WIN64)
michael@0: 
michael@0: #if defined(COMPILER_IMPLEMENTATION)
michael@0: #define COMPILER_EXPORT __declspec(dllexport)
michael@0: #else
michael@0: #define COMPILER_EXPORT __declspec(dllimport)
michael@0: #endif  // defined(COMPILER_IMPLEMENTATION)
michael@0: 
michael@0: #else  // defined(WIN32)
michael@0: #define COMPILER_EXPORT __attribute__((visibility("default")))
michael@0: #endif
michael@0: 
michael@0: #else  // defined(COMPONENT_BUILD)
michael@0: #define COMPILER_EXPORT
michael@0: #endif
michael@0: 
michael@0: #include "khrplatform.h"
michael@0: #include <stddef.h>
michael@0: 
michael@0: //
michael@0: // This is the platform independent interface between an OGL driver
michael@0: // and the shading language compiler.
michael@0: //
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: // Version number for shader translation API.
michael@0: // It is incremented everytime the API changes.
michael@0: #define ANGLE_SH_VERSION 110
michael@0: 
michael@0: //
michael@0: // The names of the following enums have been derived by replacing GL prefix
michael@0: // with SH. For example, SH_INFO_LOG_LENGTH is equivalent to GL_INFO_LOG_LENGTH.
michael@0: // The enum values are also equal to the values of their GL counterpart. This
michael@0: // is done to make it easier for applications to use the shader library.
michael@0: //
michael@0: typedef enum {
michael@0:   SH_FRAGMENT_SHADER = 0x8B30,
michael@0:   SH_VERTEX_SHADER   = 0x8B31
michael@0: } ShShaderType;
michael@0: 
michael@0: typedef enum {
michael@0:   SH_GLES2_SPEC = 0x8B40,
michael@0:   SH_WEBGL_SPEC = 0x8B41,
michael@0: 
michael@0:   // The CSS Shaders spec is a subset of the WebGL spec.
michael@0:   //
michael@0:   // In both CSS vertex and fragment shaders, ANGLE:
michael@0:   // (1) Reserves the "css_" prefix.
michael@0:   // (2) Renames the main function to css_main.
michael@0:   // (3) Disables the gl_MaxDrawBuffers built-in.
michael@0:   //
michael@0:   // In CSS fragment shaders, ANGLE:
michael@0:   // (1) Disables the gl_FragColor built-in.
michael@0:   // (2) Disables the gl_FragData built-in.
michael@0:   // (3) Enables the css_MixColor built-in.
michael@0:   // (4) Enables the css_ColorMatrix built-in.
michael@0:   //
michael@0:   // After passing a CSS shader through ANGLE, the browser is expected to append
michael@0:   // a new main function to it.
michael@0:   // This new main function will call the css_main function.
michael@0:   // It may also perform additional operations like varying assignment, texture
michael@0:   // access, and gl_FragColor assignment in order to implement the CSS Shaders
michael@0:   // blend modes.
michael@0:   //
michael@0:   SH_CSS_SHADERS_SPEC = 0x8B42
michael@0: } ShShaderSpec;
michael@0: 
michael@0: typedef enum {
michael@0:   SH_ESSL_OUTPUT   = 0x8B45,
michael@0:   SH_GLSL_OUTPUT   = 0x8B46,
michael@0:   SH_HLSL_OUTPUT   = 0x8B47,
michael@0:   SH_HLSL9_OUTPUT  = 0x8B47,
michael@0:   SH_HLSL11_OUTPUT = 0x8B48
michael@0: } ShShaderOutput;
michael@0: 
michael@0: typedef enum {
michael@0:   SH_NONE           = 0,
michael@0:   SH_INT            = 0x1404,
michael@0:   SH_FLOAT          = 0x1406,
michael@0:   SH_FLOAT_VEC2     = 0x8B50,
michael@0:   SH_FLOAT_VEC3     = 0x8B51,
michael@0:   SH_FLOAT_VEC4     = 0x8B52,
michael@0:   SH_INT_VEC2       = 0x8B53,
michael@0:   SH_INT_VEC3       = 0x8B54,
michael@0:   SH_INT_VEC4       = 0x8B55,
michael@0:   SH_BOOL           = 0x8B56,
michael@0:   SH_BOOL_VEC2      = 0x8B57,
michael@0:   SH_BOOL_VEC3      = 0x8B58,
michael@0:   SH_BOOL_VEC4      = 0x8B59,
michael@0:   SH_FLOAT_MAT2     = 0x8B5A,
michael@0:   SH_FLOAT_MAT3     = 0x8B5B,
michael@0:   SH_FLOAT_MAT4     = 0x8B5C,
michael@0:   SH_SAMPLER_2D     = 0x8B5E,
michael@0:   SH_SAMPLER_CUBE   = 0x8B60,
michael@0:   SH_SAMPLER_2D_RECT_ARB = 0x8B63,
michael@0:   SH_SAMPLER_EXTERNAL_OES = 0x8D66
michael@0: } ShDataType;
michael@0: 
michael@0: typedef enum {
michael@0:   SH_INFO_LOG_LENGTH             =  0x8B84,
michael@0:   SH_OBJECT_CODE_LENGTH          =  0x8B88,  // GL_SHADER_SOURCE_LENGTH
michael@0:   SH_ACTIVE_UNIFORMS             =  0x8B86,
michael@0:   SH_ACTIVE_UNIFORM_MAX_LENGTH   =  0x8B87,
michael@0:   SH_ACTIVE_ATTRIBUTES           =  0x8B89,
michael@0:   SH_ACTIVE_ATTRIBUTE_MAX_LENGTH =  0x8B8A,
michael@0:   SH_MAPPED_NAME_MAX_LENGTH      =  0x6000,
michael@0:   SH_NAME_MAX_LENGTH             =  0x6001,
michael@0:   SH_HASHED_NAME_MAX_LENGTH      =  0x6002,
michael@0:   SH_HASHED_NAMES_COUNT          =  0x6003,
michael@0:   SH_ACTIVE_UNIFORMS_ARRAY       =  0x6004
michael@0: } ShShaderInfo;
michael@0: 
michael@0: // Compile options.
michael@0: typedef enum {
michael@0:   SH_VALIDATE                = 0,
michael@0:   SH_VALIDATE_LOOP_INDEXING  = 0x0001,
michael@0:   SH_INTERMEDIATE_TREE       = 0x0002,
michael@0:   SH_OBJECT_CODE             = 0x0004,
michael@0:   SH_ATTRIBUTES_UNIFORMS     = 0x0008,
michael@0:   SH_LINE_DIRECTIVES         = 0x0010,
michael@0:   SH_SOURCE_PATH             = 0x0020,
michael@0:   SH_MAP_LONG_VARIABLE_NAMES = 0x0040,
michael@0:   SH_UNROLL_FOR_LOOP_WITH_INTEGER_INDEX = 0x0080,
michael@0: 
michael@0:   // This is needed only as a workaround for certain OpenGL driver bugs.
michael@0:   SH_EMULATE_BUILT_IN_FUNCTIONS = 0x0100,
michael@0: 
michael@0:   // This is an experimental flag to enforce restrictions that aim to prevent 
michael@0:   // timing attacks.
michael@0:   // It generates compilation errors for shaders that could expose sensitive
michael@0:   // texture information via the timing channel.
michael@0:   // To use this flag, you must compile the shader under the WebGL spec
michael@0:   // (using the SH_WEBGL_SPEC flag).
michael@0:   SH_TIMING_RESTRICTIONS = 0x0200,
michael@0:     
michael@0:   // This flag prints the dependency graph that is used to enforce timing
michael@0:   // restrictions on fragment shaders.
michael@0:   // This flag only has an effect if all of the following are true:
michael@0:   // - The shader spec is SH_WEBGL_SPEC.
michael@0:   // - The compile options contain the SH_TIMING_RESTRICTIONS flag.
michael@0:   // - The shader type is SH_FRAGMENT_SHADER.
michael@0:   SH_DEPENDENCY_GRAPH = 0x0400,
michael@0: 
michael@0:   // Enforce the GLSL 1.017 Appendix A section 7 packing restrictions.
michael@0:   SH_ENFORCE_PACKING_RESTRICTIONS = 0x0800,
michael@0: 
michael@0:   // This flag ensures all indirect (expression-based) array indexing
michael@0:   // is clamped to the bounds of the array. This ensures, for example,
michael@0:   // that you cannot read off the end of a uniform, whether an array
michael@0:   // vec234, or mat234 type. The ShArrayIndexClampingStrategy enum,
michael@0:   // specified in the ShBuiltInResources when constructing the
michael@0:   // compiler, selects the strategy for the clamping implementation.
michael@0:   SH_CLAMP_INDIRECT_ARRAY_BOUNDS = 0x1000,
michael@0: 
michael@0:   // This flag limits the complexity of an expression.
michael@0:   SH_LIMIT_EXPRESSION_COMPLEXITY = 0x2000,
michael@0: 
michael@0:   // This flag limits the depth of the call stack.
michael@0:   SH_LIMIT_CALL_STACK_DEPTH = 0x4000,
michael@0: } ShCompileOptions;
michael@0: 
michael@0: // Defines alternate strategies for implementing array index clamping.
michael@0: typedef enum {
michael@0:   // Use the clamp intrinsic for array index clamping.
michael@0:   SH_CLAMP_WITH_CLAMP_INTRINSIC = 1,
michael@0: 
michael@0:   // Use a user-defined function for array index clamping.
michael@0:   SH_CLAMP_WITH_USER_DEFINED_INT_CLAMP_FUNCTION
michael@0: } ShArrayIndexClampingStrategy;
michael@0: 
michael@0: //
michael@0: // Driver must call this first, once, before doing any other
michael@0: // compiler operations.
michael@0: // If the function succeeds, the return value is nonzero, else zero.
michael@0: //
michael@0: COMPILER_EXPORT int ShInitialize();
michael@0: //
michael@0: // Driver should call this at shutdown.
michael@0: // If the function succeeds, the return value is nonzero, else zero.
michael@0: //
michael@0: COMPILER_EXPORT int ShFinalize();
michael@0: 
michael@0: // The 64 bits hash function. The first parameter is the input string; the
michael@0: // second parameter is the string length.
michael@0: typedef khronos_uint64_t (*ShHashFunction64)(const char*, size_t);
michael@0: 
michael@0: //
michael@0: // Implementation dependent built-in resources (constants and extensions).
michael@0: // The names for these resources has been obtained by stripping gl_/GL_.
michael@0: //
michael@0: typedef struct
michael@0: {
michael@0:     // Constants.
michael@0:     int MaxVertexAttribs;
michael@0:     int MaxVertexUniformVectors;
michael@0:     int MaxVaryingVectors;
michael@0:     int MaxVertexTextureImageUnits;
michael@0:     int MaxCombinedTextureImageUnits;
michael@0:     int MaxTextureImageUnits;
michael@0:     int MaxFragmentUniformVectors;
michael@0:     int MaxDrawBuffers;
michael@0: 
michael@0:     // Extensions.
michael@0:     // Set to 1 to enable the extension, else 0.
michael@0:     int OES_standard_derivatives;
michael@0:     int OES_EGL_image_external;
michael@0:     int ARB_texture_rectangle;
michael@0:     int EXT_draw_buffers;
michael@0:     int EXT_frag_depth;
michael@0: 
michael@0:     // Set to 1 if highp precision is supported in the fragment language.
michael@0:     // Default is 0.
michael@0:     int FragmentPrecisionHigh;
michael@0: 
michael@0:     // Name Hashing.
michael@0:     // Set a 64 bit hash function to enable user-defined name hashing.
michael@0:     // Default is NULL.
michael@0:     ShHashFunction64 HashFunction;
michael@0: 
michael@0:     // Selects a strategy to use when implementing array index clamping.
michael@0:     // Default is SH_CLAMP_WITH_CLAMP_INTRINSIC.
michael@0:     ShArrayIndexClampingStrategy ArrayIndexClampingStrategy;
michael@0: 
michael@0:     // The maximum complexity an expression can be.
michael@0:     int MaxExpressionComplexity;
michael@0: 
michael@0:     // The maximum depth a call stack can be.
michael@0:     int MaxCallStackDepth;
michael@0: } ShBuiltInResources;
michael@0: 
michael@0: //
michael@0: // Initialize built-in resources with minimum expected values.
michael@0: //
michael@0: COMPILER_EXPORT void ShInitBuiltInResources(ShBuiltInResources* resources);
michael@0: 
michael@0: //
michael@0: // ShHandle held by but opaque to the driver.  It is allocated,
michael@0: // managed, and de-allocated by the compiler. It's contents 
michael@0: // are defined by and used by the compiler.
michael@0: //
michael@0: // If handle creation fails, 0 will be returned.
michael@0: //
michael@0: typedef void* ShHandle;
michael@0: 
michael@0: //
michael@0: // Driver calls these to create and destroy compiler objects.
michael@0: //
michael@0: // Returns the handle of constructed compiler, null if the requested compiler is
michael@0: // not supported.
michael@0: // Parameters:
michael@0: // type: Specifies the type of shader - SH_FRAGMENT_SHADER or SH_VERTEX_SHADER.
michael@0: // spec: Specifies the language spec the compiler must conform to -
michael@0: //       SH_GLES2_SPEC or SH_WEBGL_SPEC.
michael@0: // output: Specifies the output code type - SH_ESSL_OUTPUT, SH_GLSL_OUTPUT,
michael@0: //         SH_HLSL9_OUTPUT or SH_HLSL11_OUTPUT.
michael@0: // resources: Specifies the built-in resources.
michael@0: COMPILER_EXPORT ShHandle ShConstructCompiler(
michael@0:     ShShaderType type,
michael@0:     ShShaderSpec spec,
michael@0:     ShShaderOutput output,
michael@0:     const ShBuiltInResources* resources);
michael@0: COMPILER_EXPORT void ShDestruct(ShHandle handle);
michael@0: 
michael@0: //
michael@0: // Compiles the given shader source.
michael@0: // If the function succeeds, the return value is nonzero, else zero.
michael@0: // Parameters:
michael@0: // handle: Specifies the handle of compiler to be used.
michael@0: // shaderStrings: Specifies an array of pointers to null-terminated strings
michael@0: //                containing the shader source code.
michael@0: // numStrings: Specifies the number of elements in shaderStrings array.
michael@0: // compileOptions: A mask containing the following parameters:
michael@0: // SH_VALIDATE: Validates shader to ensure that it conforms to the spec
michael@0: //              specified during compiler construction.
michael@0: // SH_VALIDATE_LOOP_INDEXING: Validates loop and indexing in the shader to
michael@0: //                            ensure that they do not exceed the minimum
michael@0: //                            functionality mandated in GLSL 1.0 spec,
michael@0: //                            Appendix A, Section 4 and 5.
michael@0: //                            There is no need to specify this parameter when
michael@0: //                            compiling for WebGL - it is implied.
michael@0: // SH_INTERMEDIATE_TREE: Writes intermediate tree to info log.
michael@0: //                       Can be queried by calling ShGetInfoLog().
michael@0: // SH_OBJECT_CODE: Translates intermediate tree to glsl or hlsl shader.
michael@0: //                 Can be queried by calling ShGetObjectCode().
michael@0: // SH_ATTRIBUTES_UNIFORMS: Extracts attributes and uniforms.
michael@0: //                         Can be queried by calling ShGetActiveAttrib() and
michael@0: //                         ShGetActiveUniform().
michael@0: //
michael@0: COMPILER_EXPORT int ShCompile(
michael@0:     const ShHandle handle,
michael@0:     const char* const shaderStrings[],
michael@0:     size_t numStrings,
michael@0:     int compileOptions
michael@0:     );
michael@0: 
michael@0: // Returns a parameter from a compiled shader.
michael@0: // Parameters:
michael@0: // handle: Specifies the compiler
michael@0: // pname: Specifies the parameter to query.
michael@0: // The following parameters are defined:
michael@0: // SH_INFO_LOG_LENGTH: the number of characters in the information log
michael@0: //                     including the null termination character.
michael@0: // SH_OBJECT_CODE_LENGTH: the number of characters in the object code
michael@0: //                        including the null termination character.
michael@0: // SH_ACTIVE_ATTRIBUTES: the number of active attribute variables.
michael@0: // SH_ACTIVE_ATTRIBUTE_MAX_LENGTH: the length of the longest active attribute
michael@0: //                                 variable name including the null
michael@0: //                                 termination character.
michael@0: // SH_ACTIVE_UNIFORMS: the number of active uniform variables.
michael@0: // SH_ACTIVE_UNIFORM_MAX_LENGTH: the length of the longest active uniform
michael@0: //                               variable name including the null
michael@0: //                               termination character.
michael@0: // SH_MAPPED_NAME_MAX_LENGTH: the length of the mapped variable name including
michael@0: //                            the null termination character.
michael@0: // SH_NAME_MAX_LENGTH: the max length of a user-defined name including the
michael@0: //                     null termination character.
michael@0: // SH_HASHED_NAME_MAX_LENGTH: the max length of a hashed name including the
michael@0: //                            null termination character.
michael@0: // SH_HASHED_NAMES_COUNT: the number of hashed names from the latest compile.
michael@0: //
michael@0: // params: Requested parameter
michael@0: COMPILER_EXPORT void ShGetInfo(const ShHandle handle,
michael@0:                                ShShaderInfo pname,
michael@0:                                size_t* params);
michael@0: 
michael@0: // Returns nul-terminated information log for a compiled shader.
michael@0: // Parameters:
michael@0: // handle: Specifies the compiler
michael@0: // infoLog: Specifies an array of characters that is used to return
michael@0: //          the information log. It is assumed that infoLog has enough memory
michael@0: //          to accomodate the information log. The size of the buffer required
michael@0: //          to store the returned information log can be obtained by calling
michael@0: //          ShGetInfo with SH_INFO_LOG_LENGTH.
michael@0: COMPILER_EXPORT void ShGetInfoLog(const ShHandle handle, char* infoLog);
michael@0: 
michael@0: // Returns null-terminated object code for a compiled shader.
michael@0: // Parameters:
michael@0: // handle: Specifies the compiler
michael@0: // infoLog: Specifies an array of characters that is used to return
michael@0: //          the object code. It is assumed that infoLog has enough memory to
michael@0: //          accomodate the object code. The size of the buffer required to
michael@0: //          store the returned object code can be obtained by calling
michael@0: //          ShGetInfo with SH_OBJECT_CODE_LENGTH.
michael@0: COMPILER_EXPORT void ShGetObjectCode(const ShHandle handle, char* objCode);
michael@0: 
michael@0: // Returns information about an active attribute variable.
michael@0: // Parameters:
michael@0: // handle: Specifies the compiler
michael@0: // index: Specifies the index of the attribute variable to be queried.
michael@0: // length: Returns the number of characters actually written in the string
michael@0: //         indicated by name (excluding the null terminator) if a value other
michael@0: //         than NULL is passed.
michael@0: // size: Returns the size of the attribute variable.
michael@0: // type: Returns the data type of the attribute variable.
michael@0: // name: Returns a null terminated string containing the name of the
michael@0: //       attribute variable. It is assumed that name has enough memory to
michael@0: //       accomodate the attribute variable name. The size of the buffer
michael@0: //       required to store the attribute variable name can be obtained by
michael@0: //       calling ShGetInfo with SH_ACTIVE_ATTRIBUTE_MAX_LENGTH.
michael@0: // mappedName: Returns a null terminated string containing the mapped name of
michael@0: //             the attribute variable, It is assumed that mappedName has enough
michael@0: //             memory (SH_MAPPED_NAME_MAX_LENGTH), or NULL if don't care
michael@0: //             about the mapped name. If the name is not mapped, then name and
michael@0: //             mappedName are the same.
michael@0: COMPILER_EXPORT void ShGetActiveAttrib(const ShHandle handle,
michael@0:                                        int index,
michael@0:                                        size_t* length,
michael@0:                                        int* size,
michael@0:                                        ShDataType* type,
michael@0:                                        char* name,
michael@0:                                        char* mappedName);
michael@0: 
michael@0: // Returns information about an active uniform variable.
michael@0: // Parameters:
michael@0: // handle: Specifies the compiler
michael@0: // index: Specifies the index of the uniform variable to be queried.
michael@0: // length: Returns the number of characters actually written in the string
michael@0: //         indicated by name (excluding the null terminator) if a value
michael@0: //         other than NULL is passed.
michael@0: // size: Returns the size of the uniform variable.
michael@0: // type: Returns the data type of the uniform variable.
michael@0: // name: Returns a null terminated string containing the name of the
michael@0: //       uniform variable. It is assumed that name has enough memory to
michael@0: //       accomodate the uniform variable name. The size of the buffer required
michael@0: //       to store the uniform variable name can be obtained by calling
michael@0: //       ShGetInfo with SH_ACTIVE_UNIFORMS_MAX_LENGTH.
michael@0: // mappedName: Returns a null terminated string containing the mapped name of
michael@0: //             the uniform variable, It is assumed that mappedName has enough
michael@0: //             memory (SH_MAPPED_NAME_MAX_LENGTH), or NULL if don't care
michael@0: //             about the mapped name. If the name is not mapped, then name and
michael@0: //             mappedName are the same.
michael@0: COMPILER_EXPORT void ShGetActiveUniform(const ShHandle handle,
michael@0:                                         int index,
michael@0:                                         size_t* length,
michael@0:                                         int* size,
michael@0:                                         ShDataType* type,
michael@0:                                         char* name,
michael@0:                                         char* mappedName);
michael@0: 
michael@0: // Returns information about a name hashing entry from the latest compile.
michael@0: // Parameters:
michael@0: // handle: Specifies the compiler
michael@0: // index: Specifies the index of the name hashing entry to be queried.
michael@0: // name: Returns a null terminated string containing the user defined name.
michael@0: //       It is assumed that name has enough memory to accomodate the name.
michael@0: //       The size of the buffer required to store the user defined name can
michael@0: //       be obtained by calling ShGetInfo with SH_NAME_MAX_LENGTH.
michael@0: // hashedName: Returns a null terminated string containing the hashed name of
michael@0: //             the uniform variable, It is assumed that hashedName has enough
michael@0: //             memory to accomodate the name. The size of the buffer required
michael@0: //             to store the name can be obtained by calling ShGetInfo with
michael@0: //             SH_HASHED_NAME_MAX_LENGTH.
michael@0: COMPILER_EXPORT void ShGetNameHashingEntry(const ShHandle handle,
michael@0:                                            int index,
michael@0:                                            char* name,
michael@0:                                            char* hashedName);
michael@0: 
michael@0: // Returns a parameter from a compiled shader.
michael@0: // Parameters:
michael@0: // handle: Specifies the compiler
michael@0: // pname: Specifies the parameter to query.
michael@0: // The following parameters are defined:
michael@0: // SH_ACTIVE_UNIFORMS_ARRAY: an STL vector of active uniforms. Valid only for
michael@0: //                           HLSL output.
michael@0: // params: Requested parameter
michael@0: COMPILER_EXPORT void ShGetInfoPointer(const ShHandle handle,
michael@0:                                       ShShaderInfo pname,
michael@0:                                       void** params);
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif
michael@0: 
michael@0: #endif // _COMPILER_INTERFACE_INCLUDED_