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 GLSLANG_SHADERLANG_H_
7#define GLSLANG_SHADERLANG_H_
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 "khrplatform.h"
29
30#include <map>
31#include <string>
32#include <vector>
33
34//
35// This is the platform independent interface between an OGL driver
36// and the shading language compiler.
37//
38
39namespace sh
40{
41// GLenum alias
42typedef unsigned int GLenum;
43}
44
45// Must be included after GLenum proxy typedef
46// Note: make sure to increment ANGLE_SH_VERSION when changing ShaderVars.h
47#include "ShaderVars.h"
48
49// Version number for shader translation API.
50// It is incremented every time the API changes.
51#define ANGLE_SH_VERSION 135
52
53typedef enum {
54 SH_GLES2_SPEC = 0x8B40,
55 SH_WEBGL_SPEC = 0x8B41,
56
57 SH_GLES3_SPEC = 0x8B86,
58 SH_WEBGL2_SPEC = 0x8B87,
59
60 // The CSS Shaders spec is a subset of the WebGL spec.
61 //
62 // In both CSS vertex and fragment shaders, ANGLE:
63 // (1) Reserves the "css_" prefix.
64 // (2) Renames the main function to css_main.
65 // (3) Disables the gl_MaxDrawBuffers built-in.
66 //
67 // In CSS fragment shaders, ANGLE:
68 // (1) Disables the gl_FragColor built-in.
69 // (2) Disables the gl_FragData built-in.
70 // (3) Enables the css_MixColor built-in.
71 // (4) Enables the css_ColorMatrix built-in.
72 //
73 // After passing a CSS shader through ANGLE, the browser is expected to append
74 // a new main function to it.
75 // This new main function will call the css_main function.
76 // It may also perform additional operations like varying assignment, texture
77 // access, and gl_FragColor assignment in order to implement the CSS Shaders
78 // blend modes.
79 //
80 SH_CSS_SHADERS_SPEC = 0x8B42
81} ShShaderSpec;
82
83typedef enum {
84 SH_ESSL_OUTPUT = 0x8B45,
85 // SH_GLSL_OUTPUT is deprecated. This is to not break the build.
86 SH_GLSL_OUTPUT = 0x8B46,
87 SH_GLSL_COMPATIBILITY_OUTPUT = 0x8B46,
88 // SH_GLSL_CORE_OUTPUT is deprecated.
89 SH_GLSL_CORE_OUTPUT = 0x8B47,
90 //Note: GL introduced core profiles in 1.5. However, for compatiblity with Chromium, we treat SH_GLSL_CORE_OUTPUT as GLSL_130_OUTPUT.
91 //TODO: Remove SH_GLSL_CORE_OUTPUT
92 SH_GLSL_130_OUTPUT = 0x8B47,
93 SH_GLSL_410_CORE_OUTPUT = 0x8B84,
94 SH_GLSL_420_CORE_OUTPUT = 0x8B85,
95
96 // HLSL output only supported in some configurations.
97 SH_HLSL_OUTPUT = 0x8B48,
98 SH_HLSL9_OUTPUT = 0x8B48,
99 SH_HLSL11_OUTPUT = 0x8B49
100} ShShaderOutput;
101
102// Compile options.
103typedef enum {
104 SH_VALIDATE = 0,
105 SH_VALIDATE_LOOP_INDEXING = 0x0001,
106 SH_INTERMEDIATE_TREE = 0x0002,
107 SH_OBJECT_CODE = 0x0004,
108 SH_VARIABLES = 0x0008,
109 SH_LINE_DIRECTIVES = 0x0010,
110 SH_SOURCE_PATH = 0x0020,
111 SH_UNROLL_FOR_LOOP_WITH_INTEGER_INDEX = 0x0040,
112 // If a sampler array index happens to be a loop index,
113 // 1) if its type is integer, unroll the loop.
114 // 2) if its type is float, fail the shader compile.
115 // This is to work around a mac driver bug.
116 SH_UNROLL_FOR_LOOP_WITH_SAMPLER_ARRAY_INDEX = 0x0080,
117
118 // This is needed only as a workaround for certain OpenGL driver bugs.
119 SH_EMULATE_BUILT_IN_FUNCTIONS = 0x0100,
120
121 // This is an experimental flag to enforce restrictions that aim to prevent
122 // timing attacks.
123 // It generates compilation errors for shaders that could expose sensitive
124 // texture information via the timing channel.
125 // To use this flag, you must compile the shader under the WebGL spec
126 // (using the SH_WEBGL_SPEC flag).
127 SH_TIMING_RESTRICTIONS = 0x0200,
128
129 // This flag prints the dependency graph that is used to enforce timing
130 // restrictions on fragment shaders.
131 // This flag only has an effect if all of the following are true:
132 // - The shader spec is SH_WEBGL_SPEC.
133 // - The compile options contain the SH_TIMING_RESTRICTIONS flag.
134 // - The shader type is GL_FRAGMENT_SHADER.
135 SH_DEPENDENCY_GRAPH = 0x0400,
136
137 // Enforce the GLSL 1.017 Appendix A section 7 packing restrictions.
138 // This flag only enforces (and can only enforce) the packing
139 // restrictions for uniform variables in both vertex and fragment
140 // shaders. ShCheckVariablesWithinPackingLimits() lets embedders
141 // enforce the packing restrictions for varying variables during
142 // program link time.
143 SH_ENFORCE_PACKING_RESTRICTIONS = 0x0800,
144
145 // This flag ensures all indirect (expression-based) array indexing
146 // is clamped to the bounds of the array. This ensures, for example,
147 // that you cannot read off the end of a uniform, whether an array
148 // vec234, or mat234 type. The ShArrayIndexClampingStrategy enum,
149 // specified in the ShBuiltInResources when constructing the
150 // compiler, selects the strategy for the clamping implementation.
151 SH_CLAMP_INDIRECT_ARRAY_BOUNDS = 0x1000,
152
153 // This flag limits the complexity of an expression.
154 SH_LIMIT_EXPRESSION_COMPLEXITY = 0x2000,
155
156 // This flag limits the depth of the call stack.
157 SH_LIMIT_CALL_STACK_DEPTH = 0x4000,
158
159 // This flag initializes gl_Position to vec4(0,0,0,0) at the
160 // beginning of the vertex shader's main(), and has no effect in the
161 // fragment shader. It is intended as a workaround for drivers which
162 // incorrectly fail to link programs if gl_Position is not written.
163 SH_INIT_GL_POSITION = 0x8000,
164
165 // This flag replaces
166 // "a && b" with "a ? b : false",
167 // "a || b" with "a ? true : b".
168 // This is to work around a MacOSX driver bug that |b| is executed
169 // independent of |a|'s value.
170 SH_UNFOLD_SHORT_CIRCUIT = 0x10000,
171
172 // This flag initializes varyings without static use in vertex shader
173 // at the beginning of main(), and has no effects in the fragment shader.
174 // It is intended as a workaround for drivers which incorrectly optimize
175 // out such varyings and cause a link failure.
176 SH_INIT_VARYINGS_WITHOUT_STATIC_USE = 0x20000,
177
178 // This flag scalarizes vec/ivec/bvec/mat constructor args.
179 // It is intended as a workaround for Linux/Mac driver bugs.
180 SH_SCALARIZE_VEC_AND_MAT_CONSTRUCTOR_ARGS = 0x40000,
181
182 // This flag overwrites a struct name with a unique prefix.
183 // It is intended as a workaround for drivers that do not handle
184 // struct scopes correctly, including all Mac drivers and Linux AMD.
185 SH_REGENERATE_STRUCT_NAMES = 0x80000,
186
187 // This flag makes the compiler not prune unused function early in the
188 // compilation process. Pruning coupled with SH_LIMIT_CALL_STACK_DEPTH
189 // helps avoid bad shaders causing stack overflows.
190 SH_DONT_PRUNE_UNUSED_FUNCTIONS = 0x100000,
191} ShCompileOptions;
192
193// Defines alternate strategies for implementing array index clamping.
194typedef enum {
195 // Use the clamp intrinsic for array index clamping.
196 SH_CLAMP_WITH_CLAMP_INTRINSIC = 1,
197
198 // Use a user-defined function for array index clamping.
199 SH_CLAMP_WITH_USER_DEFINED_INT_CLAMP_FUNCTION
200} ShArrayIndexClampingStrategy;
201
202//
203// Driver must call this first, once, before doing any other
204// compiler operations.
205// If the function succeeds, the return value is true, else false.
206//
207COMPILER_EXPORT bool ShInitialize();
208//
209// Driver should call this at shutdown.
210// If the function succeeds, the return value is true, else false.
211//
212COMPILER_EXPORT bool ShFinalize();
213
214// The 64 bits hash function. The first parameter is the input string; the
215// second parameter is the string length.
216typedef khronos_uint64_t (*ShHashFunction64)(const char*, size_t);
217
218//
219// Implementation dependent built-in resources (constants and extensions).
220// The names for these resources has been obtained by stripping gl_/GL_.
221//
222typedef struct
223{
224 // Constants.
225 int MaxVertexAttribs;
226 int MaxVertexUniformVectors;
227 int MaxVaryingVectors;
228 int MaxVertexTextureImageUnits;
229 int MaxCombinedTextureImageUnits;
230 int MaxTextureImageUnits;
231 int MaxFragmentUniformVectors;
232 int MaxDrawBuffers;
233
234 // Extensions.
235 // Set to 1 to enable the extension, else 0.
236 int OES_standard_derivatives;
237 int OES_EGL_image_external;
238 int ARB_texture_rectangle;
239 int EXT_draw_buffers;
240 int EXT_frag_depth;
241 int EXT_shader_texture_lod;
242 int WEBGL_debug_shader_precision;
243 int EXT_shader_framebuffer_fetch;
244 int NV_shader_framebuffer_fetch;
245 int ARM_shader_framebuffer_fetch;
246
247 // Set to 1 to enable replacing GL_EXT_draw_buffers #extension directives
248 // with GL_NV_draw_buffers in ESSL output. This flag can be used to emulate
249 // EXT_draw_buffers by using it in combination with GLES3.0 glDrawBuffers
250 // function. This applies to Tegra K1 devices.
251 int NV_draw_buffers;
252
253 // Set to 1 if highp precision is supported in the fragment language.
254 // Default is 0.
255 int FragmentPrecisionHigh;
256
257 // GLSL ES 3.0 constants.
258 int MaxVertexOutputVectors;
259 int MaxFragmentInputVectors;
260 int MinProgramTexelOffset;
261 int MaxProgramTexelOffset;
262
263 // Name Hashing.
264 // Set a 64 bit hash function to enable user-defined name hashing.
265 // Default is NULL.
266 ShHashFunction64 HashFunction;
267
268 // Selects a strategy to use when implementing array index clamping.
269 // Default is SH_CLAMP_WITH_CLAMP_INTRINSIC.
270 ShArrayIndexClampingStrategy ArrayIndexClampingStrategy;
271
272 // The maximum complexity an expression can be.
273 int MaxExpressionComplexity;
274
275 // The maximum depth a call stack can be.
276 int MaxCallStackDepth;
277} ShBuiltInResources;
278
279//
280// Initialize built-in resources with minimum expected values.
281// Parameters:
282// resources: The object to initialize. Will be comparable with memcmp.
283//
284COMPILER_EXPORT void ShInitBuiltInResources(ShBuiltInResources *resources);
285
286//
287// ShHandle held by but opaque to the driver. It is allocated,
288// managed, and de-allocated by the compiler. Its contents
289// are defined by and used by the compiler.
290//
291// If handle creation fails, 0 will be returned.
292//
293typedef void *ShHandle;
294
295//
296// Returns the a concatenated list of the items in ShBuiltInResources as a
297// null-terminated string.
298// This function must be updated whenever ShBuiltInResources is changed.
299// Parameters:
300// handle: Specifies the handle of the compiler to be used.
301COMPILER_EXPORT const std::string &ShGetBuiltInResourcesString(const ShHandle handle);
302
303//
304// Driver calls these to create and destroy compiler objects.
305//
306// Returns the handle of constructed compiler, null if the requested compiler is
307// not supported.
308// Parameters:
309// type: Specifies the type of shader - GL_FRAGMENT_SHADER or GL_VERTEX_SHADER.
310// spec: Specifies the language spec the compiler must conform to -
311// SH_GLES2_SPEC or SH_WEBGL_SPEC.
312// output: Specifies the output code type - SH_ESSL_OUTPUT, SH_GLSL_OUTPUT,
313// SH_HLSL9_OUTPUT or SH_HLSL11_OUTPUT. Note: HLSL output is only
314// supported in some configurations.
315// resources: Specifies the built-in resources.
316COMPILER_EXPORT ShHandle ShConstructCompiler(
317 sh::GLenum type,
318 ShShaderSpec spec,
319 ShShaderOutput output,
320 const ShBuiltInResources *resources);
321COMPILER_EXPORT void ShDestruct(ShHandle handle);
322
323//
324// Compiles the given shader source.
325// If the function succeeds, the return value is true, else false.
326// Parameters:
327// handle: Specifies the handle of compiler to be used.
328// shaderStrings: Specifies an array of pointers to null-terminated strings
329// containing the shader source code.
330// numStrings: Specifies the number of elements in shaderStrings array.
331// compileOptions: A mask containing the following parameters:
332// SH_VALIDATE: Validates shader to ensure that it conforms to the spec
333// specified during compiler construction.
334// SH_VALIDATE_LOOP_INDEXING: Validates loop and indexing in the shader to
335// ensure that they do not exceed the minimum
336// functionality mandated in GLSL 1.0 spec,
337// Appendix A, Section 4 and 5.
338// There is no need to specify this parameter when
339// compiling for WebGL - it is implied.
340// SH_INTERMEDIATE_TREE: Writes intermediate tree to info log.
341// Can be queried by calling ShGetInfoLog().
342// SH_OBJECT_CODE: Translates intermediate tree to glsl or hlsl shader.
343// Can be queried by calling ShGetObjectCode().
344// SH_VARIABLES: Extracts attributes, uniforms, and varyings.
345// Can be queried by calling ShGetVariableInfo().
346//
347COMPILER_EXPORT bool ShCompile(
348 const ShHandle handle,
349 const char * const shaderStrings[],
350 size_t numStrings,
351 int compileOptions);
352
353// Return the version of the shader language.
354COMPILER_EXPORT int ShGetShaderVersion(const ShHandle handle);
355
356// Return the currently set language output type.
357COMPILER_EXPORT ShShaderOutput ShGetShaderOutputType(
358 const ShHandle handle);
359
360// Returns null-terminated information log for a compiled shader.
361// Parameters:
362// handle: Specifies the compiler
363COMPILER_EXPORT const std::string &ShGetInfoLog(const ShHandle handle);
364
365// Returns null-terminated object code for a compiled shader.
366// Parameters:
367// handle: Specifies the compiler
368COMPILER_EXPORT const std::string &ShGetObjectCode(const ShHandle handle);
369
370// Returns a (original_name, hash) map containing all the user defined
371// names in the shader, including variable names, function names, struct
372// names, and struct field names.
373// Parameters:
374// handle: Specifies the compiler
375COMPILER_EXPORT const std::map<std::string, std::string> *ShGetNameHashingMap(
376 const ShHandle handle);
377
378// Shader variable inspection.
379// Returns a pointer to a list of variables of the designated type.
380// (See ShaderVars.h for type definitions, included above)
381// Returns NULL on failure.
382// Parameters:
383// handle: Specifies the compiler
384COMPILER_EXPORT const std::vector<sh::Uniform> *ShGetUniforms(const ShHandle handle);
385COMPILER_EXPORT const std::vector<sh::Varying> *ShGetVaryings(const ShHandle handle);
386COMPILER_EXPORT const std::vector<sh::Attribute> *ShGetAttributes(const ShHandle handle);
387COMPILER_EXPORT const std::vector<sh::Attribute> *ShGetOutputVariables(const ShHandle handle);
388COMPILER_EXPORT const std::vector<sh::InterfaceBlock> *ShGetInterfaceBlocks(const ShHandle handle);
389
390typedef struct
391{
392 sh::GLenum type;
393 int size;
394} ShVariableInfo;
395
396// Returns true if the passed in variables pack in maxVectors following
397// the packing rules from the GLSL 1.017 spec, Appendix A, section 7.
398// Returns false otherwise. Also look at the SH_ENFORCE_PACKING_RESTRICTIONS
399// flag above.
400// Parameters:
401// maxVectors: the available rows of registers.
402// varInfoArray: an array of variable info (types and sizes).
403// varInfoArraySize: the size of the variable array.
404COMPILER_EXPORT bool ShCheckVariablesWithinPackingLimits(
405 int maxVectors,
406 ShVariableInfo *varInfoArray,
407 size_t varInfoArraySize);
408
409// Gives the compiler-assigned register for an interface block.
410// The method writes the value to the output variable "indexOut".
411// Returns true if it found a valid interface block, false otherwise.
412// Parameters:
413// handle: Specifies the compiler
414// interfaceBlockName: Specifies the interface block
415// indexOut: output variable that stores the assigned register
416COMPILER_EXPORT bool ShGetInterfaceBlockRegister(const ShHandle handle,
417 const std::string &interfaceBlockName,
418 unsigned int *indexOut);
419
420// Gives the compiler-assigned register for uniforms in the default
421// interface block.
422// The method writes the value to the output variable "indexOut".
423// Returns true if it found a valid default uniform, false otherwise.
424// Parameters:
425// handle: Specifies the compiler
426// interfaceBlockName: Specifies the uniform
427// indexOut: output variable that stores the assigned register
428COMPILER_EXPORT bool ShGetUniformRegister(const ShHandle handle,
429 const std::string &uniformName,
430 unsigned int *indexOut);
431
432#endif // GLSLANG_SHADERLANG_H_
433