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