Home | History | Annotate | Download | only in GLSLANG
      1 //
      2 // Copyright (c) 2002-2013 The ANGLE Project Authors. All rights reserved.
      3 // Use of this source code is governed by a BSD-style license that can be
      4 // found in the LICENSE file.
      5 //
      6 #ifndef _COMPILER_INTERFACE_INCLUDED_
      7 #define _COMPILER_INTERFACE_INCLUDED_
      8 
      9 #if defined(COMPONENT_BUILD)
     10 #if defined(_WIN32) || defined(_WIN64)
     11 
     12 #if defined(COMPILER_IMPLEMENTATION)
     13 #define COMPILER_EXPORT __declspec(dllexport)
     14 #else
     15 #define COMPILER_EXPORT __declspec(dllimport)
     16 #endif  // defined(COMPILER_IMPLEMENTATION)
     17 
     18 #else  // defined(WIN32)
     19 #define COMPILER_EXPORT __attribute__((visibility("default")))
     20 #endif
     21 
     22 #else  // defined(COMPONENT_BUILD)
     23 #define COMPILER_EXPORT
     24 #endif
     25 
     26 #include "KHR/khrplatform.h"
     27 #include <stddef.h>
     28 
     29 //
     30 // This is the platform independent interface between an OGL driver
     31 // and the shading language compiler.
     32 //
     33 
     34 #ifdef __cplusplus
     35 extern "C" {
     36 #endif
     37 
     38 // Version number for shader translation API.
     39 // It is incremented everytime the API changes.
     40 #define ANGLE_SH_VERSION 110
     41 
     42 //
     43 // The names of the following enums have been derived by replacing GL prefix
     44 // with SH. For example, SH_INFO_LOG_LENGTH is equivalent to GL_INFO_LOG_LENGTH.
     45 // The enum values are also equal to the values of their GL counterpart. This
     46 // is done to make it easier for applications to use the shader library.
     47 //
     48 typedef enum {
     49   SH_FRAGMENT_SHADER = 0x8B30,
     50   SH_VERTEX_SHADER   = 0x8B31
     51 } ShShaderType;
     52 
     53 typedef enum {
     54   SH_GLES2_SPEC = 0x8B40,
     55   SH_WEBGL_SPEC = 0x8B41,
     56 
     57   // The CSS Shaders spec is a subset of the WebGL spec.
     58   //
     59   // In both CSS vertex and fragment shaders, ANGLE:
     60   // (1) Reserves the "css_" prefix.
     61   // (2) Renames the main function to css_main.
     62   // (3) Disables the gl_MaxDrawBuffers built-in.
     63   //
     64   // In CSS fragment shaders, ANGLE:
     65   // (1) Disables the gl_FragColor built-in.
     66   // (2) Disables the gl_FragData built-in.
     67   // (3) Enables the css_MixColor built-in.
     68   // (4) Enables the css_ColorMatrix built-in.
     69   //
     70   // After passing a CSS shader through ANGLE, the browser is expected to append
     71   // a new main function to it.
     72   // This new main function will call the css_main function.
     73   // It may also perform additional operations like varying assignment, texture
     74   // access, and gl_FragColor assignment in order to implement the CSS Shaders
     75   // blend modes.
     76   //
     77   SH_CSS_SHADERS_SPEC = 0x8B42
     78 } ShShaderSpec;
     79 
     80 typedef enum {
     81   SH_ESSL_OUTPUT   = 0x8B45,
     82   SH_GLSL_OUTPUT   = 0x8B46,
     83   SH_HLSL_OUTPUT   = 0x8B47,
     84   SH_HLSL9_OUTPUT  = 0x8B47,
     85   SH_HLSL11_OUTPUT = 0x8B48
     86 } ShShaderOutput;
     87 
     88 typedef enum {
     89   SH_NONE           = 0,
     90   SH_INT            = 0x1404,
     91   SH_FLOAT          = 0x1406,
     92   SH_FLOAT_VEC2     = 0x8B50,
     93   SH_FLOAT_VEC3     = 0x8B51,
     94   SH_FLOAT_VEC4     = 0x8B52,
     95   SH_INT_VEC2       = 0x8B53,
     96   SH_INT_VEC3       = 0x8B54,
     97   SH_INT_VEC4       = 0x8B55,
     98   SH_BOOL           = 0x8B56,
     99   SH_BOOL_VEC2      = 0x8B57,
    100   SH_BOOL_VEC3      = 0x8B58,
    101   SH_BOOL_VEC4      = 0x8B59,
    102   SH_FLOAT_MAT2     = 0x8B5A,
    103   SH_FLOAT_MAT3     = 0x8B5B,
    104   SH_FLOAT_MAT4     = 0x8B5C,
    105   SH_SAMPLER_2D     = 0x8B5E,
    106   SH_SAMPLER_CUBE   = 0x8B60,
    107   SH_SAMPLER_2D_RECT_ARB = 0x8B63,
    108   SH_SAMPLER_EXTERNAL_OES = 0x8D66
    109 } ShDataType;
    110 
    111 typedef enum {
    112   SH_INFO_LOG_LENGTH             =  0x8B84,
    113   SH_OBJECT_CODE_LENGTH          =  0x8B88,  // GL_SHADER_SOURCE_LENGTH
    114   SH_ACTIVE_UNIFORMS             =  0x8B86,
    115   SH_ACTIVE_UNIFORM_MAX_LENGTH   =  0x8B87,
    116   SH_ACTIVE_ATTRIBUTES           =  0x8B89,
    117   SH_ACTIVE_ATTRIBUTE_MAX_LENGTH =  0x8B8A,
    118   SH_MAPPED_NAME_MAX_LENGTH      =  0x6000,
    119   SH_NAME_MAX_LENGTH             =  0x6001,
    120   SH_HASHED_NAME_MAX_LENGTH      =  0x6002,
    121   SH_HASHED_NAMES_COUNT          =  0x6003,
    122   SH_ACTIVE_UNIFORMS_ARRAY       =  0x6004
    123 } ShShaderInfo;
    124 
    125 // Compile options.
    126 typedef enum {
    127   SH_VALIDATE                = 0,
    128   SH_VALIDATE_LOOP_INDEXING  = 0x0001,
    129   SH_INTERMEDIATE_TREE       = 0x0002,
    130   SH_OBJECT_CODE             = 0x0004,
    131   SH_ATTRIBUTES_UNIFORMS     = 0x0008,
    132   SH_LINE_DIRECTIVES         = 0x0010,
    133   SH_SOURCE_PATH             = 0x0020,
    134   SH_MAP_LONG_VARIABLE_NAMES = 0x0040,
    135   SH_UNROLL_FOR_LOOP_WITH_INTEGER_INDEX = 0x0080,
    136 
    137   // This is needed only as a workaround for certain OpenGL driver bugs.
    138   SH_EMULATE_BUILT_IN_FUNCTIONS = 0x0100,
    139 
    140   // This is an experimental flag to enforce restrictions that aim to prevent
    141   // timing attacks.
    142   // It generates compilation errors for shaders that could expose sensitive
    143   // texture information via the timing channel.
    144   // To use this flag, you must compile the shader under the WebGL spec
    145   // (using the SH_WEBGL_SPEC flag).
    146   SH_TIMING_RESTRICTIONS = 0x0200,
    147 
    148   // This flag prints the dependency graph that is used to enforce timing
    149   // restrictions on fragment shaders.
    150   // This flag only has an effect if all of the following are true:
    151   // - The shader spec is SH_WEBGL_SPEC.
    152   // - The compile options contain the SH_TIMING_RESTRICTIONS flag.
    153   // - The shader type is SH_FRAGMENT_SHADER.
    154   SH_DEPENDENCY_GRAPH = 0x0400,
    155 
    156   // Enforce the GLSL 1.017 Appendix A section 7 packing restrictions.
    157   SH_ENFORCE_PACKING_RESTRICTIONS = 0x0800,
    158 
    159   // This flag ensures all indirect (expression-based) array indexing
    160   // is clamped to the bounds of the array. This ensures, for example,
    161   // that you cannot read off the end of a uniform, whether an array
    162   // vec234, or mat234 type. The ShArrayIndexClampingStrategy enum,
    163   // specified in the ShBuiltInResources when constructing the
    164   // compiler, selects the strategy for the clamping implementation.
    165   SH_CLAMP_INDIRECT_ARRAY_BOUNDS = 0x1000,
    166 
    167   // This flag limits the complexity of an expression.
    168   SH_LIMIT_EXPRESSION_COMPLEXITY = 0x2000,
    169 
    170   // This flag limits the depth of the call stack.
    171   SH_LIMIT_CALL_STACK_DEPTH = 0x4000,
    172 } ShCompileOptions;
    173 
    174 // Defines alternate strategies for implementing array index clamping.
    175 typedef enum {
    176   // Use the clamp intrinsic for array index clamping.
    177   SH_CLAMP_WITH_CLAMP_INTRINSIC = 1,
    178 
    179   // Use a user-defined function for array index clamping.
    180   SH_CLAMP_WITH_USER_DEFINED_INT_CLAMP_FUNCTION
    181 } ShArrayIndexClampingStrategy;
    182 
    183 //
    184 // Driver must call this first, once, before doing any other
    185 // compiler operations.
    186 // If the function succeeds, the return value is nonzero, else zero.
    187 //
    188 COMPILER_EXPORT int ShInitialize();
    189 //
    190 // Driver should call this at shutdown.
    191 // If the function succeeds, the return value is nonzero, else zero.
    192 //
    193 COMPILER_EXPORT int ShFinalize();
    194 
    195 // The 64 bits hash function. The first parameter is the input string; the
    196 // second parameter is the string length.
    197 typedef khronos_uint64_t (*ShHashFunction64)(const char*, size_t);
    198 
    199 //
    200 // Implementation dependent built-in resources (constants and extensions).
    201 // The names for these resources has been obtained by stripping gl_/GL_.
    202 //
    203 typedef struct
    204 {
    205     // Constants.
    206     int MaxVertexAttribs;
    207     int MaxVertexUniformVectors;
    208     int MaxVaryingVectors;
    209     int MaxVertexTextureImageUnits;
    210     int MaxCombinedTextureImageUnits;
    211     int MaxTextureImageUnits;
    212     int MaxFragmentUniformVectors;
    213     int MaxDrawBuffers;
    214 
    215     // Extensions.
    216     // Set to 1 to enable the extension, else 0.
    217     int OES_standard_derivatives;
    218     int OES_EGL_image_external;
    219     int ARB_texture_rectangle;
    220     int EXT_draw_buffers;
    221     int EXT_frag_depth;
    222 
    223     // Set to 1 if highp precision is supported in the fragment language.
    224     // Default is 0.
    225     int FragmentPrecisionHigh;
    226 
    227     // Name Hashing.
    228     // Set a 64 bit hash function to enable user-defined name hashing.
    229     // Default is NULL.
    230     ShHashFunction64 HashFunction;
    231 
    232     // Selects a strategy to use when implementing array index clamping.
    233     // Default is SH_CLAMP_WITH_CLAMP_INTRINSIC.
    234     ShArrayIndexClampingStrategy ArrayIndexClampingStrategy;
    235 
    236     // The maximum complexity an expression can be.
    237     int MaxExpressionComplexity;
    238 
    239     // The maximum depth a call stack can be.
    240     int MaxCallStackDepth;
    241 } ShBuiltInResources;
    242 
    243 //
    244 // Initialize built-in resources with minimum expected values.
    245 //
    246 COMPILER_EXPORT void ShInitBuiltInResources(ShBuiltInResources* resources);
    247 
    248 //
    249 // ShHandle held by but opaque to the driver.  It is allocated,
    250 // managed, and de-allocated by the compiler. It's contents
    251 // are defined by and used by the compiler.
    252 //
    253 // If handle creation fails, 0 will be returned.
    254 //
    255 typedef void* ShHandle;
    256 
    257 //
    258 // Driver calls these to create and destroy compiler objects.
    259 //
    260 // Returns the handle of constructed compiler, null if the requested compiler is
    261 // not supported.
    262 // Parameters:
    263 // type: Specifies the type of shader - SH_FRAGMENT_SHADER or SH_VERTEX_SHADER.
    264 // spec: Specifies the language spec the compiler must conform to -
    265 //       SH_GLES2_SPEC or SH_WEBGL_SPEC.
    266 // output: Specifies the output code type - SH_ESSL_OUTPUT, SH_GLSL_OUTPUT,
    267 //         SH_HLSL9_OUTPUT or SH_HLSL11_OUTPUT.
    268 // resources: Specifies the built-in resources.
    269 COMPILER_EXPORT ShHandle ShConstructCompiler(
    270     ShShaderType type,
    271     ShShaderSpec spec,
    272     ShShaderOutput output,
    273     const ShBuiltInResources* resources);
    274 COMPILER_EXPORT void ShDestruct(ShHandle handle);
    275 
    276 //
    277 // Compiles the given shader source.
    278 // If the function succeeds, the return value is nonzero, else zero.
    279 // Parameters:
    280 // handle: Specifies the handle of compiler to be used.
    281 // shaderStrings: Specifies an array of pointers to null-terminated strings
    282 //                containing the shader source code.
    283 // numStrings: Specifies the number of elements in shaderStrings array.
    284 // compileOptions: A mask containing the following parameters:
    285 // SH_VALIDATE: Validates shader to ensure that it conforms to the spec
    286 //              specified during compiler construction.
    287 // SH_VALIDATE_LOOP_INDEXING: Validates loop and indexing in the shader to
    288 //                            ensure that they do not exceed the minimum
    289 //                            functionality mandated in GLSL 1.0 spec,
    290 //                            Appendix A, Section 4 and 5.
    291 //                            There is no need to specify this parameter when
    292 //                            compiling for WebGL - it is implied.
    293 // SH_INTERMEDIATE_TREE: Writes intermediate tree to info log.
    294 //                       Can be queried by calling ShGetInfoLog().
    295 // SH_OBJECT_CODE: Translates intermediate tree to glsl or hlsl shader.
    296 //                 Can be queried by calling ShGetObjectCode().
    297 // SH_ATTRIBUTES_UNIFORMS: Extracts attributes and uniforms.
    298 //                         Can be queried by calling ShGetActiveAttrib() and
    299 //                         ShGetActiveUniform().
    300 //
    301 COMPILER_EXPORT int ShCompile(
    302     const ShHandle handle,
    303     const char* const shaderStrings[],
    304     size_t numStrings,
    305     int compileOptions
    306     );
    307 
    308 // Returns a parameter from a compiled shader.
    309 // Parameters:
    310 // handle: Specifies the compiler
    311 // pname: Specifies the parameter to query.
    312 // The following parameters are defined:
    313 // SH_INFO_LOG_LENGTH: the number of characters in the information log
    314 //                     including the null termination character.
    315 // SH_OBJECT_CODE_LENGTH: the number of characters in the object code
    316 //                        including the null termination character.
    317 // SH_ACTIVE_ATTRIBUTES: the number of active attribute variables.
    318 // SH_ACTIVE_ATTRIBUTE_MAX_LENGTH: the length of the longest active attribute
    319 //                                 variable name including the null
    320 //                                 termination character.
    321 // SH_ACTIVE_UNIFORMS: the number of active uniform variables.
    322 // SH_ACTIVE_UNIFORM_MAX_LENGTH: the length of the longest active uniform
    323 //                               variable name including the null
    324 //                               termination character.
    325 // SH_MAPPED_NAME_MAX_LENGTH: the length of the mapped variable name including
    326 //                            the null termination character.
    327 // SH_NAME_MAX_LENGTH: the max length of a user-defined name including the
    328 //                     null termination character.
    329 // SH_HASHED_NAME_MAX_LENGTH: the max length of a hashed name including the
    330 //                            null termination character.
    331 // SH_HASHED_NAMES_COUNT: the number of hashed names from the latest compile.
    332 //
    333 // params: Requested parameter
    334 COMPILER_EXPORT void ShGetInfo(const ShHandle handle,
    335                                ShShaderInfo pname,
    336                                size_t* params);
    337 
    338 // Returns nul-terminated information log for a compiled shader.
    339 // Parameters:
    340 // handle: Specifies the compiler
    341 // infoLog: Specifies an array of characters that is used to return
    342 //          the information log. It is assumed that infoLog has enough memory
    343 //          to accomodate the information log. The size of the buffer required
    344 //          to store the returned information log can be obtained by calling
    345 //          ShGetInfo with SH_INFO_LOG_LENGTH.
    346 COMPILER_EXPORT void ShGetInfoLog(const ShHandle handle, char* infoLog);
    347 
    348 // Returns null-terminated object code for a compiled shader.
    349 // Parameters:
    350 // handle: Specifies the compiler
    351 // infoLog: Specifies an array of characters that is used to return
    352 //          the object code. It is assumed that infoLog has enough memory to
    353 //          accomodate the object code. The size of the buffer required to
    354 //          store the returned object code can be obtained by calling
    355 //          ShGetInfo with SH_OBJECT_CODE_LENGTH.
    356 COMPILER_EXPORT void ShGetObjectCode(const ShHandle handle, char* objCode);
    357 
    358 // Returns information about an active attribute variable.
    359 // Parameters:
    360 // handle: Specifies the compiler
    361 // index: Specifies the index of the attribute variable to be queried.
    362 // length: Returns the number of characters actually written in the string
    363 //         indicated by name (excluding the null terminator) if a value other
    364 //         than NULL is passed.
    365 // size: Returns the size of the attribute variable.
    366 // type: Returns the data type of the attribute variable.
    367 // name: Returns a null terminated string containing the name of the
    368 //       attribute variable. It is assumed that name has enough memory to
    369 //       accomodate the attribute variable name. The size of the buffer
    370 //       required to store the attribute variable name can be obtained by
    371 //       calling ShGetInfo with SH_ACTIVE_ATTRIBUTE_MAX_LENGTH.
    372 // mappedName: Returns a null terminated string containing the mapped name of
    373 //             the attribute variable, It is assumed that mappedName has enough
    374 //             memory (SH_MAPPED_NAME_MAX_LENGTH), or NULL if don't care
    375 //             about the mapped name. If the name is not mapped, then name and
    376 //             mappedName are the same.
    377 COMPILER_EXPORT void ShGetActiveAttrib(const ShHandle handle,
    378                                        int index,
    379                                        size_t* length,
    380                                        int* size,
    381                                        ShDataType* type,
    382                                        char* name,
    383                                        char* mappedName);
    384 
    385 // Returns information about an active uniform variable.
    386 // Parameters:
    387 // handle: Specifies the compiler
    388 // index: Specifies the index of the uniform variable to be queried.
    389 // length: Returns the number of characters actually written in the string
    390 //         indicated by name (excluding the null terminator) if a value
    391 //         other than NULL is passed.
    392 // size: Returns the size of the uniform variable.
    393 // type: Returns the data type of the uniform variable.
    394 // name: Returns a null terminated string containing the name of the
    395 //       uniform variable. It is assumed that name has enough memory to
    396 //       accomodate the uniform variable name. The size of the buffer required
    397 //       to store the uniform variable name can be obtained by calling
    398 //       ShGetInfo with SH_ACTIVE_UNIFORMS_MAX_LENGTH.
    399 // mappedName: Returns a null terminated string containing the mapped name of
    400 //             the uniform variable, It is assumed that mappedName has enough
    401 //             memory (SH_MAPPED_NAME_MAX_LENGTH), or NULL if don't care
    402 //             about the mapped name. If the name is not mapped, then name and
    403 //             mappedName are the same.
    404 COMPILER_EXPORT void ShGetActiveUniform(const ShHandle handle,
    405                                         int index,
    406                                         size_t* length,
    407                                         int* size,
    408                                         ShDataType* type,
    409                                         char* name,
    410                                         char* mappedName);
    411 
    412 // Returns information about a name hashing entry from the latest compile.
    413 // Parameters:
    414 // handle: Specifies the compiler
    415 // index: Specifies the index of the name hashing entry to be queried.
    416 // name: Returns a null terminated string containing the user defined name.
    417 //       It is assumed that name has enough memory to accomodate the name.
    418 //       The size of the buffer required to store the user defined name can
    419 //       be obtained by calling ShGetInfo with SH_NAME_MAX_LENGTH.
    420 // hashedName: Returns a null terminated string containing the hashed name of
    421 //             the uniform variable, It is assumed that hashedName has enough
    422 //             memory to accomodate the name. The size of the buffer required
    423 //             to store the name can be obtained by calling ShGetInfo with
    424 //             SH_HASHED_NAME_MAX_LENGTH.
    425 COMPILER_EXPORT void ShGetNameHashingEntry(const ShHandle handle,
    426                                            int index,
    427                                            char* name,
    428                                            char* hashedName);
    429 
    430 // Returns a parameter from a compiled shader.
    431 // Parameters:
    432 // handle: Specifies the compiler
    433 // pname: Specifies the parameter to query.
    434 // The following parameters are defined:
    435 // SH_ACTIVE_UNIFORMS_ARRAY: an STL vector of active uniforms. Valid only for
    436 //                           HLSL output.
    437 // params: Requested parameter
    438 COMPILER_EXPORT void ShGetInfoPointer(const ShHandle handle,
    439                                       ShShaderInfo pname,
    440                                       void** params);
    441 
    442 #ifdef __cplusplus
    443 }
    444 #endif
    445 
    446 #endif // _COMPILER_INTERFACE_INCLUDED_
    447