| 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, ¶ms[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. |
| |