1Name
2
3    CHROMIUM_bind_uniform_location
4
5Name Strings
6
7    GL_CHROMIUM_bind_uniform_location
8
9Version
10
11    Last Modifed Date: September 8, 2015
12
13Dependencies
14
15    OpenGL ES 2.0 is required.
16
17Overview
18
19    This extension is simlar to glBindAttribLocation but instead
20    lets you choose a location for a uniform. This allows you
21    to not have to query the locations of uniforms.
22
23    This allows the client program to know the locations of uniforms
24    without having to wait for shaders to compile or GLSL programs to
25    link to query the locations and therefore have no blocking calls
26    when initializing programs.
27
28Issues
29
30    If a uniform is an array you can only call glBindUniformLocation
31    for the location of the first element. Other elements' locations
32    must be queried if you need them. Often this is not an issue
33    because you can set all the elements with a single gl call from
34    the first location.
35
36    Good Example:
37
38        --shader--
39        uniform float u_someArray[4];
40
41        --C--
42        GLint location = 123;
43        glBindUniformLocation(program, location, "u_someArray");
44        glLinkProgram(program);
45        glUseProgram(program);
46
47        // set all 4 floats in u_someArray
48        float values[] = { 0.1f, 0.2f, 0.3f, 0.4f, };
49        glUniform1fv(location, 4, values);
50
51    Bad example 1:
52
53        GLint location = 123;
54        glBindUniformLocation(program, location, "u_someArray");
55        glLinkProgram(program);
56        glUseProgram(program);
57
58        // set floats in u_someArray one at a time
59        glUniform1f(location, 0.1f);
60        glUniform1f(location + 1, 0.2f);  // ERROR! math not allowed on locations
61
62    Bad example 2:
63
64        GLint location0 = 123;
65        GLint location1 = 124;
66        glBindUniformLocation(program, location0, "u_someArray[0]");
67        glBindUniformLocation(program, location1, "u_someArray[1]"); // ERROR!
68        // not allowed to assign locations to array elements
69
70    If you need to set individual elements of a uniform array you must query the
71    location of the each element you wish to set.
72
73    If a uniform has its location explicitly set within the shader text and a
74    different location set via the API, the assignment in the shader text is
75    used.
76
77    If the location of a statically used uniform set via the API conflicts with
78    the location of a different uniform set in the shader text, linking must
79    fail.
80
81New Tokens
82
83    None
84
85New Procedures and Functions
86
87    void BindUniformLocationCHROMIUM (GLuint program, GLint location,
88                                      const GLhchar* name);
89
90    specifes that the uniform variable named <name> in program <program>
91    should be bound to uniform location <location> when the program is next
92    linked.  If <name> was bound previously, its assigned binding is replaced
93    with <location>. <name> must be a null terminated string.  The error
94    INVALID_VALUE is generated if <location> is equal or greater than
95
96    (MAX_VERTEX_UNIFORM_VECTORS + MAX_FRAGMENT_UNIFORM_VECTORS) * 4
97
98    or less than 0. BindUniformLocation has no effect until the program is
99    linked. In particular, it doesn't modify the bindings of uniform
100    variables in a program that has already been linked.
101
102    The error INVALID_OPERATION is generated if name starts with the reserved
103    "gl_" prefix. The error INVALID_VALUE is generated if name ends with
104    an array element expression other than "[0]".
105
106    When a program is linked, any active uniforms without a binding specified
107    through BindUniformLocation will be automatically be bound to locations by
108    the GL.  Such bindings can be queried using the command
109    GetUniformLocation.
110
111    BindUniformLocation may be issued before any shader objects are attached
112    to a program object.  Hence it is allowed to bind any name (except a name
113    starting with "gl_") to an index, including a name that is never used as a
114    uniform in any shader object.  Assigned bindings for uniform variables
115    that do not exist or are not active are ignored. Using such bindings
116    behaves as if passed location was -1.
117
118    It is possible for an application to bind more than one uniform name to
119    the same location.  This is referred to as aliasing.  This will only work
120    if only one of the aliased uniforms is statically used in the executable
121    program.  If two statically used uniforms in a program are bound to the same
122    location, link must fail.
123
124Errors
125
126    None.
127
128New State
129
130    None.
131
132Revision History
133
134    7/20/2012    Documented the extension
135    9/8/2015     Require program link to fail if two statically used uniforms
136                 are bound to the same location.
137    11/6/2015    Require inactive and non-existing, bound uniform locations
138                 to behave like location -1.
139    3/9/2017     Locations set in the shader override ones set by the binding
140                 API.
141    3/26/2018    Clarify that aliasing rules apply to statically used uniforms.