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