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.
6 #ifndef _COMPILER_INTERFACE_INCLUDED_
7 #define _COMPILER_INTERFACE_INCLUDED_
9 #if defined(COMPONENT_BUILD) && !defined(ANGLE_TRANSLATOR_STATIC)
10 #if defined(_WIN32) || defined(_WIN64)
12 #if defined(ANGLE_TRANSLATOR_IMPLEMENTATION)
13 #define COMPILER_EXPORT __declspec(dllexport)
15 #define COMPILER_EXPORT __declspec(dllimport)
16 #endif // defined(ANGLE_TRANSLATOR_IMPLEMENTATION)
18 #else // defined(_WIN32) || defined(_WIN64)
19 #define COMPILER_EXPORT __attribute__((visibility("default")))
22 #else // defined(COMPONENT_BUILD) && !defined(ANGLE_TRANSLATOR_STATIC)
23 #define COMPILER_EXPORT
26 #include "KHR/khrplatform.h"
30 // This is the platform independent interface between an OGL driver
31 // and the shading language compiler.
38 // Version number for shader translation API.
39 // It is incremented everytime the API changes.
40 #define ANGLE_SH_VERSION 112
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.
49 SH_FRAGMENT_SHADER = 0x8B30,
50 SH_VERTEX_SHADER = 0x8B31
54 SH_GLES2_SPEC = 0x8B40,
55 SH_WEBGL_SPEC = 0x8B41,
57 // The CSS Shaders spec is a subset of the WebGL spec.
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.
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.
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
77 SH_CSS_SHADERS_SPEC = 0x8B42
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
92 SH_FLOAT_VEC2 = 0x8B50,
93 SH_FLOAT_VEC3 = 0x8B51,
94 SH_FLOAT_VEC4 = 0x8B52,
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
112 SH_PRECISION_HIGHP = 0x5001,
113 SH_PRECISION_MEDIUMP = 0x5002,
114 SH_PRECISION_LOWP = 0x5003,
115 SH_PRECISION_UNDEFINED = 0
119 SH_INFO_LOG_LENGTH = 0x8B84,
120 SH_OBJECT_CODE_LENGTH = 0x8B88, // GL_SHADER_SOURCE_LENGTH
121 SH_ACTIVE_UNIFORMS = 0x8B86,
122 SH_ACTIVE_UNIFORM_MAX_LENGTH = 0x8B87,
123 SH_ACTIVE_ATTRIBUTES = 0x8B89,
124 SH_ACTIVE_ATTRIBUTE_MAX_LENGTH = 0x8B8A,
125 SH_VARYINGS = 0x8BBB,
126 SH_VARYING_MAX_LENGTH = 0x8BBC,
127 SH_MAPPED_NAME_MAX_LENGTH = 0x6000,
128 SH_NAME_MAX_LENGTH = 0x6001,
129 SH_HASHED_NAME_MAX_LENGTH = 0x6002,
130 SH_HASHED_NAMES_COUNT = 0x6003,
131 SH_ACTIVE_UNIFORMS_ARRAY = 0x6004
137 SH_VALIDATE_LOOP_INDEXING = 0x0001,
138 SH_INTERMEDIATE_TREE = 0x0002,
139 SH_OBJECT_CODE = 0x0004,
140 SH_VARIABLES = 0x0008,
141 SH_LINE_DIRECTIVES = 0x0010,
142 SH_SOURCE_PATH = 0x0020,
143 SH_MAP_LONG_VARIABLE_NAMES = 0x0040,
144 SH_UNROLL_FOR_LOOP_WITH_INTEGER_INDEX = 0x0080,
146 // This is needed only as a workaround for certain OpenGL driver bugs.
147 SH_EMULATE_BUILT_IN_FUNCTIONS = 0x0100,
149 // This is an experimental flag to enforce restrictions that aim to prevent
151 // It generates compilation errors for shaders that could expose sensitive
152 // texture information via the timing channel.
153 // To use this flag, you must compile the shader under the WebGL spec
154 // (using the SH_WEBGL_SPEC flag).
155 SH_TIMING_RESTRICTIONS = 0x0200,
157 // This flag prints the dependency graph that is used to enforce timing
158 // restrictions on fragment shaders.
159 // This flag only has an effect if all of the following are true:
160 // - The shader spec is SH_WEBGL_SPEC.
161 // - The compile options contain the SH_TIMING_RESTRICTIONS flag.
162 // - The shader type is SH_FRAGMENT_SHADER.
163 SH_DEPENDENCY_GRAPH = 0x0400,
165 // Enforce the GLSL 1.017 Appendix A section 7 packing restrictions.
166 // This flag only enforces (and can only enforce) the packing
167 // restrictions for uniform variables in both vertex and fragment
168 // shaders. ShCheckVariablesWithinPackingLimits() lets embedders
169 // enforce the packing restrictions for varying variables during
170 // program link time.
171 SH_ENFORCE_PACKING_RESTRICTIONS = 0x0800,
173 // This flag ensures all indirect (expression-based) array indexing
174 // is clamped to the bounds of the array. This ensures, for example,
175 // that you cannot read off the end of a uniform, whether an array
176 // vec234, or mat234 type. The ShArrayIndexClampingStrategy enum,
177 // specified in the ShBuiltInResources when constructing the
178 // compiler, selects the strategy for the clamping implementation.
179 SH_CLAMP_INDIRECT_ARRAY_BOUNDS = 0x1000,
181 // This flag limits the complexity of an expression.
182 SH_LIMIT_EXPRESSION_COMPLEXITY = 0x2000,
184 // This flag limits the depth of the call stack.
185 SH_LIMIT_CALL_STACK_DEPTH = 0x4000,
187 // This flag initializes gl_Position to vec4(0,0,0,0) at the
188 // beginning of the vertex shader's main(), and has no effect in the
189 // fragment shader. It is intended as a workaround for drivers which
190 // incorrectly fail to link programs if gl_Position is not written.
191 SH_INIT_GL_POSITION = 0x8000,
193 // This flag replaces
194 // "a && b" with "a ? b : false",
195 // "a || b" with "a ? true : b".
196 // This is to work around a MacOSX driver bug that |b| is executed
197 // independent of |a|'s value.
198 SH_UNFOLD_SHORT_CIRCUIT = 0x10000,
200 // This flag initializes varyings without static use in vertex shader
201 // at the beginning of main(), and has no effects in the fragment shader.
202 // It is intended as a workaround for drivers which incorrectly optimize
203 // out such varyings and cause a link failure.
204 SH_INIT_VARYINGS_WITHOUT_STATIC_USE = 0x20000,
207 // Defines alternate strategies for implementing array index clamping.
209 // Use the clamp intrinsic for array index clamping.
210 SH_CLAMP_WITH_CLAMP_INTRINSIC = 1,
212 // Use a user-defined function for array index clamping.
213 SH_CLAMP_WITH_USER_DEFINED_INT_CLAMP_FUNCTION
214 } ShArrayIndexClampingStrategy;
217 // Driver must call this first, once, before doing any other
218 // compiler operations.
219 // If the function succeeds, the return value is nonzero, else zero.
221 COMPILER_EXPORT int ShInitialize();
223 // Driver should call this at shutdown.
224 // If the function succeeds, the return value is nonzero, else zero.
226 COMPILER_EXPORT int ShFinalize();
228 // The 64 bits hash function. The first parameter is the input string; the
229 // second parameter is the string length.
230 typedef khronos_uint64_t (*ShHashFunction64)(const char*, size_t);
233 // Implementation dependent built-in resources (constants and extensions).
234 // The names for these resources has been obtained by stripping gl_/GL_.
239 int MaxVertexAttribs;
240 int MaxVertexUniformVectors;
241 int MaxVaryingVectors;
242 int MaxVertexTextureImageUnits;
243 int MaxCombinedTextureImageUnits;
244 int MaxTextureImageUnits;
245 int MaxFragmentUniformVectors;
249 // Set to 1 to enable the extension, else 0.
250 int OES_standard_derivatives;
251 int OES_EGL_image_external;
252 int ARB_texture_rectangle;
253 int EXT_draw_buffers;
256 // Set to 1 if highp precision is supported in the fragment language.
258 int FragmentPrecisionHigh;
261 // Set a 64 bit hash function to enable user-defined name hashing.
263 ShHashFunction64 HashFunction;
265 // Selects a strategy to use when implementing array index clamping.
266 // Default is SH_CLAMP_WITH_CLAMP_INTRINSIC.
267 ShArrayIndexClampingStrategy ArrayIndexClampingStrategy;
269 // The maximum complexity an expression can be.
270 int MaxExpressionComplexity;
272 // The maximum depth a call stack can be.
273 int MaxCallStackDepth;
274 } ShBuiltInResources;
277 // Initialize built-in resources with minimum expected values.
279 COMPILER_EXPORT void ShInitBuiltInResources(ShBuiltInResources* resources);
282 // ShHandle held by but opaque to the driver. It is allocated,
283 // managed, and de-allocated by the compiler. It's contents
284 // are defined by and used by the compiler.
286 // If handle creation fails, 0 will be returned.
288 typedef void* ShHandle;
291 // Driver calls these to create and destroy compiler objects.
293 // Returns the handle of constructed compiler, null if the requested compiler is
296 // type: Specifies the type of shader - SH_FRAGMENT_SHADER or SH_VERTEX_SHADER.
297 // spec: Specifies the language spec the compiler must conform to -
298 // SH_GLES2_SPEC or SH_WEBGL_SPEC.
299 // output: Specifies the output code type - SH_ESSL_OUTPUT, SH_GLSL_OUTPUT,
300 // SH_HLSL9_OUTPUT or SH_HLSL11_OUTPUT.
301 // resources: Specifies the built-in resources.
302 COMPILER_EXPORT ShHandle ShConstructCompiler(
305 ShShaderOutput output,
306 const ShBuiltInResources* resources);
307 COMPILER_EXPORT void ShDestruct(ShHandle handle);
310 // Compiles the given shader source.
311 // If the function succeeds, the return value is nonzero, else zero.
313 // handle: Specifies the handle of compiler to be used.
314 // shaderStrings: Specifies an array of pointers to null-terminated strings
315 // containing the shader source code.
316 // numStrings: Specifies the number of elements in shaderStrings array.
317 // compileOptions: A mask containing the following parameters:
318 // SH_VALIDATE: Validates shader to ensure that it conforms to the spec
319 // specified during compiler construction.
320 // SH_VALIDATE_LOOP_INDEXING: Validates loop and indexing in the shader to
321 // ensure that they do not exceed the minimum
322 // functionality mandated in GLSL 1.0 spec,
323 // Appendix A, Section 4 and 5.
324 // There is no need to specify this parameter when
325 // compiling for WebGL - it is implied.
326 // SH_INTERMEDIATE_TREE: Writes intermediate tree to info log.
327 // Can be queried by calling ShGetInfoLog().
328 // SH_OBJECT_CODE: Translates intermediate tree to glsl or hlsl shader.
329 // Can be queried by calling ShGetObjectCode().
330 // SH_VARIABLES: Extracts attributes, uniforms, and varyings.
331 // Can be queried by calling ShGetVariableInfo().
333 COMPILER_EXPORT int ShCompile(
334 const ShHandle handle,
335 const char* const shaderStrings[],
340 // Returns a parameter from a compiled shader.
342 // handle: Specifies the compiler
343 // pname: Specifies the parameter to query.
344 // The following parameters are defined:
345 // SH_INFO_LOG_LENGTH: the number of characters in the information log
346 // including the null termination character.
347 // SH_OBJECT_CODE_LENGTH: the number of characters in the object code
348 // including the null termination character.
349 // SH_ACTIVE_ATTRIBUTES: the number of active attribute variables.
350 // SH_ACTIVE_ATTRIBUTE_MAX_LENGTH: the length of the longest active attribute
351 // variable name including the null
352 // termination character.
353 // SH_ACTIVE_UNIFORMS: the number of active uniform variables.
354 // SH_ACTIVE_UNIFORM_MAX_LENGTH: the length of the longest active uniform
355 // variable name including the null
356 // termination character.
357 // SH_VARYINGS: the number of varying variables.
358 // SH_VARYING_MAX_LENGTH: the length of the longest varying variable name
359 // including the null termination character.
360 // SH_MAPPED_NAME_MAX_LENGTH: the length of the mapped variable name including
361 // the null termination character.
362 // SH_NAME_MAX_LENGTH: the max length of a user-defined name including the
363 // null termination character.
364 // SH_HASHED_NAME_MAX_LENGTH: the max length of a hashed name including the
365 // null termination character.
366 // SH_HASHED_NAMES_COUNT: the number of hashed names from the latest compile.
368 // params: Requested parameter
369 COMPILER_EXPORT void ShGetInfo(const ShHandle handle,
373 // Returns nul-terminated information log for a compiled shader.
375 // handle: Specifies the compiler
376 // infoLog: Specifies an array of characters that is used to return
377 // the information log. It is assumed that infoLog has enough memory
378 // to accomodate the information log. The size of the buffer required
379 // to store the returned information log can be obtained by calling
380 // ShGetInfo with SH_INFO_LOG_LENGTH.
381 COMPILER_EXPORT void ShGetInfoLog(const ShHandle handle, char* infoLog);
383 // Returns null-terminated object code for a compiled shader.
385 // handle: Specifies the compiler
386 // infoLog: Specifies an array of characters that is used to return
387 // the object code. It is assumed that infoLog has enough memory to
388 // accomodate the object code. The size of the buffer required to
389 // store the returned object code can be obtained by calling
390 // ShGetInfo with SH_OBJECT_CODE_LENGTH.
391 COMPILER_EXPORT void ShGetObjectCode(const ShHandle handle, char* objCode);
393 // Returns information about a shader variable.
395 // handle: Specifies the compiler
396 // variableType: Specifies the variable type; options include
397 // SH_ACTIVE_ATTRIBUTES, SH_ACTIVE_UNIFORMS, SH_VARYINGS.
398 // index: Specifies the index of the variable to be queried.
399 // length: Returns the number of characters actually written in the string
400 // indicated by name (excluding the null terminator) if a value other
401 // than NULL is passed.
402 // size: Returns the size of the variable.
403 // type: Returns the data type of the variable.
404 // precision: Returns the precision of the variable.
405 // staticUse: Returns 1 if the variable is accessed in a statement after
406 // pre-processing, whether or not run-time flow of control will
407 // cause that statement to be executed.
408 // Returns 0 otherwise.
409 // name: Returns a null terminated string containing the name of the
410 // variable. It is assumed that name has enough memory to accormodate
411 // the variable name. The size of the buffer required to store the
412 // variable name can be obtained by calling ShGetInfo with
413 // SH_ACTIVE_ATTRIBUTE_MAX_LENGTH, SH_ACTIVE_UNIFORM_MAX_LENGTH,
414 // SH_VARYING_MAX_LENGTH.
415 // mappedName: Returns a null terminated string containing the mapped name of
416 // the variable, It is assumed that mappedName has enough memory
417 // (SH_MAPPED_NAME_MAX_LENGTH), or NULL if don't care about the
418 // mapped name. If the name is not mapped, then name and mappedName
420 COMPILER_EXPORT void ShGetVariableInfo(const ShHandle handle,
421 ShShaderInfo variableType,
426 ShPrecisionType* precision,
431 // Returns information about a name hashing entry from the latest compile.
433 // handle: Specifies the compiler
434 // index: Specifies the index of the name hashing entry to be queried.
435 // name: Returns a null terminated string containing the user defined name.
436 // It is assumed that name has enough memory to accomodate the name.
437 // The size of the buffer required to store the user defined name can
438 // be obtained by calling ShGetInfo with SH_NAME_MAX_LENGTH.
439 // hashedName: Returns a null terminated string containing the hashed name of
440 // the uniform variable, It is assumed that hashedName has enough
441 // memory to accomodate the name. The size of the buffer required
442 // to store the name can be obtained by calling ShGetInfo with
443 // SH_HASHED_NAME_MAX_LENGTH.
444 COMPILER_EXPORT void ShGetNameHashingEntry(const ShHandle handle,
449 // Returns a parameter from a compiled shader.
451 // handle: Specifies the compiler
452 // pname: Specifies the parameter to query.
453 // The following parameters are defined:
454 // SH_ACTIVE_UNIFORMS_ARRAY: an STL vector of active uniforms. Valid only for
456 // params: Requested parameter
457 COMPILER_EXPORT void ShGetInfoPointer(const ShHandle handle,
467 // Returns 1 if the passed in variables pack in maxVectors following
468 // the packing rules from the GLSL 1.017 spec, Appendix A, section 7.
469 // Returns 0 otherwise. Also look at the SH_ENFORCE_PACKING_RESTRICTIONS
472 // maxVectors: the available rows of registers.
473 // varInfoArray: an array of variable info (types and sizes).
474 // varInfoArraySize: the size of the variable array.
475 COMPILER_EXPORT int ShCheckVariablesWithinPackingLimits(
477 ShVariableInfo* varInfoArray,
478 size_t varInfoArraySize);
484 #endif // _COMPILER_INTERFACE_INCLUDED_