blob: f2c2665d36519af1f381a29d5c6fcd9b48ad9cdc [file] [log] [blame]
Name
ARB_program_interface_query
Name Strings
GL_ARB_program_interface_query
Contact
Pat Brown, NVIDIA (pbrown 'at' nvidia.com)
Contributors
Members of the Khronos OpenGL ARB TSG
Notice
Copyright (c) 2012-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the ARB on 2012/06/12.
Version
Last Modified Date: August 19, 2013
Revision: 20
Number
ARB Extension #134
Dependencies
OpenGL 2.0 is required.
This extension is written against the OpenGL 4.2 Compatibility Profile
Specification (January 19, 2012).
OpenGL 3.0, ARB_transform_feedback, and EXT_transform_feedback affect the
definition of this extension.
OpenGL 3.1 and ARB_uniform_buffer_object affect the definition of this
extension.
OpenGL 4.0 and ARB_shader_subroutine affect the definition of this
extension.
OpenGL 4.2 and ARB_shader_atomic_counters affect the definition of this
extension.
OpenGL 4.3 and ARB_shader_storage_buffer_object affect the definition of
this extension.
OpenGL 4.3 and ARB_arrays_of_arrays affect the definition of this
extension.
OpenGL 4.3 and ARB_compute_shader affect the definition of this extension.
OpenGL 4.3 and ARB_explicit_uniform_location affect the definition of this
extension.
Overview
This extension provides a single unified set of query commands that can be
used by applications to determine properties of various interfaces and
resources used by program objects to communicate with application code,
fixed-function OpenGL pipeline stages, and other programs. In unextended
OpenGL 4.2, there is a separate set of query commands for each different
type of interface or resource used by the program. These different sets
of queries are structured nearly identically, but the queries for some
interfaces have limited capability (e.g., there is no ability to enumerate
fragment shader outputs).
With the single set of query commands provided by this extension, a
consistent set of queries is available for all interfaces, and a new
interface can be added without having to introduce a completely new set of
query commands. These queries are intended to provide a superset of the
capabilities provided by similar queries in OpenGL 4.2, and should allow
for the deprecation of the existing queries.
This extension defines two terms: interfaces and active resources. Each
interface of a program object provides a way for the program to
communicate with application code, fixed-function OpenGL pipeline stages,
and other programs. Examples of interfaces for a program object include
inputs (receiving values from vertex attributes or outputs of other
programs), outputs (sending values to other programs or per-fragment
operations), uniforms (receiving values from API calls), uniform blocks
(receiving values from bound buffer objects), subroutines and subroutine
uniforms (receiving API calls to indicate functions to call during program
execution), and atomic counter buffers (holding values to be manipulated
by atomic counter shader functions). Each interface of a program has a
set of active resources used by the program. For example, the resources
of a program's input interface includes all active input variables used by
the first stage of the program. The resources of a program's uniform
block interface consists of the set of uniform blocks with at least one
member used by any shader in the program.
IP Status
No known IP claims.
New Procedures and Functions
void GetProgramInterfaceiv(uint program, enum programInterface,
enum pname, int *params);
uint GetProgramResourceIndex(uint program, enum programInterface,
const char *name);
void GetProgramResourceName(uint program, enum programInterface,
uint index, sizei bufSize, sizei *length,
char *name);
void GetProgramResourceiv(uint program, enum programInterface,
uint index, sizei propCount,
const enum *props, sizei bufSize,
sizei *length, int *params);
int GetProgramResourceLocation(uint program, enum programInterface,
const char *name);
int GetProgramResourceLocationIndex(uint program, enum programInterface,
const char *name);
New Tokens
Accepted by the <programInterface> parameter of GetProgramInterfaceiv,
GetProgramResourceIndex, GetProgramResourceName, GetProgramResourceiv,
GetProgramResourceLocation, and GetProgramResourceLocationIndex:
UNIFORM 0x92E1
UNIFORM_BLOCK 0x92E2
PROGRAM_INPUT 0x92E3
PROGRAM_OUTPUT 0x92E4
BUFFER_VARIABLE 0x92E5
SHADER_STORAGE_BLOCK 0x92E6
ATOMIC_COUNTER_BUFFER (already in 4.2)
VERTEX_SUBROUTINE 0x92E8
TESS_CONTROL_SUBROUTINE 0x92E9
TESS_EVALUATION_SUBROUTINE 0x92EA
GEOMETRY_SUBROUTINE 0x92EB
FRAGMENT_SUBROUTINE 0x92EC
COMPUTE_SUBROUTINE 0x92ED
VERTEX_SUBROUTINE_UNIFORM 0x92EE
TESS_CONTROL_SUBROUTINE_UNIFORM 0x92EF
TESS_EVALUATION_SUBROUTINE_UNIFORM 0x92F0
GEOMETRY_SUBROUTINE_UNIFORM 0x92F1
FRAGMENT_SUBROUTINE_UNIFORM 0x92F2
COMPUTE_SUBROUTINE_UNIFORM 0x92F3
TRANSFORM_FEEDBACK_VARYING 0x92F4
Accepted by the <pname> parameter of GetProgramInterfaceiv:
ACTIVE_RESOURCES 0x92F5
MAX_NAME_LENGTH 0x92F6
MAX_NUM_ACTIVE_VARIABLES 0x92F7
MAX_NUM_COMPATIBLE_SUBROUTINES 0x92F8
Accepted in the <props> array of GetProgramResourceiv:
NAME_LENGTH 0x92F9
TYPE 0x92FA
ARRAY_SIZE 0x92FB
OFFSET 0x92FC
BLOCK_INDEX 0x92FD
ARRAY_STRIDE 0x92FE
MATRIX_STRIDE 0x92FF
IS_ROW_MAJOR 0x9300
ATOMIC_COUNTER_BUFFER_INDEX 0x9301
BUFFER_BINDING 0x9302
BUFFER_DATA_SIZE 0x9303
NUM_ACTIVE_VARIABLES 0x9304
ACTIVE_VARIABLES 0x9305
REFERENCED_BY_VERTEX_SHADER 0x9306
REFERENCED_BY_TESS_CONTROL_SHADER 0x9307
REFERENCED_BY_TESS_EVALUATION_SHADER 0x9308
REFERENCED_BY_GEOMETRY_SHADER 0x9309
REFERENCED_BY_FRAGMENT_SHADER 0x930A
REFERENCED_BY_COMPUTE_SHADER 0x930B
TOP_LEVEL_ARRAY_SIZE 0x930C
TOP_LEVEL_ARRAY_STRIDE 0x930D
LOCATION 0x930E
LOCATION_INDEX 0x930F
IS_PER_PATCH 0x92E7
NUM_COMPATIBLE_SUBROUTINES (already in 4.2)
COMPATIBLE_SUBROUTINES (already in 4.2)
Additions to Chapter 2 of the OpenGL 4.2 (Compatibility Profile) Specification
(OpenGL Operation)
Modify Section 2.14.3, Program Objects (p. 97)
(insert at the end of the section, p. 101)
Program Interfaces
When a program object is made part of the current rendering state, its
executable code may communicate with other GL pipeline stages or
application code through a variety of /interfaces/. When a program is
linked, the GL builds a list of /active resources/ for each interface.
Examples of active resources include variables, interface blocks, and
subroutines used by shader code. Resources referenced in shader code are
considered /active/ unless the compiler and linker can conclusively
determine that they have no observable effect on the results produced by
the executable code of the program. For example, variables might be
considered inactive if they are declared but not used in executable code,
used only in a clause of an "if" statement that would never be executed,
used only in functions that are never called, or used only in computations
of temporary variables having no effect on any shader output. In cases
where the compiler or linker cannot make a conclusive determination, any
resource referenced by shader code will be considered active. The set of
active resources on for any interface is implementation-dependent because
it depends on various analysis and optimizations performed by the compiler
and linker.
If a program is linked successfully, the GL will generate lists of active
resources based on the executable code produced by the link. If a program
is linked unsuccessfully, the link may have failed for a number of
reasons, including cases where the program required more resources than
supported by the implementation. Implementations are permitted, but not
required, to record lists of resources that would have been considered
active had the program linked successfully. If an implementation does not
record information for any given interface, the corresponding list of
active resources is considered empty. If a program has never been linked,
all lists of active resources are considered empty.
The GL provides a number of commands to query properties of the interfaces
of a program object. Each such command accepts a <programInterface>
token, identifying a specific interface. The supported values for
<programInterface> are as follows:
* UNIFORM corresponds to the set of active uniform variables (section
2.14.7) used by <program>.
* UNIFORM_BLOCK corresponds to the set of active uniform blocks (section
2.14.7) used by <program>.
* ATOMIC_COUNTER_BUFFER corresponds to the set of active atomic counter
buffer binding points (section 2.14.7) used by <program>.
* PROGRAM_INPUT corresponds to the set of active input variables used by
the first shader stage of <program>. If <program> includes multiple
shader stages, input variables from any shader stage other than the
first will not be enumerated.
* PROGRAM_OUTPUT corresponds to the set of active output variables
(section 2.14.11) used by the last shader stage of <program>. If
<program> includes multiple shader stages, output variables from any
shader stage other than the last will not be enumerated.
* VERTEX_SUBROUTINE, TESS_CONTROL_SUBROUTINE,
TESS_EVALUATION_SUBROUTINE, GEOMETRY_SUBROUTINE, FRAGMENT_SUBROUTINE,
and COMPUTE_SUBROUTINE correspond to the set of active subroutines for
the vertex, tessellation control, tessellation evaluation, geometry,
fragment, and compute shader stages of <program>, respectively
(section 2.14.8).
* VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_SUBROUTINE_UNIFORM,
TESS_EVALUATION_SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_UNIFORM,
FRAGMENT_SUBROUTINE_UNIFORM, and COMPUTE_SUBROUTINE_UNIFORM correspond
to the set of active subroutine uniform variables used by the vertex,
tessellation control, tessellation evaluation, geometry, fragment, and
compute shader stages of <program>, respectively (section 2.14.8).
* TRANSFORM_FEEDBACK_VARYING corresponds to the set of output variables
in the last non-fragment stage of <program> that would be captured
when transform feedback is active (section 2.20.2).
* BUFFER_VARIABLE corresponds to the set of active buffer variables (see
the ARB_shader_storage_buffer_object extension) used by <program>.
* SHADER_STORAGE_BLOCK corresponds to the set of active shader storage
blocks (see the ARB_shader_storage_buffer_object extension) used by
<program>.
When building a list of active variable or interface blocks, resources
with aggregate types (such as arrays or structures) may produce multiple
entries in the active resource list for the corresponding interface.
Additionally, each active variable, interface block, or subroutine in the
list is assigned an associated name string that can be used by
applications to refer to the resources. For interfaces involving
variables, interface blocks, or subroutines, the entries of active
resource lists are generated as follows:
* For an active variable declared as a single instance of a basic type,
a single entry will be generated, using the variable name from the
shader source.
* For an active variable declared as an array of basic types, a single
entry will be generated, with its name string formed by concatenating
the name of the array and the string "[0]".
* For an active variable declared as a structure, a separate entry will
be generated for each active structure member. The name of each entry
is formed by concatenating the name of the structure, the "."
character, and the name of the structure member. If a structure
member to enumerate is itself a structure or array, these enumeration
rules are applied recursively.
* For an active variable declared as an array of an aggregate data type
(structures or arrays), a separate entry will be generated for each
active array element, unless noted immediately below. The name of
each entry is formed by concatenating the name of the array, the "["
character, an integer identifying the element number, and the "]"
character. These enumeration rules are applied recursively, treating
each enumerated array element as a separate active variable.
* For an active shader storage block member declared as an array, an
entry will be generated only for the first array element, regardless
of its type. For arrays of aggregate types, the enumeration rules are
applied recursively for the single enumerated array element.
* For an active interface block not declared as an array of block
instances, a single entry will be generated, using the block name from
the shader source.
* For an active interface block declared as an array of instances,
separate entries will be generated for each active instance. The name
of the instance is formed by concatenating the block name, the "["
character, an integer identifying the instance number, and the "]"
character.
* For an active subroutine, a single entry will be generated, using the
subroutine name from the shader source.
When an integer array element or block instance number is part of the name
string, it will be specified in decimal form without a "+" or "-" sign or
any extra leading zeroes. Additionally, the name string will not include
white space anywhere in the string.
The order of the active resource list is implementation-dependent for all
interfaces except for TRANSFORM_FEEDBACK_VARYING. For
TRANSFORM_FEEDBACK_VARYING, the active resource list will use the variable
order specified in the the most recent call to TransformFeedbackVaryings
before the last call to LinkProgram.
For the ATOMIC_COUNTER_BUFFER interface, the list of active buffer binding
points is built by identifying each unique binding point associated with
one or more active atomic counter uniform variables. Active atomic
counter buffers do not have an associated name string.
For the UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT, and
TRANSFORM_FEEDBACK_VARYING interfaces, the active resource list will
include all active variables for the interface, including any active
built-in variables.
For PROGRAM_INPUT and PROGRAM_OUTPUT interfaces for shaders that recieve
or produce patch primitves, the active resource list will include both
per-vertex and per-patch inputs and outputs.
For the TRANSFORM_FEEDBACK_VARYING interface, the active resource list
will entries for the special varying names gl_NextBuffer,
gl_SkipComponents1, gl_SkipComponents2, gl_SkipComponents3, and
gl_SkipComponents4 (section 2.14.11). These variables are used to control
how varying values are written to transform feedback buffers. When
enumerating the properties of such resources, these variables are
considered to have a TYPE of NONE and an ARRAY_SIZE of 0 (gl_NextBuffer),
1, 2, 3, and 4, respectively.
When a program is linked successfully, active variables in the UNIFORM,
PROGRAM_INPUT, PROGRAM_OUTPUT interface, or in any of the subroutine
uniform interfaces, are assigned one or more signed integer /locations/.
These locations can be used by commands to assign values to uniforms and
subroutine uniforms, to identify generic vertex attributes associated with
vertex shader inputs, or to identify fragment color output numbers and
indices associated with fragment shader outputs. For such variables
declared as arrays, separate locations will be assigned to each active
array element. Not all active variables are assigned valid locations; the
following variables will have an effective location of -1:
* uniforms declared as atomic counters;
* members of a uniform block;
* built-in inputs, outputs, and uniforms (starting with "gl_"); and
* inputs or outputs not declared with a "location" layout qualifier,
except for vertex shader inputs and fragment shader outputs.
If a program has not been linked or has was last linked unsuccessfully, no
locations will be assigned.
The command
void GetProgramInterfaceiv(uint program, enum programInterface,
enum pname, int *params);
queries a property of the interface <programInterface> in program
<program>, returning its value in <params>. The property to return is
specified by <pname>.
If <pname> is ACTIVE_RESOURCES, the value returned is the number of
resources in the active resource list for <programInterface>. If the list
of active resources for <programInterface> is empty, zero is returned.
If <pname> is MAX_NAME_LENGTH, the value returned is the length of the
longest active name string for an active resource in <programInterface>.
This length includes an extra character for the null terminator. If the
list of active resources for <programInterface> is empty, zero is
returned. The error INVALID_OPERATION is generated if <programInterface>
is ATOMIC_COUNTER_BUFFER, since active atomic counter buffer resources are
not assigned name strings.
If <pname> is MAX_NUM_ACTIVE_VARIABLES, the value returned is the number
of active variables belonging to the interface block or atomic counter
buffer resource in <programInterface> with the most active variables. If
the list of active resources for <programInterface> is empty, zero is
returned. The error INVALID_OPERATION is generated if <programInterface>
is not UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER, or SHADER_STORAGE_BLOCK.
If <pname> is MAX_NUM_COMPATIBLE_SUBROUTINES, the value returned is the
number of compatible subroutines belonging to the active subroutine
uniform in <programInterface> with the most compatible subroutines. If
the list of active resources for <programInterface> is empty, zero is
returned. The error INVALID_OPERATION is generated unless
<programInterface> is VERTEX_SUBROUTINE_UNIFORM,
TESS_CONTROL_SUBROUTINE_UNIFORM, TESS_EVALUATION_SUBROUTINE_UNIFORM,
GEOMETRY_SUBROUTINE_UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM, or
COMPUTE_SUBROUTINE_UNIFORM.
Each entry in the active resource list for an interface is assigned a
unique unsigned integer index in the range 0..<N>-1, where <N> is the
number of entries in the active resource list. The command
uint GetProgramResourceIndex(uint program, enum programInterface,
const char *name);
returns the unsigned integer index assigned to a resource named <name> in
the interface type <programInterface> of program object <program>. The
error INVALID_ENUM is generated if <programInterface> is
ATOMIC_COUNTER_BUFFER, since active atomic counter buffer resources are
not assigned name strings.
If <name> exactly matches the name string of one of the active resources
for <programInterface>, the index of the matched resource is returned.
Additionally, if <name> would exactly match the name string of an active
resource if "[0]" were appended to <name>, the index of the matched
resource is returned. Otherwise, <name> is considered not to be the name
of an active resource, and INVALID_INDEX is returned. Note that if an
interface enumerates a single active resource list entry for an array
variable (e.g., "a[0]"), a <name> identifying any array element other than
the first (e.g., "a[1]") is not considered to match.
For the interface TRANSFORM_FEEDBACK_VARYING, the value INVALID_INDEX
should be returned when querying the index assigned to the special names
"gl_NextBuffer", "gl_SkipComponents1", "gl_SkipComponents2",
"gl_SkipComponents3", and "gl_SkipComponents4".
The command
void GetProgramResourceName(uint program, enum programInterface,
uint index, sizei bufSize, sizei *length,
char *name);
returns the name string assigned to the single active resource with an
index of <index> in the interface <programInterface> of program object
<program>. The error INVALID_VALUE is generated if <index> is greater
than or equal to the number of entries in the active resource list for
<programInterface>. The error INVALID_ENUM is generated if
<programInterface> is ATOMIC_COUNTER_BUFFER, since active atomic counter
buffer resources are not assigned name strings.
The name string assigned to the active resource identified by <index> is
returned as a null-terminated string in <name>. The actual number of
characters written into <name>, excluding the null terminator, is returned
in <length>. If <length> is NULL, no length is returned. The maximum
number of characters that may be written into <name>, including the null
terminator, is specified by <bufSize>. If the length of the name string
(including the null terminator) is greater than <bufSize>, the first
<bufSize>-1 characters of the name string will be written to <name>,
followed by a null terminator. If <bufSize> is zero, no error will be
generated but no characters will be written to <name>. The length of the
longest name string for <programInterface>, including a null terminator,
can be queried by calling GetProgramInterfaceiv with a <pname> of
MAX_NAME_LENGTH.
The command
void GetProgramResourceiv(uint program, enum programInterface,
uint index, sizei propCount,
const enum *props, sizei bufSize,
sizei *length, int *params);
returns values for multiple properties of a single active resource with an
index of <index> in the interface <programInterface> of program object
<program>. For each resource, values for <propCount> properties specified
by the array <props> are returned. The error INVALID_VALUE is generated
if <propCount> is zero. The error INVALID_ENUM is generated if any value
in <props> is not one of the properties described immediately below. The
error INVALID_OPERATION is generated if any value in <props> is not
allowed for <programInterface>. The set of allowed <programInterface>
values for each property can be found in Table X.1.
The values associated with the properties of the active resource are
written to consecutive entries in <params>, in increasing order according
to position in <props>. If no error is generated, only the first
<bufSize> integer values will be written to <params>; any extra values
will not be returned. If <length> is not NULL, the actual number of
integer values written to <params> will be written to <length>.
Property Supported Interfaces
--------------------------- ----------------------------------------
NAME_LENGTH all but ATOMIC_COUNTER_BUFFER
TYPE UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT,
TRANSFORM_FEEDBACK_VARYING,
BUFFER_VARIABLE
ARRAY_SIZE UNIFORM, BUFFER_VARIABLE, PROGRAM_INPUT,
PROGRAM_OUTPUT, VERTEX_SUBROUTINE_
UNIFORM, TESS_CONTROL_SUBROUTINE_UNIFORM,
TESS_EVALUATION_SUBROUTINE_UNIFORM,
GEOMETRY_SUBROUTINE_UNIFORM, FRAGMENT_
SUBROUTINE_UNIFORM, COMPUTE_SUBROUTINE_
UNIFORM, TRANSFORM_FEEDBACK_VARYING
OFFSET UNIFORM, BUFFER_VARIABLE
BLOCK_INDEX UNIFORM, BUFFER_VARIABLE
ARRAY_STRIDE UNIFORM, BUFFER_VARIABLE
MATRIX_STRIDE UNIFORM, BUFFER_VARIABLE
IS_ROW_MAJOR UNIFORM, BUFFER_VARIABLE
ATOMIC_COUNTER_BUFFER_INDEX UNIFORM
BUFFER_BINDING UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER,
SHADER_STORAGE_BLOCK
BUFFER_DATA_SIZE UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER
SHADER_STORAGE_BLOCK
NUM_ACTIVE_VARIABLES UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER
SHADER_STORAGE_BLOCK
ACTIVE_VARIABLES UNIFORM_BLOCK, ATOMIC_COUNTER_BUFFER
SHADER_STORAGE_BLOCK
REFERENCED_BY_VERTEX_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_
SHADER BUFFER, SHADER_STORAGE_BLOCK,
BUFFER_VARIABLE, PROGRAM_INPUT,
PROGRAM_OUTPUT
REFERENCED_BY_TESS_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_
CONTROL_SHADER BUFFER, SHADER_STORAGE_BLOCK,
BUFFER_VARIABLE, PROGRAM_INPUT,
PROGRAM_OUTPUT
REFERENCED_BY_TESS_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_
EVALUATION_SHADER BUFFER, SHADER_STORAGE_BLOCK,
BUFFER_VARIABLE, PROGRAM_INPUT,
PROGRAM_OUTPUT
REFERENCED_BY_GEOMETRY_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_
SHADER BUFFER, SHADER_STORAGE_BLOCK,
BUFFER_VARIABLE, PROGRAM_INPUT,
PROGRAM_OUTPUT
REFERENCED_BY_FRAGMENT_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_
SHADER BUFFER, SHADER_STORAGE_BLOCK,
BUFFER_VARIABLE, PROGRAM_INPUT,
PROGRAM_OUTPUT
REFERENCED_BY_COMPUTE_ UNIFORM, UNIFORM_BLOCK, ATOMIC_COUNTER_
SHADER BUFFER, SHADER_STORAGE_BLOCK,
BUFFER_VARIABLE, PROGRAM_INPUT,
PROGRAM_OUTPUT
NUM_COMPATIBLE_SUBROUTINES VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_
SUBROUTINE_UNIFORM, TESS_EVALUATION_
SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_
UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM,
COMPUTE_SUBROUTINE_UNIFORM
COMPATIBLE_SUBROUTINES VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_
SUBROUTINE_UNIFORM, TESS_EVALUATION_
SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_
UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM,
COMPUTE_SUBROUTINE_UNIFORM
TOP_LEVEL_ARRAY_SIZE BUFFER_VARIABLE
TOP_LEVEL_ARRAY_STRIDE BUFFER_VARIABLE
LOCATION UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT,
VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_
SUBROUTINE_UNIFORM, TESS_EVALUATION_
SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_
UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM,
COMPUTE_SUBROUTINE_UNIFORM
LOCATION_INDEX PROGRAM_OUTPUT
IS_PER_PATCH PROGRAM_INPUT, PROGRAM_OUTPUT
Table X.1, GetProgramResourceiv properties and supported interfaces
For the property NAME_LENGTH, a single integer identifying the length of
the name string associated with an active variable, interface block, or
subroutine is written to <params>. The name length includes a terminating
null character.
For the property TYPE, a single integer identifying the type of an active
variable is written to <params>. The integer returned is one of the
values found in table 2.16.
For the property ARRAY_SIZE, a single integer identifying the number of
active array elements of an active variable is written to <params>. The
array size returned is in units of the type associated with the property
TYPE. For active variables not corresponding to an array of basic types,
the value one is written to <params>. If the variable is a shader
storage block member in an array with no declared size, the value zero
is written to <params>.
For the property BLOCK_INDEX, a single integer identifying the index of
the active interface block containing an active variable is written to
<params>. If the variable is not the member of an interface block, the
value -1 is written to <params>.
For the property OFFSET, a single integer identifying the offset of an
active variable is written to <params>. For active variables backed by a
buffer object, the value written is the offset, in basic machine units,
relative to the base of buffer range holding the values of the variable.
For active variables not backed by a buffer object, an offset of -1 is
written to <params>.
For the property ARRAY_STRIDE, a single integer identifying the stride
between array elements in an active variable is written to <params>. For
active variables declared as an array of basic types, the value written is
the difference, in basic machine units, between the offsets of consecutive
elements in an array. For active variables not declared as an array of
basic types, zero is written to <params>. For active variables not backed
by a buffer object, -1 is written to <params>, regardless of the variable
type.
For the property MATRIX_STRIDE, a single integer identifying the stride
between columns of a column-major matrix or rows of a row-major matrix is
written to <params>. For active variables declared a single matrix or
array of matrices, the value written is the difference, in basic machine
units, between the offsets of consecutive columns or rows in each matrix.
For active variables not declared as a matrix or array of matrices, zero
is written to <params>. For active variables not backed by a buffer
object, -1 is written to <params>, regardless of the variable type.
For the property IS_ROW_MAJOR, a single integer identifying whether an
active variable is a row-major matrix is written to <params>. For active
variables backed by a buffer object, declared as a single matrix or array
of matrices, and stored in row-major order, one is written to <params>.
For all other active variables, zero is written to <params>.
For the property ATOMIC_COUNTER_BUFFER_INDEX, a single integer identifying
the index of the active atomic counter buffer containing an active
variable is written to <params>. If the variable is not an atomic counter
uniform, the value -1 is written to <params>.
For the property of BUFFER_BINDING, to index of the buffer binding point
associated with the active uniform block, shader storage block, or atomic
counter buffer is written to <params>.
For the property of BUFFER_DATA_SIZE, then the implementation-dependent
minimum total buffer object size, in basic machine units, required to hold
all active variables associated with an active uniform block, shader
storage block, or atomic counter buffer is written to <params>. If the
final member of an active shader storage block is array with no declared
size, the minimum buffer size is computed assuming the array was declared
as an array with one element.
For the property of NUM_ACTIVE_VARIABLES, the number of active variables
associated with an active uniform block, shader storage block, or atomic
counter buffer is written to <params>.
For the property of ACTIVE_VARIABLES, an array of active variable indices
associated with an active uniform block, shader storage block, or atomic
counter buffer is written to <params>. The number of values written to
<params> for an active resource is given by the value of the property
NUM_ACTIVE_VARIABLES for the resource.
For the properties REFERENCED_BY_VERTEX_SHADER,
REFERENCED_BY_TESS_CONTROL_SHADER, REFERENCED_BY_TESS_EVALUATION_SHADER,
REFERENCED_BY_GEOMETRY_SHADER, REFERENCED_BY_FRAGMENT_SHADER, and
REFERENCED_BY_COMPUTE_SHADER, a single integer is written to <params>,
identifying whether the active resource is referenced by the vertex,
tessellation control, tessellation evaluation, geometry, or fragment
shaders, respectively, in the program object. The value one is written to
<params> if an active variable is referenced by the corresponding shader,
or if an active uniform block, shader storage block, or atomic counter
buffer contains at least one variable referenced by the corresponding
shader. Otherwise, the value zero is written to <params>.
For the property TOP_LEVEL_ARRAY_SIZE, a single integer identifying the
number of active array elements of the top-level shader storage block
member containing to the active variable is written to <params>. If the
top-level block member is not declared as an array, the value one is
written to <params>. If the top-level block member is an array with no
declared size, the value zero is written to <params>.
For the property TOP_LEVEL_ARRAY_STRIDE, a single integer identifying the
stride between array elements of the top-level shader storage block member
containing the active variable is written to <params>. For top-level
block members declared as arrays, the value written is the difference, in
basic machine units, between the offsets of the active variable for
consecutive elements in the top-level array. For top-level block members
not declared as an array, zero is written to <params>.
For the property LOCATION, a single integer identifying the assigned
location for an active uniform, input, output, or subroutine uniform
variable is written to <params>. For input, output, or uniform variables
with locations specified by a layout qualifier, the specified location is
used. For vertex shader input or fragment shader output variables without
a layout qualifier, the location assigned when a program is linked is
written to <params>. For all other input and output variables, the value
-1 is written to <params>. For uniforms in uniform blocks, the value -1
is written to <params>.
For the property LOCATION_INDEX, a single integer identifying the fragment
color index of an active fragment shader output variable is written to
<params>. If the active variable is an output for a non-fragment shader,
the value -1 will be written to <params>.
For the property IS_PER_PATCH, a single integer identifying whether the
input or output is a per-patch attribute. If the active variable is a
per-patch attribute (declared with the "patch" qualifier), the value one
is written to <params>; otherwise, the value zero is written to <params>.
The commands
int GetProgramResourceLocation(uint program, enum programInterface,
const char *name);
int GetProgramResourceLocationIndex(uint program, enum programInterface,
const char *name);
returns the location or the fragment color index, respectively, assigned
to the variable named <name> in interface <programInterface> of program
object <program>. For both commands, the error INVALID_OPERATION is
generated if <program> has not been linked or was last linked
unsuccessfully. For GetProgramResourceLocation, <programInterface> must
be one of UNIFORM, PROGRAM_INPUT, PROGRAM_OUTPUT,
VERTEX_SUBROUTINE_UNIFORM, TESS_CONTROL_SUBROUTINE_UNIFORM,
TESS_EVALUATION_SUBROUTINE_UNIFORM, GEOMETRY_SUBROUTINE_UNIFORM,
FRAGMENT_SUBROUTINE_UNIFORM, or COMPUTE_SUBROUTINE_UNIFORM. For
GetProgramResourceLocationIndex, <programInterface> must be
PROGRAM_OUTPUT. The value -1 will be returned by either command if an
error occurs, if <name> does not identify an active variable on
<programInterface>, or if <name> identifies an active variable that does
not have a valid location assigned, as described above. The locations
returned by these commands are the same locations returned when querying
the LOCATION and LOCATION_INDEX resource properties.
A string provided to GetProgramResourceLocation or
GetProgramResourceLocationIndex is considered to match an active variable
if:
* the string exactly matches the name of the active variable;
* if the string identifies the base name of an active array, where the
string would exactly match the name of the variable if the suffix
"[0]" were appended to the string; or
* if the string identifies an active element of the array, where the
string ends with the concatenation of the "[" character, an integer
(with no "+" sign, extra leading zeroes, or whitespace) identifying an
array element, and the "]" character, the integer is less than the
number of active elements of the array variable, and where the string
would exactly match the enumerated name of the array if the decimal
integer were replaced with zero.
Any other string is considered not to identify an active variable. If the
string specifies an element of an array variable,
GetProgramResourceLocation and GetProgramResourceLocationIndex return the
location or fragment color index assigned to that element. If it
specifies the base name of an array, it identifies the resources
associated with the first element of the array.
Modify Section 2.14.6, Vertex Attributes, p. 109
(delete text beginning with the second paragraph of p. 110, through the
second paragraph of p. 112)
(modify the third paragraph, p. 112, removing the first sentence) The
command
void BindAttribLocation(uint program, uint index, const char *name);
...
(insert after second paragraph, p. 113)
To determine the set of active vertex attribute variables used by a
program, applications can query the properties and active resources of the
PROGRAM_INPUT interface of a program including a vertex shader.
Additionally, the command
void GetActiveAttrib(uint program, uint index,
sizei bufSize, sizei *length, int *size,
enum *type, char *name);
can be used to determine properties of the active input variable assigned
the index <index> in program object <program>. If no error occurs, the
command is equivalent to calling:
const enum props[] = { ARRAY_SIZE, TYPE };
GetProgramResourceName(program, PROGRAM_INPUT, index, bufSize, length,
name);
GetProgramResourceiv(program, PROGRAM_INPUT, index, 1, &props[0],
1, NULL, size);
GetProgramResourceiv(program, PROGRAM_INPUT, index, 1, &props[1],
1, NULL, (int *) type);
If <index> is not the index of an active input variable in <program>, the
error INVALID_VALUE is generated. If <program> does not include a vertex
shader, it has no active vertex attributes and the error INVALID_VALUE is
generated for all values of <index>. For GetActiveAttrib, all active
vertex shader input variables are enumerated, including the special
built-in inputs gl_VertexID and gl_InstanceID.
The command
int GetAttribLocation(uint program, const char *name);
can be used to determine the location assigned to the active input
variable named <name> in program object <program>. The error
INVALID_OPERATION is generated and -1 is returned if <program> has not
been linked or was last linked unsuccessfully. If <program> has been
successfully linked but contains no vertex shader, no error will be
generated but -1 will be returned. Otherwise, the command is equivalent
to calling:
GetProgramResourceLocation(program, PROGRAM_INPUT, name);
There is an implementation-dependent limit on the number of active
attribute variables [[compatibility profile only: (either conventional or
generic)]] in a vertex shader. A program with more than
MAX_VERTEX_ATTRIBS active attribute variables may fail to link, unless
device-dependent optimizations are able to make the program fit within
available hardware resources. For the purposes of this test, attribute
variables of the type dvec3, dvec4, dmat2x3, dmat2x4, dmat3, dmat3x4,
dmat4x3, and dmat4 may count as consuming twice as many attributes as
equivalent single-precision types. While these types use the same number
of generic attributes as their single-precision equivalents,
implementations are permitted to consume two single-precision vectors of
internal storage for each three- or four-component double-precision
vector.
Modify Section 2.14.7, Uniform Variables, p. 113
(replace text starting with the 3rd paragraph on p. 115 through the 3rd
paragraph on p. 127)
To determine the set of active uniform variables used by a program,
applications can query the properties and active resources of the UNIFORM
interface of a program.
Additionally, several dedicated commands are provided to query properties
of active uniforms. The commands
int GetUniformLocation(uint program, const char *name)
void GetActiveUniformName(uint program, uint uniformIndex,
sizei bufSize, sizei *length,
char *uniformName);
are equivalent to calling
GetProgramResourceLocation(program, UNIFORM, name);
GetProgramResourceName(program, UNIFORM, uniformIndex, bufSize, length,
uniformName);
The command
void GetUniformIndices(uint program, sizei uniformCount,
const char * const *uniformNames,
uint *uniformIndices);
is equivalent to
for (int i = 0; i < uniformCount; i++) {
uniformIndices[i] =
GetProgramResourceIndex(program, UNIFORM, uniformNames[i];
}
The command
void GetActiveUniform(uint program, uint index, sizei bufSize,
sizei *length, int *size, enum *type,
char *name);
is equivalent to
const enum props[] = { ARRAY_SIZE, TYPE };
GetProgramResourceName(program, UNIFORM, index, bufSize, length, name);
GetProgramResourceiv(program, UNIFORM, index,
1, &props[0], 1, NULL, size);
GetProgramResourceiv(program, UNIFORM, index,
1, &props[1], 1, NULL, (int *) type);
The command
void GetActiveUniformsiv(uint program, sizei uniformCount,
const uint *uniformIndices, enum pname,
int *params);
is equivalent to
GLenum prop;
for (int i = 0; i < uniformCount; i++) {
GetProgramResourceiv(program, UNIFORM, uniformIndices[i], 1, &prop,
1, NULL, &params[i]);
}
where the value of <prop> is taken from Table X.2, based on the value of
<pname>.
<pname> <prop>
------------------------------ ------------------------------
UNIFORM_TYPE TYPE
UNIFORM_SIZE ARRAY_SIZE
UNIFORM_NAME_LENGTH NAME_LENGTH
UNIFORM_BLOCK_INDEX BLOCK_INDEX
UNIFORM_OFFSET OFFSET
UNIFORM_ARRAY_STRIDE ARRAY_STRIDE
UNIFORM_MATRIX_STRIDE MATRIX_STRIDE
UNIFORM_IS_ROW_MAJOR IS_ROW_MAJOR
UNIFORM_ATOMIC_COUNTER_ ATOMIC_COUNTER_BUFFER_INDEX
BUFFER_INDEX
Table X.2, GetProgramResourceiv properties used by
GetActiveUniformsiv.
To determine the set of active uniform blocks used by a program,
applications can query the properties and active resources of the
UNIFORM_BLOCK interface of a program.
Additionally, several dedicated commands are provided to query properties
of active uniform blocks. The commands
uint GetUniformBlockIndex(uint program, const char *uniformBlockName);
void GetActiveUniformBlockName(uint program, uint uniformBlockIndex,
sizei bufSize, sizei length,
char *uniformBlockName);
are equivalent to calling
GetProgramResourceIndex(program, UNIFORM_BLOCK, uniformBlockName);
and
GetProgramResourceName(program, UNIFORM_BLOCK, uniformBlockIndex,
bufSize, length, uniformBlockName);
The command
void GetActiveUniformBlockiv(uint program, uint uniformBlockIndex,
enum pname, int *params);
is equivalent to calling
GLenum prop;
GetProgramResourceiv(program, UNIFORM_BLOCK, uniformBlockIndex,
1, &prop, maxSize, NULL, params);
where the value of <prop> is taken from Table X.3, based on the value of
<pname>, and <maxSize> is taken to specify a sufficiently large buffer to
receive all values that would be written to <params>.
<pname> <prop>
------------------------------ ------------------------------
UNIFORM_BLOCK_BINDING BUFFER_BINDING
UNIFORM_BLOCK_DATA_SIZE BUFFER_DATA_SIZE
UNIFORM_BLOCK_NAME_LENGTH NAME_LENGTH
UNIFORM_BLOCK_ACTIVE_UNIFORMS NUM_ACTIVE_VARIABLES
UNIFORM_BLOCK_ACTIVE_ ACTIVE_VARIABLES
UNIFORM_INDICES
UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_VERTEX_SHADER
VERTEX_SHADER
UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_TESS_CONTROL_SHADER
TESS_CONTROL_SHADER
UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_TESS_EVALUATION_SHADER
TESS_EVALUATION_SHADER
UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_GEOMETRY_SHADER
GEOMETRY_SHADER
UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_FRAGMENT_SHADER
FRAGMENT_SHADER
UNIFORM_BLOCK_REFERENCED_BY_ REFERENCED_BY_COMPUTE_SHADER
COMPUTE_SHADER
Table X.3, GetProgramResourceiv properties used by
GetActiveUniformBlockiv.
To determine the set of active atomic counter buffer binding points used
by a program, applications can query the properties and active resources
of the ATOMIC_COUNTER_BUFFER interface of a program.
Additionally, the command
void GetActiveAtomicCounterBufferiv(uint program, uint bufferIndex,
enum pname, int *params);
can be used to determine properties of active atomic counter buffer
bindings used by <program> and is equivalent to calling
GLenum prop;
GetProgramResourceiv(program, ATOMIC_COUNTER_BUFFER, bufferIndex,
1, &prop, maxSize, NULL, params);
where the value of <prop> is taken from Table X.4, based on the value of
<pname>, and <maxSize> is taken to specify a sufficiently large buffer to
receive all values that would be written to <params>.
<pname> <prop>
------------------------------ ------------------------------
ATOMIC_COUNTER_BUFFER_BINDING BUFFER_BINDING
ATOMIC_COUNTER_BUFFER_ BUFFER_DATA_SIZE
DATA_SIZE
ATOMIC_COUNTER_BUFFER_ACTIVE_ NUM_ACTIVE_VARIABLES
ATOMIC_COUNTERS
ATOMIC_COUNTER_BUFFER_ACTIVE_ ACTIVE_VARIABLES
ATOMIC_COUNTER_INDICES
ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_VERTEX_SHADER
REFERENCED_BY_VERTEX_SHADER
ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_TESS_CONTROL_SHADER
REFERENCED_BY_TESS_
CONTROL_SHADER
ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_TESS_EVALUATION_SHADER
REFERENCED_BY_TESS_
EVALUATION_SHADER
ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_GEOMETRY_SHADER
REFERENCED_BY_GEOMETRY_SHADER
ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_FRAGMENT_SHADER
REFERENCED_BY_FRAGMENT_SHADER
ATOMIC_COUNTER_BUFFER_ REFERENCED_BY_COMPUTE_SHADER
REFERENCED_BY_COMPUTE_SHADER
Table X.4, GetProgramResourceiv properties used by
GetActiveAtomicCounterBufferiv.
Modify Section 2.14.8, Subroutine Uniform Variables, p. 136
(This section could probably use some reorganization and a high-level
introduction to how subroutines and subroutine variables work. As
written now, it mostly talks about the GL APIs operating on these without
a lot of conceptual discussion. These edits makes this section smaller
by redefining the old APIs in terms of the new ones.)
(replace language in the section describing the active subroutine and
subroutine uniform enumeration with the following)
To determine the set of active subroutines and subroutines used by a
particular shader stage of a program, applications can query the
properties and active resources of the interfaces for the shader type, as
listed in Tables X.5 and X.6.
Interface Shader Type
------------------------------ ------------------------------
VERTEX_SUBROUTINE VERTEX_SHADER
TESS_CONTROL_SUBROUTINE TESS_CONTROL_SHADER
TESS_EVALUATION_SUBROUTINE TESS_EVALUATION_SHADER
GEOMETRY_SUBROUTINE GEOMETRY_SHADER
FRAGMENT_SUBROUTINE FRAGMENT_SHADER
COMPUTE_SUBROUTINE COMPUTE_SHADER
Table X.5, Interfaces for active subroutines for a particular shader
type in a program.
Interface Shader Type
------------------------------ ------------------------------
VERTEX_SUBROUTINE_UNIFORM VERTEX_SHADER
TESS_CONTROL_SUBROUTINE_ TESS_CONTROL_SHADER
UNIFORM
TESS_EVALUATION_SUBROUTINE TESS_EVALUATION_SHADER
UNIFORM
GEOMETRY_SUBROUTINE_UNIFORM GEOMETRY_SHADER
FRAGMENT_SUBROUTINE_UNIFORM FRAGMENT_SHADER
COMPUTE_SUBROUTINE_UNIFORM COMPUTE_SHADER
Table X.6, Interfaces for active subroutine uniforms for a particular
shader type in a program.
Dedicated commands are provided to determine properties of active
subroutines and active subroutine uniforms. The commands
uint GetSubroutineIndex(uint program, enum shadertype,
const char *name);
void GetActiveSubroutineName(uint program, enum shadertype, uint index,
sizei bufsize, sizei *length, char *name);
are equivalent to
GetProgramResourceIndex(program, programInterface, name);
GetProgramResourceName(program, programInterface, index, bufsize,
length, name);
where <programInterface> is taken from Table X.5 according to the value of
<shadertype>.
The commands
void GetSubroutineUniformLocation(uint program, enum shadertype,
const char *name);
void GetActiveSubroutineUniformName(uint program, enum shadertype,
uint index, sizei bufsize,
sizei *length, char *name);
void GetActiveSubroutineUniformiv(uint program, enum shadertype,
uint index, enum pname, int *values);
are equivalent to
GetProgramResourceLocation(program, programInterface, name);
GetProgramResourceName(program, programInterface, index, bufsize, length,
name);
GetProgramResourceiv(program, programInterface, index, 1, &pname,
maxSize, NULL, values);
where <programInterface> is taken from Table X.6 according to the value of
<shadertype>. For GetActiveSubroutineUniformiv, <pname> must be one of
NUM_COMPATIBLE_SUBROUTINES or COMPATIBLE_SUBROUTINES, and <maxSize> is
taken to specify a sufficiently large buffer to receive all values that
would be written to <params>.
Modify Section 2.14.11, Output Variables, p. 140
(replace last paragraph, p. 143 through next-to-last paragraph, p. 144
with the following)
To determine the set of output variables in a linked program object that
will be captured in transform feedback mode, applications can query the
properties and active resources of the TRANSFORM_FEEDBACK_VARYING
interface.
Additionally, the dedicated command
void GetTransformFeedbackVarying(uint program, uint index,
sizei bufSize, sizei *length,
sizei *size, enum *type, char *name);
can be used to enumerate properties of a single output variable captured
in transform feedback mode, and is equivalent to
const enum props[] = { ARRAY_SIZE, TYPE };
GetProgramResourceName(program, TRANSFORM_FEEDBACK_VARYING, index,
bufSize, length, name);
GetProgramResourceiv(program, TRANSFORM_FEEDBACK_VARYING, index,
1, &props[0], 1, NULL, size);
GetProgramResourceiv(program, TRANSFORM_FEEDBACK_VARYING, index,
1, &props[1], 1, NULL, (int *) type);
GetTransformFeedbackVarying may be used to query any transform
feedback varying variable, not just those specified with
TransformFeedbackVarying.
Additions to Chapter 3 of the OpenGL 4.2 (Compatibility Profile) Specification
(Rasterization)
Modify Section 3.13.2, Shader Execution, p. 371
(replace next-to-last paragraph, p. 378 through the first paragraph,
p. 379 with the following)
To determine the set of fragment shader output attribute variables used by
a program, applications can query the properties and active resources of
the PROGRAM_OUTPUT interface of a program including a fragment shader.
Additionally, dedicated commands are provided to query the location and
fragment color index assigned to a fragment shader output variable. For
the commands
int GetFragDataLocation(uint program, const char *name);
int GetFragDataIndex(uint program, const char *name);
the error INVALID_OPERATION is generated and -1 is returned if <program>
has not been linked or was last linked unsuccessfully. If <program> has
been successfully linked but contains no fragment shader, no error will be
generated but -1 will be returned. Otherwise, the commands are equivalent
to calling:
GetProgramResourceLocation(program, PROGRAM_OUTPUT, name);
or
GetProgramResourceLocationIndex(program, PROGRAM_OUTPUT, name);
Additions to Chapter 4 of the OpenGL 4.2 (Compatibility Profile) Specification
(Per-Fragment Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 4.2 (Compatibility Profile) Specification
(Special Functions)
None. Note that all the commands added here are not included in display
lists, but no specification edits are required since existing blanket
language covers all Get* commands.
Additions to Chapter 6 of the OpenGL 4.2 (Compatibility Profile) Specification
(State and State Requests)
None.
Additions to Appendix A of the OpenGL 4.2 (Compatibility Profile)
Specification (Invariance)
None.
Additions to Appendix D of the OpenGL 4.2 (Compatibility Profile)
Specification (Shared Objects and Multiple Contexts)
None.
Additions to the AGL/EGL/GLX/WGL Specifications
None
GLX Protocol
TBD
Dependencies on OpenGL 3.0, ARB_transform_feedback, and EXT_transform_feedback
If OpenGL 3.0, ARB_transform_feedback, and EXT_transform_feedback are not
supported, references to the TRANSFORM_FEEDBACK_VARYING interface should
be removed.
Dependencies on OpenGL 3.1 and ARB_uniform_buffer_object
If OpenGL 3.1 and ARB_uniform_buffer_object are not supported, references
to the UNIFORM_BLOCK interface should be removed.
Dependencies on OpenGL 4.0 and ARB_shader_subroutine
If OpenGL 4.0 and ARB_shader_subroutine are not supported, references to
the VERTEX_SUBROUTINE, TESS_CONTROL_SUBROUTINE,
TESS_EVALUATION_SUBROUTINE, GEOMETRY_SUBROUTINE, FRAGMENT_SUBROUTINE,
COMPUTE_SUBROUTINE, VERTEX_SUBROUTINE_UNIFORM,
TESS_CONTROL_SUBROUTINE_UNIFORM, TESS_EVALUATION_SUBROUTINE_UNIFORM,
GEOMETRY_SUBROUTINE_UNIFORM, FRAGMENT_SUBROUTINE_UNIFORM, and
COMPUTE_SUBROUTINE_UNIFORM interfaces should be removed.
Dependencies on OpenGL 4.2 and ARB_shader_atomic_counters
If OpenGL 4.2 and ARB_shader_atomic_counters are not supported, references
to the ATOMIC_COUNTER_BUFFER interfaces should be removed.
Dependencies on OpenGL 4.3 and ARB_shader_storage_buffer_object
If OpenGL 4.3 and ARB_shader_storage_buffer_object are not supported,
references to the BUFFER_VARIABLE and SHADER_STORAGE_BLOCK interfaces
should be removed.
Dependencies on OpenGL 4.3 and ARB_arrays_of_arrays
If OpenGL 4.3 and ARB_arrays_of_arrays are not supported, language
describing the enumeration of multi-dimensional arrays (i.e., arrays of
arrays) should be removed.
Dependencies on OpenGL 4.3 and ARB_compute_shader
If OpenGL 4.3 and ARB_compute_shader are not supported, references to the
COMPUTE_SUBROUTINE and COMPUTE_SUBROUTINE_UNIFORM interfaces should be
removed.
Dependencies on OpenGL 4.3 and ARB_explicit_uniform_location
If OpenGL 4.3 and ARB_explicit_uniform_location are not supported,
references to uniform variables being declared with a layout qualifier
should be removed.
Errors
An INVALID_VALUE error is generated by GetProgramInterfaceiv,
GetProgramResourceIndex, GetProgramResourceName, GetProgramResourceiv,
GetProgramResourceLocation, and GetProgramResourceLocationIndex if
<program> is not the name of either a shader or program object.
An INVALID_OPERATION error is generated by GetProgramInterfaceiv,
GetProgramResourceIndex, GetProgramResourceName, GetProgramResourceiv,
GetProgramResourceLocation, and GetProgramResourceLocationIndex if
<program> is the name of a shader object.
INVALID_OPERATION is generated by GetProgramInterfaceiv if the parameter
<pname> is not supported for the interface <programInterface>.
INVALID_ENUM is generated by GetProgramResourceIndex if <programInterface>
is ATOMIC_COUNTER_BUFFER.
INVALID_VALUE is generated by GetProgramResourceName if <index> is greater
than or equal to the number of entries in the active resource list for
<programInterface>.
INVALID_ENUM is generated by GetProgramResourceName if <programInterface>
is ATOMIC_COUNTER_BUFFER.
INVALID_VALUE is generated by GetProgramResourceiv if <propCount> is zero.
INVALID_ENUM is generated by GetProgramResourceiv if any value in <props>
is not a property name supported by the command.
INVALID_OPERATION is generated by GetProgramResourceiv if any value in
<props> is not supported for the interface <programInterface>.
INVALID_OPERATION is generated by GetProgramResourceLocation and
GetProgramResourceLocationIndex if <program> has not been linked or was
last linked unsuccessfully.
New State
Insert new tables after Table 6.53, Program Object State (cont.), p. 557:
Add table, labeled "Program Interface State"
Initial
Get Value Type Get Command Value Description Sec.
----------------------- ---- ----------- ------- ------------------------ -----
ACTIVE_RESOURCES nxZ+ GetProgramInterfaceiv 0 number of active resources 2.14.3
on an interface
MAX_NAME_LENGTH nxZ+ GetProgramInterfaceiv 0 maximum name length for 2.14.3
active resources
MAX_NUM_ACTIVE_VARIABLES nxZ+ GetProgramInterfaceiv 0 maximum number of active 2.14.3
variables for active
resources
MAX_NUM_COMPATIBLE_SUBROUTINES nxZ+ GetProgramInterfaceiv 0 maximum number of compat- 2.14.3
ible subroutines for
subroutine uniforms
Add table, labeled "Program Object Resource State"
Initial
Get Value Type Get Command Value Description Sec.
----------------------- ---- ----------- ------- ------------------------ -----
NAME_LENGTH Z+ GetProgram- - length of active resource 2.14.3
Resourceiv name
TYPE Z+ GetProgram- - active resource data type 2.14.3
Resourceiv
ARRAY_SIZE Z+ GetProgram- - active resource array size 2.14.3
Resourceiv
OFFSET Z+ GetProgram- - active resource offset in 2.14.3
Resourceiv memory
BLOCK_INDEX Z+ GetProgram- - index of interface block 2.14.3
Resourceiv owning resource
ARRAY_STRIDE Z+ GetProgram- - active resource array 2.14.3
Resourceiv stride in memory
MATRIX_STRIDE Z+ GetProgram- - active resource matrix 2.14.3
Resourceiv stride in memory
IS_ROW_MAJOR Z+ GetProgram- - active resource stored as 2.14.3
Resourceiv a row major matrix?
ATOMIC_COUNTER_BUFFER_INDEX Z+ GetProgram- - index of atomic counter 2.14.3
Resourceiv buffer owning resource
BUFFER_BINDING Z+ GetProgram- - buffer binding assigned 2.14.3
Resourceiv to active resource
BUFFER_DATA_SIZE Z+ GetProgram- - minimum buffer data size 2.14.3
Resourceiv required for resource
NUM_ACTIVE_VARIABLES Z+ GetProgram- - number of active variables 2.14.3
Resourceiv owned by active resource
ACTIVE_VARIABLES Z+ GetProgram- - list of active variables 2.14.3
Resourceiv owned by active resource
REFERENCED_BY_VERTEX_SHADER Z+ GetProgram- - active resource used by 2.14.3
Resourceiv vertex shader?
REFERENCED_BY_TESS_CONTROL_ Z+ GetProgram- - active resource used by 2.14.3
SHADER Resourceiv tess. control shader?
REFERENCED_BY_TESS_EVALUATION_ Z+ GetProgram- - active resource used by 2.14.3
SHADER Resourceiv tess evaluation shader?
REFERENCED_BY_GEOMETRY_SHADER Z+ GetProgram- - active resource used by 2.14.3
Resourceiv geometry shader?
REFERENCED_BY_FRAGMENT_SHADER Z+ GetProgram- - active resource used by 2.14.3
Resourceiv fragment shader?
REFERENCED_BY_COMPUTE_SHADER Z+ GetProgram- - active resource used by 2.14.3
Resourceiv compute shader?
TOP_LEVEL_ARRAY_SIZE Z+ GetProgram- - array size of top level 2.14.3
Resourceiv shd. storage block member
TOP_LEVEL_ARRAY_STRIDE Z+ GetProgram- - array stride of top level 2.14.3
Resourceiv shd. storage block member
LOCATION Z+ GetProgram- - location assigned to 2.14.3
Resourceiv active resource
LOCATION_INDEX Z+ GetProgram- - location index assigned 2.14.3
Resourceiv to active resource
IS_PER_PATCH Z+ GetProgram- - is active input/output 2.14.3
Resourceiv a per-patch attribute?
NUM_COMPATIBLE_SUBROUTINES Z+ GetProgram- - number of compatible 2.14.3
Resourceiv subroutines for active
subroutine uniform
COMPATIBLE_SUBROUTINES Z+ GetProgram- - list of compatible 2.14.3
Resourceiv subroutines for active
subroutine uniform
New Implementation Dependent State
None.
Sample Code
!!! TBD !!!
Conformance Tests
!!! TBD !!!
Issues
(1) Does the list of active resources in a program include built-ins where
applicable?
RESOLVED: Yes; built-ins should be enumerated when present.
(2) Should this extension fully support all program interfaces and
resources, even those that have limited or no query capabilities
today? In particular, there is very little enumeration support for
fragment outputs and transform feedback varyings. OpenGL 4.1 added
ARB_separate_shader_objects that allowed two independent programs to
form an interface, but provided no mechanism for querying the active
variables on either side of that interface.
RESOLVED: Let's support as much as we can with a single set of
functions.
(3) How should we support enumeration of variables and interface blocks
provided by the ARB_shader_storage_buffer_object extension?
RESOLVED: The enumeration mechanisms provided by this extension will be
the only way to enumerate buffer variables and shader storage blocks.
ARB_shader_storage_buffer_object will require this extension.
(4) The commands provided this extension are intended to supersede
existing enumeration APIs (e.g., GetActiveUniform, GetActiveAttrib).
The old APIs can eventually be deprecated. Both new and old APIs
generate a list of active resources and assign indices to each entry
in the list. Should assigned indices match between the new and old
APIs?
RESOLVED: Yes. While there is no strong reason why the new APIs
couldn't adopt new enumeration rules for existing resource types, it's
easier to enumerate the same way that we've done for the older API
calls, for several reasons:
* Minimizes changes for existing applications using the old
enumeration APIs or for applications needing to support both the new
and old APIs. All they need to do is map their existing API usage
to the new APIs without having to reconsider whether any other
assumption of their old logic is still valid.
* Minimizes complexity for implementations needing to support both new
and old APIs, at least until the old APIs are deprecated/removed.
* Makes it easier to redefine the existing functions in terms of the
new ones.
(5) Existing enumeration APIs handle entities like arrays of structures by
unrolling them. For example, a uniform array of structures with 8
elements and 3 structure members will result in 24 entries enumerated
by GetActiveUniform. Should we re-work the API to enumerate fewer
entries?
RESOLVED: For existing resources, no, for the reasons discussed above.
The main problem with that approach is if a shader uses a uniform block
with a large array of structures. For newer resource types, we can and
will adopt new rules.
(6) How should enumeration rules work for complex arrays/structures in
shader storage blocks (ARB_shader_storage_buffer_object)?
RESOLVED: One of the intended use cases is to allow for shader storage
blocks consisting of little more than a large (or unsized) array of
structures. For example, we might have shader code like:
struct VertexInfo {
float position[3];
float normal[3];
};
buffer VertexCollection {
VertexInfo v[10000];
};
If existing uniform enumeration API rules were applied, this would
enumerate 20000 separate active resources (10000 array elements with two
members each). That seems crazy. This specification optimizes for this
case by flattening arrays at the top of the block. For that shader, we
would enumerate only the first element of each array ("v[0].position[0]"
and "v[0].normal[0]"). The properties TOP_LEVEL_ARRAY_SIZE and
TOP_LEVEL_ARRAY_STRIDE allow applications to determine the size (if
declared) and stride in buffer object memory.
For more complex hierarchies, we chose to continue unrolling arrays in
the middle of the hierarchy to avoid the need to specify a more complex
API. For example, in this code
struct VertexInfo {
float position[3];
float normal[3];
};
struct TriangleInfo {
VertexInfo v[3];
};
buffer VertexCollection {
TriangleInfo t[10000];
};
we would unroll "TriangleInfo" and enumerate six resources:
t[0].v[0].position[0]
t[0].v[0].normal[0]
t[0].v[1].position[0]
t[0].v[1].normal[0]
t[0].v[2].position[0]
t[0].v[2].normal[0]
Flattening "v[]" to a single entry would require either some sort of
recursive enumeration (e.g., enumerate "t" as a structure and provide
"pointers" to a collection of members), or some sort of new property
that returns a variable-length array of strides.
(7) The ARB_array_of_arrays extension allows shaders to declare
multi-dimensional arrays that could be enumerated by this API? How
should arrays of arrays be enumerated?
RESOLVED: We define rules consistent with our enumeration rules for
other complex types. For existing one-dimensional arrays, we enumerate
a single entry if the array is an array of basic types, or separate
entries for each array element if the array is an array of structures.
We follow similar rules here. For a uniform array such as:
uniform vec4 a[5][4][3];
we enumerate twenty different entries ("a[0][0][0]" through
"a[4][3][0]"), each of which is treated as an array with three elements.
This is morally equivalent to what you'd get if you worked around the
limitation in current GLSL via:
struct ArrayBottom { vec4 c[3]; };
struct ArrayMid { ArrayBottom b[3]; };
uniform ArrayMid a[5];
which would enumerate "a[0].b[0].c[0]" through "a[4].b[3].c[0]".
We also apply the top-level array flattening for shader storage block
members. For example:
buffer Block {
vec4 a[5][4][3];
};
would enumerate only four entries -- "a[0][0][0]" through "a[0][3][0]",
where each enumerated entry corresponds to an array of size 3, has a
top-level size of 5, and has a top-level stride appropriate for its
layout in memory.
(8) For GetProgramResourceIndex, what sort of strings can be used to match
the resource names for arrays of arrays? For example, let's say a
shader declares a uniform such as:
uniform vec4 a[3][4][5];
Which one of the following names are accepted? "a[2][1][0]" to
identify the base of the bottom-level array? "a[2][1]", to identify
the same without the final "[0]"? "a[2]", equivalent to "a[2][0][0]"?
Just "a", equivalent to "a[0][0][0]"?
RESOLVED: We only accept entries of the form "a[2][1][0]" or
"a[2][1]", which is consistent with the existing rules that only allow
applications to omit the last index of a bottom-level array that has
been rolled up.
(9) Should be consolidate the commands GetAttribLocation,
GetUniformLocation, GetSubroutineUniformLocation, GetFragDataLocation
(and GetFragDataIndex) into a single generic API?
RESOLVED: Yes. This spec provides GetProgramResourceLocation and
GetProgramResourceLocationIndex commands to consolidate the existing
set of commands. Additionally, GetProgramResourceiv can be used to
query locations via the LOCATION and LOCATION_INDEX properties.
There are a number of irregularities in the assignment of locations as
compared to other uniform types:
* Atomic counter uniforms, uniforms in blocks are not assigned
locations.
* Built in inputs and outputs are not assigned locations.
* The locations of inputs other than vertex shader inputs and
fragment shader outputs don't interact with any other GL state;
they are used only for interfacing with other programs. For such
variables, we choose the return the specified location number if a
variable is declared with a layout qualifier, and -1 (no valid
location) otherwise. Variables declared without location layout
qualifiers will be assigned an internal location by the
compiler/linker, but those locations do not necessarily correspond
to the canonical integer locations supported in layout qualifiers.
* For fragment shader outputs, not only do we have a location, but
we also have an associated index that can be queried with
GetFragDataIndex.
(10) What should we do about tokens like ACTIVE_UNIFORMS and
ACTIVE_UNIFORM_MAX_LENGTH that are specific to an interface, but are
queried today by GetProgramiv?
RESOLVED: We provide a new GetProgramInterfaceiv query to return
properties of an interface. The value returned today by ACTIVE_UNIFORMS
can be determined by calling GetProgramInterfaceiv with a
<programInterface> of UNIFORM and a <pname> of ACTIVE_RESOURCES.
ACTIVE_RESOURCES can also be used for other interfaces to get values
returned today with other query tokens (e.g., ACTIVE_ATTRIBUTES).
(11) What sort of interface should we use for querying properties of
active resources? We have two different styles of query today.
Functions like GetActiveUniform() allow applications to query
multiple (fixed) properties of a single active uniform. Functions
like GetActiveUniforms() allow applications to query a single
property of multiple active uniforms?
RESOLVED: GetProgramResourceiv allows applications to query multiple
properties of a single resource in a single call; applications pass in
an array of properties to query.
We considered providing a command GetProgramResourcesiv that would have
allowed an application to query multiple properties of multiple
resources in a single call, by passing in an array of resource indices.
We decided not to include this for simplicity. Also note that the most
common use case we envisioned would be to query all properties of all
active resources, with code like the following:
struct VariableInfo {
GLenum type;
GLint location;
};
GLenum inputProps[] = { GL_TYPE, GL_LOCATION };
GLuint nInputProps = sizeof(inputProps) / sizeof(GLenum);
GLint nActive;
glGetProgramInterface(program, GL_PROGRAM_INPUT, GL_ACTIVE_RESOURCES,
&nActive);
VariableInfo *varInfo = malloc(nActive*sizeof(VariableInfo));
GLuint *indices = malloc(nActive*sizeof(GLuint));
for (GLuint i = 0; i < nActive; i++) { indices[i] = i; }
glGetProgramResourcesiv(program, GL_PROGRAM_INPUT,
nActive, indices, nInputProps, inputProps,
nActive*nInputProps, NULL, (GLint*)varInfo);
Such an API would require applications to fill in a dummy array of
indices to express "all indices". With the simplified API, more GL
calls are required, but the code is overall simpler:
glGetProgramInterface(program, GL_PROGRAM_INPUT, GL_ACTIVE_RESOURCES,
&nActive);
VariableInfo *varInfo = malloc(nActive*sizeof(VariableInfo));
for (GLuint i = 0; i < nActive; i++) {
glGetProgramResourceiv(program, GL_PROGRAM_INPUT, i,
nInputProps, inputProps,
nActive*nInputProps, NULL,
(GLint*) (&varInfo[i]));
}
(12) For GetProgramResourceiv, how should we handle queries of properties
that return a variable number of values (e.g.,
COMPATIBLE_SUBROUTINES)? Should we support these queries in the
general "multiple properties of multiple resources" query, or provide
a separate "single property of single resource query"? Should we
just write out a variable number of values to <params>? If we allow
for a variable number of values to be written to <params>, should we
provide some sort of <bufSize> parameter to guard against overflows?
RESOLVED: We will support these properties in the general "multiple
properties of a single resource" query and write out the variable number
of values to consecutive locations in the array. If an application
wants to query such properties for multiple resources at once, it can
parse the values returned by the GL. If NUM_COMPATIBLE_SUBROUTINES is
immediately before COMPATIBLE_SUBROUTINES in the property list, the
number of compatible subroutines written to the buffer (N) will be found
immediately immediately prior to the N compatible subroutine numbers.
We will provide a <bufSize> parameter to guard against overflow.
Applications can ensure they have an adequately-sized buffer by calling
GetProgramInterfaceiv with a <pname> of MAX_NUM_COMPATIBLE_SUBROUTINES
to determine the maximum number of subroutines that will be written to
any one buffer.
It's not clear how valuable the variable-length enumeration queries
actually are. Unextended OpenGL 4.2 has two such queries today:
COMPATIBLE_SUBROUTINES and UNIFORM_BLOCK_ACTIVE_UNIFORMS.
UNIFORM_BLOCK_ACTIVE_UNIFORMS isn't strictly needed; an application can
determine this list themselves by querying the UNIFORM_BLOCK_INDEX
property of each active uniform. We could do something similar for
compatible subroutines.
(13) Should we add a mechanism for enumerating subroutine types supported
by a program and querying the subroutine type for subroutines and
subroutine uniforms?
RESOLVED: No. Such a mechanism could have been used to reduce the need
for variable-length return values for GetProgramResourcesiv in some
cases. Instead of supporting COMPATIBLE_SUBROUTINES (list all
subroutines compatible with a uniform type), we could have allowed
applications to query the subroutine type for both subroutines and
subroutine uniforms and match them in application code. The problem
with that approach is that subroutines can have multiple associated
subroutine types, so a variable-length return value would still be
needed to query subroutine types.
(14) Should we support "REFERENCED_BY_*" for uniforms and buffer
variables?
RESOLVED: Yes. It isn't supported in unextended OpenGL 4.2, but the
functionality seems to make sense.
(15) Since this extension is being developed at the same time as compute
shaders, should we add compute shader-specific enums for the old
queries that would be superseded by the the queries added here? Or
should we rely solely on the new queries? For example, should we add
a new token "UNIFORM_BLOCK_REFERENCED_BY_COMPUTE_SHADER"?
RESOLVED: Yes, we will add old-style enums for the compute shader stage
for all previously existing APIs.
(16) How are inputs and outputs in the built-in interface block
"gl_PerVertex" enumerated?
RESOLVED: We will follow the default rule for enumerating block members
in the OpenGL API, which is:
* If a variable is a member of an interface block without an instance
name, it is enumerated using just the variable name.
* If a variable is a member of an interface block with an instance
name, it is enumerated as "BlockName.Member", where "BlockName" is
the name of the interface block (not the instance name) and "Member"
is the name of the variable.
For example, in the following code:
uniform Block1 {
int member1;
};
uniform Block2 {
int member2;
} instance2;
uniform Block3 {
int member3;
} instance3[2]; // uses two separate buffer bindings
the three uniforms (if active) are enumerated as "member1",
"Block2.member2", and "Block3.member3".
For tessellation control, tessellation evaluation, and geometry shaders,
per-vertex built-in inputs like gl_Position are in a block with an
instance name of "gl_in[]". Additionally, for tessellation control
shaders, per-vertex built-in outputs like gl_Position are in a block
with an instance name of "gl_out[]". In these cases, applying the
standard rules would result in an enumerated name of
"gl_PerVertex.gl_Position".
(17) Should we add support for enumerating per-patch shader
inputs/outputs? If so, how to distinguish between per-vertex and
per-patch?
RESOLVED: Yes. When program inputs or outputs include per-patch
attributes, those variables will be enumerated along with per-vertex
attributes. To determine if an input or output is per-patch, use the
resource property IS_PER_PATCH.
(18) Do we enumerate the special "marker" variables for transform feedback
varyings (gl_NextBuffer, gl_SkipComponents[1234])? If so, what are
their properties?
RESOLVED: Yes, we should definitely enumerate them so applications can
determine programmatically what would be written to transform feedback
buffers. This capability is already supported by the existing
GetTransformFeedback query. We follow the existing behavior -- all of
these entries are enumerated with a type of NONE. gl_NextBuffer returns
an array size of 0; gl_SkipComponents[1234] returns an array size equal
to the specified number of components.
(19) Should we support a <bufsize> arguments to prevent buffer overflows
on the GetProgramInterfaceiv query?
RESOLVED: Yes, to provide a "safe" mechanism since the query might
return an unpredictable and program-dependent amount of data. We also
provide a <length> parameter that can be used to return the number of
words written by the query to be consistent with other similar APIs.
(20) Are "old" token names (e.g., UNIFORM_TYPE) accepted by "new"
commmands (GetProgramResourceiv)? Are "new" token names (TYPE)
accepted by "old" commands (GetActiveUniforms)?
RESOLVED: No. New queries support only the new enums; old queries
support only the old ones.
(21) While programs may include shader code for multiple stages, shader
subroutines and subroutine uniforms are specific to a single stage in
the program. This means that there is a separate interface for each
program stage. Should we specify <programInterface> tokens for a
cross-product of interfaces and stages (e.g., VERTEX_SUBROUTINE,
FRAGMENT_SUBROUTINE_UNIFORM)? Or should we provide generic
<programInterface> tokens (SUBROUTINE, SUBROUTINE_UNIFORM) and accept
a second <stage> parameter?
RESOLVED: Use concatenated tokens to avoid creating adding a separate
set of per-stage APIs. With this solution, we have means 12
concatenated tokens (6 stages crossed with SUBROUTINE and
SUBROUTINE_UNIFORM); we don't expect a massive number of new tokens in
the future.
(22) What data type should be used for the <params> (return data) argument
to GetProgramResourceiv()?
RESOLVED: Use an "int *" to be consistent with all the other
"*iv"-style queries.
We considered using a "void *" so applications could avoid manual casts
for cases where the API would be used to fill a structure with
properties of a resource, as in code like the following:
struct VariableInfo {
GLenum type;
GLint location;
} varInfo;
GLenum inputProps[] = { GL_TYPE, GL_LOCATION };
GLuint nInputProps = sizeof(inputProps) / sizeof(GLenum);
...
glGetProgramResourceiv(program, GL_PROGRAM_INPUT, index,
nInputProps, inputProps, nInputProps, NULL,
(GLint*)varInfo);
(23) The special "marker" names "gl_NextBuffer" and "gl_SkipComponents*"
may appear multiple times in the array of strings passed to
TransformFeedbackVaryings. How is this condition handled in the new
enumeration APIs?
RESOLVED: For the purposes of enumerating active resources in the
TRANSFORM_FEEDBACK_VARYINGS interface, each instance of the marker is
assigned its own index, and the name and properties associated with that
index can be queried. [See also issue (18).] This is consistent with
how GetTransformFeedbackVaryings works in unextended OpenGL 4.2.
The problem is that since a marker name can have multiple associated
indices, it's not clear what value should be returned when passing such
a string to GetProgramResourceIndex(). We specify that passing any of
these marker strings should return the value INVALID_INDEX, regardless
of the number of times the marker appears in the inputs to
TransformFeedbackVaryings. Unextended OpenGL 4.2 does not provide the
ability to query the index associated with an active transform feedback
varying name, so this is a new issue in this extension.
(24) The PROGRAM_INPUT and PROGRAM_OUTPUT interfaces are provided to allow
applications to query active inputs and outputs in a program. Do we
enumerate all variables qualified with "in" and "out", or should
special "system" built-ins such as gl_VertexID, gl_InstanceID, and
gl_FrontFacing be excluded?
RESOLVED: We enumerate all active variables qualified with "in" or
"out" in the PROGRAM_INPUT and PROGRAM_OUTPUT interfaces, including
special variables. Additionally, because we redefine the function
glGetActiveAttrib in terms of this in terms of the PROGRAM_INPUT
interface, we should enumerate the specials gl_VertexID and
gl_InstanceID there as well. Previously, there was no explicit spec
language whether these variables should be enumerated by
GetActiveAttrib, and various OpenGL implementations behaved differently.
This approach allows applications to enumerate all inputs used by a
vertex shader, whether or not they correspond to attributes in
conventional or generic vertex attribute arrays.
(25) What should the value of ARRAY_SIZE be for non-array and unsized
array variables?
RESOLVED: For compatibility with GetActiveUniform, ARRAY_SIZE of a
non-array variable is one (initially this was specified as zero, an
unintentional incompatibility). For unsized array variables, the size
is zero.
Revision History
Revision 20, August 19, 2013 (Jon Leech)
- Change ARRAY_SIZE query to return one for active variables not
corresponding to an array of basic types, rather than zero, for
compatibility with GetActiveUniform (Bug 10647). Return zero for
explicitly unsized arrays (Bug 10641). Add extra 'const' qualifier
for GetUniformIndices <uniformNames> argument (Bug 10703).
Revision 19, July 11, 2013 (Jon Leech)
- Clarify that GetTransformFeedbackVarying can be used to query
any transform feedback varying variable (Bug 10472).
Revision 18, July 10, 2012 (pbrown)
- Specify an INVALID_ENUM error when ATOMIC_COUNTER_BUFFER is passed
to GetProgramResourceIndex or GetProgramResourceName. Clarify that
the array element portion of a string passed to
GetProgramResourceLocation or GetProgramResourceLocationIndex
must not have, a "+" sign, extra leading zeroes, or whitespace (bug
9254).
Revision 17, July 7, 2012 (pbrown)
- Specify that "special" built-ins inputs and outputs such as
"gl_VertexID" should be enumerated in the PROGRAM_INPUT and
PROGRAM_OUTPUT interfaces, as well as the legacy function
GetActiveAttrib. Add spec language counting the built-ins gl_VertexID
and gl_InstanceID against the active attribute limit (bug 9201).
Revision 16, July 2, 2012 (pbrown)
- Fix typos in the language mapping OpenGL 4.2 active subroutine and
subroutine uniform enumeration functions to the new interfaces.
Revision 15, June 21, 2012 (Jon Leech)
- Update errors to match the generic errors for all commands taking
<program> names (INVALID_VALUE if neither a shader nor program
object name, and INVALID_OPERATION if a shader object name) (Bug
9145).
Revision 14, June 14, 2012 (Jon Leech)
- Add INVALID_VALUE error if <program> is not the name of a valid
program object (Bug 9145).
Revision 13, May 31, 2012 (pbrown)
- Specify that passing the special "marker" strings "gl_NextBuffer"
and "gl_SkipComponents*" to GetProgramResourceIndex() will always
return INVALID_INDEX (bug 9071).
Revision 12, May 31, 2012 (pbrown)
- Allow the BUFFER_VARIABLE, PROGRAM_INPUT, and PROGRAM_OUTPUT
interfaces to be used by the REFERENCED_BY_*_SHADER property in
GetProgramResourceiv (bug 9007).
- Remove duplicate reference to BUFFER_VARIABLE in the list of
interfaces supported by the ARRAY_SIZE property in
GetProgramResourceiv.
Revision 11, May 18, 2012 (pbrown)
- Clarify that the LOCATION_INDEX property is only supported for the
PROGRAM_OUTPUT interface and not for PROGRAM_INPUT.
Revision 10, May 10, 2012 (pbrown)
- Rename the formal parameter <interface> used by the functions in this
extension to <programInterface>. Certain versions of the Microsoft
C/C++ compiler and/or its headers cause "interface" to be treated as a
reserved keyword.
Revision 9, May 10, 2012 (pbrown)
- Fix incorrect enumerant assignments. ATOMIC_COUNTER_BUFFER has
already been assigned for ARB_shader_atomic_counters. Fix
cut-and-paste error assigning a duplicate value to
TESS_CONTROL_SUBROUTINE. Reassign value for IS_PER_PATCH to fill
the ATOMIC_COUNTER_BUFFER hole.
Revision 8, May 2, 2012 (pbrown)
- Reserve enumerants.
- Add state table entries.
- Mark issues as resolved per the Khronos F2F.
- Add issue (22), where we decided to keep the "int *" argument to
GetProgramResourceiv().
Revision 7, April 25, 2012
- Rename IS_PATCH_ATTRIB to IS_PER_PATCH (bug 8752).
Revision 6, April 12, 2012
- Add explicit language indicating that per-patch attributes can be
enumerated in the PROGRAM_INPUT and PROGRAM_OUTPUT interfaces, plus
the IS_PATCH_ATTRIB property.
- Take a first cut at redefining all the existing enumeration APIs in
terms of the new APIs.
- Add missing OFFSET token to new token list.
- Rename BUFFER_SIZE to BUFFER_DATA_SIZE to be consistent with older
token names.
- Mark various issues as resolved.
Revision 5, April 12, 2012
- Remove support for querying properties of multiple resources in a
single call; rename GetProgramResourcesiv to GetProgramResourceiv
since only a single resource is queried at a time.
- Fold issue (22) into issue (11).
Revision 4, April 5, 2012
- Add issue (22) about the need to allocate/fill an array of indices even
if you want to query properties of all active resources at once.
Revision 3, April 5, 2012
- Checkpoint with various edits/cleanups. Add an introduction; clean up
new procedures, tokens, errors, and issues sections.
- Rename APIs to GetProgramInterface and GetProgramResource*.
- Add GetProgramResourceLocation API as a generic location query.
- Add interactions with ARB_compute_shader.
- Add interactions with ARB_explicit_uniform_location.
- Add discussion of enumeration of built-in variables and special
transform feedback markers.
- Add general discussion of locations assigned to active variables.
- Add interface properties MAX_NUM_ACTIVE_VARIABLES and
MAX_NUM_COMPATIBLE_SUBROUTINES.
- Add resource properties LOCATION and LOCATION_INDEX.
- Add <bufSize> and <length> parameters to GetProgramResourcesiv.
Revision 2, March 22, 2012
- Added new function prototypes for review purposes.
Revision 1, March 14, 2012
- Initial revision.