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) && !defined(ANGLE_TRANSLATOR_STATIC) 10#if defined(_WIN32) || defined(_WIN64) 11 12#if defined(ANGLE_TRANSLATOR_IMPLEMENTATION) 13#define COMPILER_EXPORT __declspec(dllexport) 14#else 15#define COMPILER_EXPORT __declspec(dllimport) 16#endif // defined(ANGLE_TRANSLATOR_IMPLEMENTATION) 17 18#else // defined(_WIN32) || defined(_WIN64) 19#define COMPILER_EXPORT __attribute__((visibility("default"))) 20#endif 21 22#else // defined(COMPONENT_BUILD) && !defined(ANGLE_TRANSLATOR_STATIC) 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 35extern "C" { 36#endif 37 38// Version number for shader translation API. 39// It is incremented every time the API changes. 40#define ANGLE_SH_VERSION 125 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// 48typedef enum { 49 SH_FRAGMENT_SHADER = 0x8B30, 50 SH_VERTEX_SHADER = 0x8B31 51} ShShaderType; 52 53typedef 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 80typedef 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 88typedef enum { 89 SH_NONE = 0, 90 SH_INT = 0x1404, 91 SH_UNSIGNED_INT = 0x1405, 92 SH_FLOAT = 0x1406, 93 SH_FLOAT_VEC2 = 0x8B50, 94 SH_FLOAT_VEC3 = 0x8B51, 95 SH_FLOAT_VEC4 = 0x8B52, 96 SH_INT_VEC2 = 0x8B53, 97 SH_INT_VEC3 = 0x8B54, 98 SH_INT_VEC4 = 0x8B55, 99 SH_UNSIGNED_INT_VEC2 = 0x8DC6, 100 SH_UNSIGNED_INT_VEC3 = 0x8DC7, 101 SH_UNSIGNED_INT_VEC4 = 0x8DC8, 102 SH_BOOL = 0x8B56, 103 SH_BOOL_VEC2 = 0x8B57, 104 SH_BOOL_VEC3 = 0x8B58, 105 SH_BOOL_VEC4 = 0x8B59, 106 SH_FLOAT_MAT2 = 0x8B5A, 107 SH_FLOAT_MAT3 = 0x8B5B, 108 SH_FLOAT_MAT4 = 0x8B5C, 109 SH_FLOAT_MAT2x3 = 0x8B65, 110 SH_FLOAT_MAT2x4 = 0x8B66, 111 SH_FLOAT_MAT3x2 = 0x8B67, 112 SH_FLOAT_MAT3x4 = 0x8B68, 113 SH_FLOAT_MAT4x2 = 0x8B69, 114 SH_FLOAT_MAT4x3 = 0x8B6A, 115 SH_SAMPLER_2D = 0x8B5E, 116 SH_SAMPLER_3D = 0x8B5F, 117 SH_SAMPLER_CUBE = 0x8B60, 118 SH_SAMPLER_2D_RECT_ARB = 0x8B63, 119 SH_SAMPLER_EXTERNAL_OES = 0x8D66, 120 SH_SAMPLER_2D_ARRAY = 0x8DC1, 121 SH_INT_SAMPLER_2D = 0x8DCA, 122 SH_INT_SAMPLER_3D = 0x8DCB, 123 SH_INT_SAMPLER_CUBE = 0x8DCC, 124 SH_INT_SAMPLER_2D_ARRAY = 0x8DCF, 125 SH_UNSIGNED_INT_SAMPLER_2D = 0x8DD2, 126 SH_UNSIGNED_INT_SAMPLER_3D = 0x8DD3, 127 SH_UNSIGNED_INT_SAMPLER_CUBE = 0x8DD4, 128 SH_UNSIGNED_INT_SAMPLER_2D_ARRAY = 0x8DD7, 129 SH_SAMPLER_2D_SHADOW = 0x8B62, 130 SH_SAMPLER_CUBE_SHADOW = 0x8DC5, 131 SH_SAMPLER_2D_ARRAY_SHADOW = 0x8DC4 132} ShDataType; 133 134typedef enum { 135 SH_PRECISION_HIGHP = 0x5001, 136 SH_PRECISION_MEDIUMP = 0x5002, 137 SH_PRECISION_LOWP = 0x5003, 138 SH_PRECISION_UNDEFINED = 0 139} ShPrecisionType; 140 141typedef enum { 142 SH_INFO_LOG_LENGTH = 0x8B84, 143 SH_OBJECT_CODE_LENGTH = 0x8B88, // GL_SHADER_SOURCE_LENGTH 144 SH_ACTIVE_UNIFORMS = 0x8B86, 145 SH_ACTIVE_UNIFORM_MAX_LENGTH = 0x8B87, 146 SH_ACTIVE_ATTRIBUTES = 0x8B89, 147 SH_ACTIVE_ATTRIBUTE_MAX_LENGTH = 0x8B8A, 148 SH_VARYINGS = 0x8BBB, 149 SH_VARYING_MAX_LENGTH = 0x8BBC, 150 SH_MAPPED_NAME_MAX_LENGTH = 0x6000, 151 SH_NAME_MAX_LENGTH = 0x6001, 152 SH_HASHED_NAME_MAX_LENGTH = 0x6002, 153 SH_HASHED_NAMES_COUNT = 0x6003, 154 SH_ACTIVE_UNIFORMS_ARRAY = 0x6004, 155 SH_SHADER_VERSION = 0x6005, 156 SH_ACTIVE_INTERFACE_BLOCKS_ARRAY = 0x6006, 157 SH_ACTIVE_OUTPUT_VARIABLES_ARRAY = 0x6007, 158 SH_ACTIVE_ATTRIBUTES_ARRAY = 0x6008, 159 SH_ACTIVE_VARYINGS_ARRAY = 0x6009, 160 SH_RESOURCES_STRING_LENGTH = 0x600A, 161 SH_OUTPUT_TYPE = 0x600B 162} ShShaderInfo; 163 164// Compile options. 165typedef enum { 166 SH_VALIDATE = 0, 167 SH_VALIDATE_LOOP_INDEXING = 0x0001, 168 SH_INTERMEDIATE_TREE = 0x0002, 169 SH_OBJECT_CODE = 0x0004, 170 SH_VARIABLES = 0x0008, 171 SH_LINE_DIRECTIVES = 0x0010, 172 SH_SOURCE_PATH = 0x0020, 173 SH_UNROLL_FOR_LOOP_WITH_INTEGER_INDEX = 0x0040, 174 // If a sampler array index happens to be a loop index, 175 // 1) if its type is integer, unroll the loop. 176 // 2) if its type is float, fail the shader compile. 177 // This is to work around a mac driver bug. 178 SH_UNROLL_FOR_LOOP_WITH_SAMPLER_ARRAY_INDEX = 0x0080, 179 180 // This is needed only as a workaround for certain OpenGL driver bugs. 181 SH_EMULATE_BUILT_IN_FUNCTIONS = 0x0100, 182 183 // This is an experimental flag to enforce restrictions that aim to prevent 184 // timing attacks. 185 // It generates compilation errors for shaders that could expose sensitive 186 // texture information via the timing channel. 187 // To use this flag, you must compile the shader under the WebGL spec 188 // (using the SH_WEBGL_SPEC flag). 189 SH_TIMING_RESTRICTIONS = 0x0200, 190 191 // This flag prints the dependency graph that is used to enforce timing 192 // restrictions on fragment shaders. 193 // This flag only has an effect if all of the following are true: 194 // - The shader spec is SH_WEBGL_SPEC. 195 // - The compile options contain the SH_TIMING_RESTRICTIONS flag. 196 // - The shader type is SH_FRAGMENT_SHADER. 197 SH_DEPENDENCY_GRAPH = 0x0400, 198 199 // Enforce the GLSL 1.017 Appendix A section 7 packing restrictions. 200 // This flag only enforces (and can only enforce) the packing 201 // restrictions for uniform variables in both vertex and fragment 202 // shaders. ShCheckVariablesWithinPackingLimits() lets embedders 203 // enforce the packing restrictions for varying variables during 204 // program link time. 205 SH_ENFORCE_PACKING_RESTRICTIONS = 0x0800, 206 207 // This flag ensures all indirect (expression-based) array indexing 208 // is clamped to the bounds of the array. This ensures, for example, 209 // that you cannot read off the end of a uniform, whether an array 210 // vec234, or mat234 type. The ShArrayIndexClampingStrategy enum, 211 // specified in the ShBuiltInResources when constructing the 212 // compiler, selects the strategy for the clamping implementation. 213 SH_CLAMP_INDIRECT_ARRAY_BOUNDS = 0x1000, 214 215 // This flag limits the complexity of an expression. 216 SH_LIMIT_EXPRESSION_COMPLEXITY = 0x2000, 217 218 // This flag limits the depth of the call stack. 219 SH_LIMIT_CALL_STACK_DEPTH = 0x4000, 220 221 // This flag initializes gl_Position to vec4(0,0,0,0) at the 222 // beginning of the vertex shader's main(), and has no effect in the 223 // fragment shader. It is intended as a workaround for drivers which 224 // incorrectly fail to link programs if gl_Position is not written. 225 SH_INIT_GL_POSITION = 0x8000, 226 227 // This flag replaces 228 // "a && b" with "a ? b : false", 229 // "a || b" with "a ? true : b". 230 // This is to work around a MacOSX driver bug that |b| is executed 231 // independent of |a|'s value. 232 SH_UNFOLD_SHORT_CIRCUIT = 0x10000, 233 234 // This flag initializes varyings without static use in vertex shader 235 // at the beginning of main(), and has no effects in the fragment shader. 236 // It is intended as a workaround for drivers which incorrectly optimize 237 // out such varyings and cause a link failure. 238 SH_INIT_VARYINGS_WITHOUT_STATIC_USE = 0x20000, 239} ShCompileOptions; 240 241// Defines alternate strategies for implementing array index clamping. 242typedef enum { 243 // Use the clamp intrinsic for array index clamping. 244 SH_CLAMP_WITH_CLAMP_INTRINSIC = 1, 245 246 // Use a user-defined function for array index clamping. 247 SH_CLAMP_WITH_USER_DEFINED_INT_CLAMP_FUNCTION 248} ShArrayIndexClampingStrategy; 249 250// 251// Driver must call this first, once, before doing any other 252// compiler operations. 253// If the function succeeds, the return value is nonzero, else zero. 254// 255COMPILER_EXPORT int ShInitialize(); 256// 257// Driver should call this at shutdown. 258// If the function succeeds, the return value is nonzero, else zero. 259// 260COMPILER_EXPORT int ShFinalize(); 261 262// The 64 bits hash function. The first parameter is the input string; the 263// second parameter is the string length. 264typedef khronos_uint64_t (*ShHashFunction64)(const char*, size_t); 265 266// 267// Implementation dependent built-in resources (constants and extensions). 268// The names for these resources has been obtained by stripping gl_/GL_. 269// 270typedef struct 271{ 272 // Constants. 273 int MaxVertexAttribs; 274 int MaxVertexUniformVectors; 275 int MaxVaryingVectors; 276 int MaxVertexTextureImageUnits; 277 int MaxCombinedTextureImageUnits; 278 int MaxTextureImageUnits; 279 int MaxFragmentUniformVectors; 280 int MaxDrawBuffers; 281 282 // Extensions. 283 // Set to 1 to enable the extension, else 0. 284 int OES_standard_derivatives; 285 int OES_EGL_image_external; 286 int ARB_texture_rectangle; 287 int EXT_draw_buffers; 288 int EXT_frag_depth; 289 int EXT_shader_texture_lod; 290 291 // Set to 1 if highp precision is supported in the fragment language. 292 // Default is 0. 293 int FragmentPrecisionHigh; 294 295 // GLSL ES 3.0 constants. 296 int MaxVertexOutputVectors; 297 int MaxFragmentInputVectors; 298 int MinProgramTexelOffset; 299 int MaxProgramTexelOffset; 300 301 // Name Hashing. 302 // Set a 64 bit hash function to enable user-defined name hashing. 303 // Default is NULL. 304 ShHashFunction64 HashFunction; 305 306 // Selects a strategy to use when implementing array index clamping. 307 // Default is SH_CLAMP_WITH_CLAMP_INTRINSIC. 308 ShArrayIndexClampingStrategy ArrayIndexClampingStrategy; 309 310 // The maximum complexity an expression can be. 311 int MaxExpressionComplexity; 312 313 // The maximum depth a call stack can be. 314 int MaxCallStackDepth; 315} ShBuiltInResources; 316 317// 318// Initialize built-in resources with minimum expected values. 319// 320COMPILER_EXPORT void ShInitBuiltInResources(ShBuiltInResources* resources); 321 322// 323// ShHandle held by but opaque to the driver. It is allocated, 324// managed, and de-allocated by the compiler. Its contents 325// are defined by and used by the compiler. 326// 327// If handle creation fails, 0 will be returned. 328// 329typedef void* ShHandle; 330 331// 332// Returns the a concatenated list of the items in ShBuiltInResources as a string. 333// This function must be updated whenever ShBuiltInResources is changed. 334// Parameters: 335// handle: Specifies the handle of the compiler to be used. 336// outStringLen: Specifies the size of the buffer, in number of characters. The size 337// of the buffer required to store the resources string can be obtained 338// by calling ShGetInfo with SH_RESOURCES_STRING_LENGTH. 339// outStr: Returns a null-terminated string representing all the built-in resources. 340COMPILER_EXPORT void ShGetBuiltInResourcesString(const ShHandle handle, size_t outStringLen, char *outStr); 341 342// 343// Driver calls these to create and destroy compiler objects. 344// 345// Returns the handle of constructed compiler, null if the requested compiler is 346// not supported. 347// Parameters: 348// type: Specifies the type of shader - SH_FRAGMENT_SHADER or SH_VERTEX_SHADER. 349// spec: Specifies the language spec the compiler must conform to - 350// SH_GLES2_SPEC or SH_WEBGL_SPEC. 351// output: Specifies the output code type - SH_ESSL_OUTPUT, SH_GLSL_OUTPUT, 352// SH_HLSL9_OUTPUT or SH_HLSL11_OUTPUT. 353// resources: Specifies the built-in resources. 354COMPILER_EXPORT ShHandle ShConstructCompiler( 355 ShShaderType type, 356 ShShaderSpec spec, 357 ShShaderOutput output, 358 const ShBuiltInResources* resources); 359COMPILER_EXPORT void ShDestruct(ShHandle handle); 360 361// 362// Compiles the given shader source. 363// If the function succeeds, the return value is nonzero, else zero. 364// Parameters: 365// handle: Specifies the handle of compiler to be used. 366// shaderStrings: Specifies an array of pointers to null-terminated strings 367// containing the shader source code. 368// numStrings: Specifies the number of elements in shaderStrings array. 369// compileOptions: A mask containing the following parameters: 370// SH_VALIDATE: Validates shader to ensure that it conforms to the spec 371// specified during compiler construction. 372// SH_VALIDATE_LOOP_INDEXING: Validates loop and indexing in the shader to 373// ensure that they do not exceed the minimum 374// functionality mandated in GLSL 1.0 spec, 375// Appendix A, Section 4 and 5. 376// There is no need to specify this parameter when 377// compiling for WebGL - it is implied. 378// SH_INTERMEDIATE_TREE: Writes intermediate tree to info log. 379// Can be queried by calling ShGetInfoLog(). 380// SH_OBJECT_CODE: Translates intermediate tree to glsl or hlsl shader. 381// Can be queried by calling ShGetObjectCode(). 382// SH_VARIABLES: Extracts attributes, uniforms, and varyings. 383// Can be queried by calling ShGetVariableInfo(). 384// 385COMPILER_EXPORT int ShCompile( 386 const ShHandle handle, 387 const char* const shaderStrings[], 388 size_t numStrings, 389 int compileOptions 390 ); 391 392// Returns a parameter from a compiled shader. 393// Parameters: 394// handle: Specifies the compiler 395// pname: Specifies the parameter to query. 396// The following parameters are defined: 397// SH_INFO_LOG_LENGTH: the number of characters in the information log 398// including the null termination character. 399// SH_OBJECT_CODE_LENGTH: the number of characters in the object code 400// including the null termination character. 401// SH_ACTIVE_ATTRIBUTES: the number of active attribute variables. 402// SH_ACTIVE_ATTRIBUTE_MAX_LENGTH: the length of the longest active attribute 403// variable name including the null 404// termination character. 405// SH_ACTIVE_UNIFORMS: the number of active uniform variables. 406// SH_ACTIVE_UNIFORM_MAX_LENGTH: the length of the longest active uniform 407// variable name including the null 408// termination character. 409// SH_VARYINGS: the number of varying variables. 410// SH_VARYING_MAX_LENGTH: the length of the longest varying variable name 411// including the null termination character. 412// SH_MAPPED_NAME_MAX_LENGTH: the length of the mapped variable name including 413// the null termination character. 414// SH_NAME_MAX_LENGTH: the max length of a user-defined name including the 415// null termination character. 416// SH_HASHED_NAME_MAX_LENGTH: the max length of a hashed name including the 417// null termination character. 418// SH_HASHED_NAMES_COUNT: the number of hashed names from the latest compile. 419// SH_SHADER_VERSION: the version of the shader language 420// SH_OUTPUT_TYPE: the currently set language output type 421// 422// params: Requested parameter 423COMPILER_EXPORT void ShGetInfo(const ShHandle handle, 424 ShShaderInfo pname, 425 size_t* params); 426 427// Returns nul-terminated information log for a compiled shader. 428// Parameters: 429// handle: Specifies the compiler 430// infoLog: Specifies an array of characters that is used to return 431// the information log. It is assumed that infoLog has enough memory 432// to accomodate the information log. The size of the buffer required 433// to store the returned information log can be obtained by calling 434// ShGetInfo with SH_INFO_LOG_LENGTH. 435COMPILER_EXPORT void ShGetInfoLog(const ShHandle handle, char* infoLog); 436 437// Returns null-terminated object code for a compiled shader. 438// Parameters: 439// handle: Specifies the compiler 440// infoLog: Specifies an array of characters that is used to return 441// the object code. It is assumed that infoLog has enough memory to 442// accomodate the object code. The size of the buffer required to 443// store the returned object code can be obtained by calling 444// ShGetInfo with SH_OBJECT_CODE_LENGTH. 445COMPILER_EXPORT void ShGetObjectCode(const ShHandle handle, char* objCode); 446 447// Returns information about a shader variable. 448// Parameters: 449// handle: Specifies the compiler 450// variableType: Specifies the variable type; options include 451// SH_ACTIVE_ATTRIBUTES, SH_ACTIVE_UNIFORMS, SH_VARYINGS. 452// index: Specifies the index of the variable to be queried. 453// length: Returns the number of characters actually written in the string 454// indicated by name (excluding the null terminator) if a value other 455// than NULL is passed. 456// size: Returns the size of the variable. 457// type: Returns the data type of the variable. 458// precision: Returns the precision of the variable. 459// staticUse: Returns 1 if the variable is accessed in a statement after 460// pre-processing, whether or not run-time flow of control will 461// cause that statement to be executed. 462// Returns 0 otherwise. 463// name: Returns a null terminated string containing the name of the 464// variable. It is assumed that name has enough memory to accormodate 465// the variable name. The size of the buffer required to store the 466// variable name can be obtained by calling ShGetInfo with 467// SH_ACTIVE_ATTRIBUTE_MAX_LENGTH, SH_ACTIVE_UNIFORM_MAX_LENGTH, 468// SH_VARYING_MAX_LENGTH. 469// mappedName: Returns a null terminated string containing the mapped name of 470// the variable, It is assumed that mappedName has enough memory 471// (SH_MAPPED_NAME_MAX_LENGTH), or NULL if don't care about the 472// mapped name. If the name is not mapped, then name and mappedName 473// are the same. 474COMPILER_EXPORT void ShGetVariableInfo(const ShHandle handle, 475 ShShaderInfo variableType, 476 int index, 477 size_t* length, 478 int* size, 479 ShDataType* type, 480 ShPrecisionType* precision, 481 int* staticUse, 482 char* name, 483 char* mappedName); 484 485// Returns information about a name hashing entry from the latest compile. 486// Parameters: 487// handle: Specifies the compiler 488// index: Specifies the index of the name hashing entry to be queried. 489// name: Returns a null terminated string containing the user defined name. 490// It is assumed that name has enough memory to accomodate the name. 491// The size of the buffer required to store the user defined name can 492// be obtained by calling ShGetInfo with SH_NAME_MAX_LENGTH. 493// hashedName: Returns a null terminated string containing the hashed name of 494// the uniform variable, It is assumed that hashedName has enough 495// memory to accomodate the name. The size of the buffer required 496// to store the name can be obtained by calling ShGetInfo with 497// SH_HASHED_NAME_MAX_LENGTH. 498COMPILER_EXPORT void ShGetNameHashingEntry(const ShHandle handle, 499 int index, 500 char* name, 501 char* hashedName); 502 503// Returns a parameter from a compiled shader. 504// Parameters: 505// handle: Specifies the compiler 506// pname: Specifies the parameter to query. 507// The following parameters are defined: 508// SH_ACTIVE_UNIFORMS_ARRAY: an STL vector of active uniforms. Valid only for 509// HLSL output. 510// params: Requested parameter 511COMPILER_EXPORT void ShGetInfoPointer(const ShHandle handle, 512 ShShaderInfo pname, 513 void** params); 514 515typedef struct 516{ 517 ShDataType type; 518 int size; 519} ShVariableInfo; 520 521// Returns 1 if the passed in variables pack in maxVectors following 522// the packing rules from the GLSL 1.017 spec, Appendix A, section 7. 523// Returns 0 otherwise. Also look at the SH_ENFORCE_PACKING_RESTRICTIONS 524// flag above. 525// Parameters: 526// maxVectors: the available rows of registers. 527// varInfoArray: an array of variable info (types and sizes). 528// varInfoArraySize: the size of the variable array. 529COMPILER_EXPORT int ShCheckVariablesWithinPackingLimits( 530 int maxVectors, 531 ShVariableInfo* varInfoArray, 532 size_t varInfoArraySize); 533 534#ifdef __cplusplus 535} 536#endif 537 538#endif // _COMPILER_INTERFACE_INCLUDED_ 539