[OpenGL] Inconsistencies and missing information regarding glGetProgramResourceiv

[einsweniger]

I hope this is the correct place to report issues with the Core Spec. I would have made a pull request with the proposed changes, but I can't figure out how the core spec PDF is generated. (I'm guessing it's not generated from the Refpages as these are littered with typos :D)

Where are my issues: Table 7.2 references allowed property/interface combinations to request via glGetProgramResourceiv the following section (starting w/ pg 111) describes the return values and semantics for the properties.

Inconsistencies:

Most of the descriptions start by stating the property followed by the kind of returned values, e.g.:

For property ARRAY_SIZE, a single integer identifying [$FUNCTION] is written to params.

Several properties do not follow these 'templates', namely:

• BUFFER_BINDING, the index of the buffer binding point associated with the active uniform block, atomic counter buffer, shader storage block, or transform feedback buffer is written to params.

• BUFFER_DATA_SIZE, the implementation-dependent minimum total buffer object size is written to params. This value is the size, in basic machine units, required to hold all active variables associated with an active uniform block, shader storage block, or atomic counter buffer. If the final member of an active shader storage block is an array with no declared size, the minimum buffer size is computed assuming the array was declared as an array with one element.

• NUM_ACTIVE_VARIABLES, the number of active variables associated with an active uniform block, atomic counter buffer, shader storage block, or transform feedback buffer is written to params.

• ACTIVE_VARIABLES, an array of active variable indices associated with an atomic counter buffer, active uniform block, shader storage block, or transform feedback 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.

• REFERENCEDBY*_SHADER, a single integer is written to params, identifying whether the active resource is referenced by the vertex, tessellation control, tessellation evaluation, geometry, fragment, or compute 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.

I'd like to propose a change to the following (changes to first sentence highlighted):

• BUFFER_BINDING, a single integer identifying the index of the buffer binding point associated with the active uniform block, atomic counter buffer, shader storage block, or transform feedback buffer is written to params.

• BUFFER_DATA_SIZE, a single integer identifying the implementation-dependent minimum total buffer object size is written to params. [...]

• NUM_ACTIVE_VARIABLES, a single integer identifying the number of active variables associated with an active uniform block, atomic counter buffer, shader storage block, or transform feedback buffer is written to params.

I like the style the REFERENCEDBY*_SHADER section is written in better ("single integer is written to params, identifying [...]"), but that would require more changes.

Missing information:

Then: there are two missing properties which are in the table; but not in the description:

NUM_COMPATIBLE_SUBROUTINES and COMPATIBLE_SUBROUTINES.

I'd propose a text analogous to NUM_ACTIVE_VARIABLES for the first (if using the proposed change above):

For the property NUM_COMPATIBLE_SUBROUTINES, a single integer identifying the number of compatible subroutines associated with an active subroutine uniform is written to params.

as for COMPATIBLE_SUBROUTINES:

For the property COMPATIBLE_SUBROUTINES, an array of compatible subroutine indices associated with an active subroutine uniform is written to params. The number of values written to params for an active resource is given by the value of the property NUM_COMPATIBLE_SUBROUTINES for the resource.

[einsweniger]

While I'm here :D : I really dislike the Table 7.2 for GetProgramResourceiv, it's a little annoying to figure out which property is allowed on their respective interfaces. If it's possible, could we replace that with a matrix of [Property x Interface] with dots for allowed combinations? (in the style of p114 or maybe as an other table in the appendix)?

[pdaniell-nv]

Discussed in the OpenGL/ES working group meeting today. We agreed the addition of "a single integer identifying" to the descriptions of BUFFER_BINDING, BUFFER_DATA_SIZE and NUM_ACTIVE_VARIABLES would be a positive change. This change would be required in both the OpenGL and OpenGL ES specs.

We also agreed to add the missing descriptions for NUM_COMPATIBLE_SUBROUTINES and COMPATIBLE_SUBROUTINES to the OpenGL spec as suggested above.

Thanks for your issue and suggested changes.

Assigned to @oddhack to update the OpenGL and OpenGL ES specs with these changes.

[oddhack]

The fixes identified by @pdaniell-nv will be in the next GL & ES spec updates, coming soon.