gpu/GLES2/extensions/CHROMIUM/CHROMIUM_bind_uniform_location.txt

   1 Name
   2
   3     CHROMIUM_bind_uniform_location
   4
   5 Name Strings
   6
   7     GL_CHROMIUM_bind_uniform_location
   8
   9 Version
  10
  11     Last Modifed Date: June 20, 2012
  12
  13 Dependencies
  14
  15     OpenGL ES 2.0 is required.
  16
  17 Overview
  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
  28 Issues
  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 New Tokens
  74
  75     None
  76
  77 New Procedures and Functions
  78
  79     void BindUniformLocationCHROMIUM (GLuint program, GLint location,
  80                                       const GLhchar* name);
  81
  82     specifes that the uniform variable named <name> in program <program>
  83     should be bound to uniform location <location> when the program is next
  84     linked.  If <name> was bound previously, its assigned binding is replaced
  85     with <location>. <name> must be a null terminated string.  The error
  86     INVALID_VALUE is generated if <location> is equal or greater than
  87
  88     (MAX_VERTEX_UNIFORM_VECTORS + MAX_FRAGMENT_UNIFORM_VECTORS) * 4
  89
  90     or less than 0. BindUniformLocation has no effect until the program is
  91     linked. In particular, it doesn't modify the bindings of active uniforms
  92     variables in a program that has already been linked.
  93
  94     The error INVALID_OPERATION is generated if name starts with the reserved
  95     "gl_" prefix. The error INVALID_VALUE is generated if name ends with
  96     an array element expression other than "[0]".
  97
  98     When a program is linked, any active uniforms without a binding specified
  99     through BindUniformLocation will be automatically be bound to locations by
 100     the GL.  Such bindings can be queried using the command
 101     GetUniformLocation.
 102
 103     BindUniformLocation may be issued before any shader objects are attached
 104     to a program object.  Hence it is allowed to bind any name (except a name
 105     starting with "gl_") to an index, including a name that is never used as a
 106     uniform in any shader object.  Assigned bindings for uniform variables
 107     that do not exist or are not active are ignored.
 108
 109     It is possible for an application to bind more than one uniform name to
 110     the same location.  This is referred to as aliasing.  This will only work
 111     if only one of the aliased uniforms is active in the executable program,
 112     or if no path through the shader consumes more than one uniform of a set
 113     of uniforms aliased to the same location.  A link error can occur if the
 114     linker determines that every path through the shader consumes multiple
 115     aliased uniforms, but implementations are not required to generate an
 116     error in this case.  The compiler and linker are allowed to assume that no
 117     aliasing is done, and may employ optimizations that work only in the
 118     absence of aliasing.
 119
 120 Errors
 121
 122     None.
 123
 124 New State
 125
 126     None.
 127
 128 Revision History
 129
 130     7/20/2012    Documented the extension
 131