1//
2// Copyright (c) 2002-2010 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//
10// This is the platform independent interface between an OGL driver
11// and the shading language compiler.
12//
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18// Version number for shader translation API.
19// It is incremented everytime the API changes.
20#define SH_VERSION 103
21
22//
23// The names of the following enums have been derived by replacing GL prefix
24// with SH. For example, SH_INFO_LOG_LENGTH is equivalent to GL_INFO_LOG_LENGTH.
25// The enum values are also equal to the values of their GL counterpart. This
26// is done to make it easier for applications to use the shader library.
27//
28typedef enum {
29  SH_FRAGMENT_SHADER = 0x8B30,
30  SH_VERTEX_SHADER   = 0x8B31
31} ShShaderType;
32
33typedef enum {
34  SH_GLES2_SPEC = 0x8B40,
35  SH_WEBGL_SPEC = 0x8B41
36} ShShaderSpec;
37
38typedef enum {
39  SH_NONE           = 0,
40  SH_INT            = 0x1404,
41  SH_FLOAT          = 0x1406,
42  SH_FLOAT_VEC2     = 0x8B50,
43  SH_FLOAT_VEC3     = 0x8B51,
44  SH_FLOAT_VEC4     = 0x8B52,
45  SH_INT_VEC2       = 0x8B53,
46  SH_INT_VEC3       = 0x8B54,
47  SH_INT_VEC4       = 0x8B55,
48  SH_BOOL           = 0x8B56,
49  SH_BOOL_VEC2      = 0x8B57,
50  SH_BOOL_VEC3      = 0x8B58,
51  SH_BOOL_VEC4      = 0x8B59,
52  SH_FLOAT_MAT2     = 0x8B5A,
53  SH_FLOAT_MAT3     = 0x8B5B,
54  SH_FLOAT_MAT4     = 0x8B5C,
55  SH_SAMPLER_2D     = 0x8B5E,
56  SH_SAMPLER_CUBE   = 0x8B60
57} ShDataType;
58
59typedef enum {
60  SH_INFO_LOG_LENGTH             =  0x8B84,
61  SH_OBJECT_CODE_LENGTH          =  0x8B88,  // GL_SHADER_SOURCE_LENGTH
62  SH_ACTIVE_UNIFORMS             =  0x8B86,
63  SH_ACTIVE_UNIFORM_MAX_LENGTH   =  0x8B87,
64  SH_ACTIVE_ATTRIBUTES           =  0x8B89,
65  SH_ACTIVE_ATTRIBUTE_MAX_LENGTH =  0x8B8A
66} ShShaderInfo;
67
68// Compile options.
69typedef enum {
70  SH_VALIDATE               = 0,
71  SH_VALIDATE_LOOP_INDEXING = 0x0001,
72  SH_INTERMEDIATE_TREE      = 0x0002,
73  SH_OBJECT_CODE            = 0x0004,
74  SH_ATTRIBUTES_UNIFORMS    = 0x0008
75} ShCompileOptions;
76
77//
78// Driver must call this first, once, before doing any other
79// compiler operations.
80// If the function succeeds, the return value is nonzero, else zero.
81//
82int ShInitialize();
83//
84// Driver should call this at shutdown.
85// If the function succeeds, the return value is nonzero, else zero.
86//
87int ShFinalize();
88
89//
90// Implementation dependent built-in resources (constants and extensions).
91// The names for these resources has been obtained by stripping gl_/GL_.
92//
93typedef struct
94{
95    // Constants.
96    int MaxVertexAttribs;
97    int MaxVertexUniformVectors;
98    int MaxVaryingVectors;
99    int MaxVertexTextureImageUnits;
100    int MaxCombinedTextureImageUnits;
101    int MaxTextureImageUnits;
102    int MaxFragmentUniformVectors;
103    int MaxDrawBuffers;
104
105    // Extensions.
106    // Set to 1 to enable the extension, else 0.
107    int OES_standard_derivatives;
108} ShBuiltInResources;
109
110//
111// Initialize built-in resources with minimum expected values.
112//
113void ShInitBuiltInResources(ShBuiltInResources* resources);
114
115//
116// ShHandle held by but opaque to the driver.  It is allocated,
117// managed, and de-allocated by the compiler. It's contents
118// are defined by and used by the compiler.
119//
120// If handle creation fails, 0 will be returned.
121//
122typedef void* ShHandle;
123
124//
125// Driver calls these to create and destroy compiler objects.
126//
127// Returns the handle of constructed compiler.
128// Parameters:
129// type: Specifies the type of shader - SH_FRAGMENT_SHADER or SH_VERTEX_SHADER.
130// spec: Specifies the language spec the compiler must conform to -
131//       SH_GLES2_SPEC or SH_WEBGL_SPEC.
132// resources: Specifies the built-in resources.
133ShHandle ShConstructCompiler(ShShaderType type, ShShaderSpec spec,
134                             const ShBuiltInResources* resources);
135void ShDestruct(ShHandle handle);
136
137//
138// Compiles the given shader source.
139// If the function succeeds, the return value is nonzero, else zero.
140// Parameters:
141// handle: Specifies the handle of compiler to be used.
142// shaderStrings: Specifies an array of pointers to null-terminated strings
143//                containing the shader source code.
144// numStrings: Specifies the number of elements in shaderStrings array.
145// compileOptions: A mask containing the following parameters:
146// SH_VALIDATE: Validates shader to ensure that it conforms to the spec
147//              specified during compiler construction.
148// SH_VALIDATE_LOOP_INDEXING: Validates loop and indexing in the shader to
149//                            ensure that they do not exceed the minimum
150//                            functionality mandated in GLSL 1.0 spec,
151//                            Appendix A, Section 4 and 5.
152//                            There is no need to specify this parameter when
153//                            compiling for WebGL - it is implied.
154// SH_INTERMEDIATE_TREE: Writes intermediate tree to info log.
155//                       Can be queried by calling ShGetInfoLog().
156// SH_OBJECT_CODE: Translates intermediate tree to glsl or hlsl shader.
157//                 Can be queried by calling ShGetObjectCode().
158// SH_ATTRIBUTES_UNIFORMS: Extracts attributes and uniforms.
159//                         Can be queried by calling ShGetActiveAttrib() and
160//                         ShGetActiveUniform().
161//
162int ShCompile(
163    const ShHandle handle,
164    const char* const shaderStrings[],
165    const int numStrings,
166    int compileOptions
167    );
168
169// Returns a parameter from a compiled shader.
170// Parameters:
171// handle: Specifies the compiler
172// pname: Specifies the parameter to query.
173// The following parameters are defined:
174// SH_INFO_LOG_LENGTH: the number of characters in the information log
175//                     including the null termination character.
176// SH_OBJECT_CODE_LENGTH: the number of characters in the object code
177//                        including the null termination character.
178// SH_ACTIVE_ATTRIBUTES: the number of active attribute variables.
179// SH_ACTIVE_ATTRIBUTE_MAX_LENGTH: the length of the longest active attribute
180//                                 variable name including the null
181//                                 termination character.
182// SH_ACTIVE_UNIFORMS: the number of active uniform variables.
183// SH_ACTIVE_UNIFORM_MAX_LENGTH: the length of the longest active uniform
184//                               variable name including the null
185//                               termination character.
186//
187// params: Requested parameter
188void ShGetInfo(const ShHandle handle, ShShaderInfo pname, int* params);
189
190// Returns nul-terminated information log for a compiled shader.
191// Parameters:
192// handle: Specifies the compiler
193// infoLog: Specifies an array of characters that is used to return
194//          the information log. It is assumed that infoLog has enough memory
195//          to accomodate the information log. The size of the buffer required
196//          to store the returned information log can be obtained by calling
197//          ShGetInfo with SH_INFO_LOG_LENGTH.
198void ShGetInfoLog(const ShHandle handle, char* infoLog);
199
200// Returns null-terminated object code for a compiled shader.
201// Parameters:
202// handle: Specifies the compiler
203// infoLog: Specifies an array of characters that is used to return
204//          the object code. It is assumed that infoLog has enough memory to
205//          accomodate the object code. The size of the buffer required to
206//          store the returned object code can be obtained by calling
207//          ShGetInfo with SH_OBJECT_CODE_LENGTH.
208void ShGetObjectCode(const ShHandle handle, char* objCode);
209
210// Returns information about an active attribute variable.
211// Parameters:
212// handle: Specifies the compiler
213// index: Specifies the index of the attribute variable to be queried.
214// length: Returns the number of characters actually written in the string
215//         indicated by name (excluding the null terminator) if a value other
216//         than NULL is passed.
217// size: Returns the size of the attribute variable.
218// type: Returns the data type of the attribute variable.
219// name: Returns a null terminated string containing the name of the
220//       attribute variable. It is assumed that name has enough memory to
221//       accomodate the attribute variable name. The size of the buffer
222//       required to store the attribute variable name can be obtained by
223//       calling ShGetInfo with SH_ACTIVE_ATTRIBUTE_MAX_LENGTH.
224void ShGetActiveAttrib(const ShHandle handle,
225                       int index,
226                       int* length,
227                       int* size,
228                       ShDataType* type,
229                       char* name);
230
231// Returns information about an active uniform variable.
232// Parameters:
233// handle: Specifies the compiler
234// index: Specifies the index of the uniform variable to be queried.
235// length: Returns the number of characters actually written in the string
236//         indicated by name (excluding the null terminator) if a value
237//         other than NULL is passed.
238// size: Returns the size of the uniform variable.
239// type: Returns the data type of the uniform variable.
240// name: Returns a null terminated string containing the name of the
241//       uniform variable. It is assumed that name has enough memory to
242//       accomodate the uniform variable name. The size of the buffer required
243//       to store the uniform variable name can be obtained by calling
244//       ShGetInfo with SH_ACTIVE_UNIFORMS_MAX_LENGTH.
245void ShGetActiveUniform(const ShHandle handle,
246                        int index,
247                        int* length,
248                        int* size,
249                        ShDataType* type,
250                        char* name);
251
252#ifdef __cplusplus
253}
254#endif
255
256#endif // _COMPILER_INTERFACE_INCLUDED_
257