View source for Shader Subroutine/Introspection

Because the list of {{pagelink|Shader Subroutine|subroutine resources}} (of all kinds) are broken down by shader stage, all functions that query information about them take a {{param|shadertype}} parameter in addition to the {{param|program}} object to query from. The {{param|shadertype}} is the [[Shader Stage|shader stage enumerator name]] for the stage to query information about.

Each active subroutine (a subroutine function which can be used with a subroutine uniform that itself is active) has an index. There are two ways to get the index for a particular subroutine function. If you have the name of a subroutine, you can query the index with this function:

{{funcdef|GLuint {{apifunc|glGetSubroutineIndex}}(GLuint {{param|program}}, GLenum {{param|shadertype}}, const GLchar *{{param|name}});}}

If {{param|name}} does not name an ''active'' subroutine function, then {{enum|GL_INVALID_INDEX}} will be returned. Otherwise, it will be the index of the subroutine function.

To iterate through the list of all subroutine functions, you can query the total number of subroutines. This is done via this function:

{{funcdef|void {{apifunc|glGetProgramStage|iv}}(GLuint {{param|program}}, GLenum {{param|shadertype}}, GLenum {{param|pname}}, GLint *{{param|values}});}}

To query the number of active subroutine functions, {{param|pname}} must be {{enum|GL_ACTIVE_SUBROUTINES}}. This stores the number of active subroutine functions as a single integer in {{param|values}}.

To get the name of a subroutine function from an index, pass the {{param|index}} to this function:

{{funcdef|void {{apifunc|glGetActiveSubroutineName}}(GLuint {{param|program}}, GLenum {{param|shadertype}}, GLuint {{param|index}}, GLsizei {{param|bufsize}}, GLsizei *{{param|length}}, GLchar *{{param|name}});}}

{{param|bufsize}} is the total number of bytes that {{param|name}} points to; OpenGL will not write more than this number of bytes. If {{param|length}} is not NULL, the function will write the number of characters written into {{param|name}}.

There is no way to query the length of the name for a specific subroutine function (at least, not with this API. You must use the [[Program Interface Query|query API for that]]). However, you can query the largest subroutine function name used by a shader stage. This is done with {{apifunc|glGetProgramStage}}, using the {{enum|GL_ACTIVE_SUBROUTINE_MAX_LENGTH}} enumerator.

The name is the only information that can be queried about a subroutine function directly.

Like regular [[Uniform (GLSL)|uniforms]], subroutine uniforms have both a location and an index. The location is used when actually selecting which subroutine to use for that uniform, while the index is ''only'' used to query information about that uniform.

To iterate through the number of subroutine uniforms for a stage and query information about them, you must first get the number of subroutine uniform indices. This uses {{apifunc|glGetProgramStage}} with {{param|GL_ACTIVE_SUBROUTINE_UNIFORMS}}. The valid indices range from 0 to that value minus one.

Armed with a subroutine uniform {{param|index}}, one can query general information about the subroutine uniform with this function:

{{funcdef|void {{apifunc|glGetActiveSubroutineUniform|iv}}(GLuint {{param|program}}, GLenum {{param|shadertype}}, GLuint {{param|index}}, GLenum {{param|pname}}, GLint *{{param|values}});}}

{{param|pname}} defines what information is to be set into {{param|values}}:

* {{enum|GL_NUM_COMPATIBLE_SUBROUTINES}}: The number of subroutine functions that can be used with this uniform.
* {{enum|GL_COMPATIBLE_SUBROUTINES}}: This returns an array of indices for each of the subroutine functions that can be used with this uniform. {{param|values}} must be at least {{enum|GL_NUM_COMPATIBLE_SUBROUTINES}} entries in size.
* {{enum|GL_UNIFORM_SIZE}}: The number of entries in the subroutine uniform. Subroutine uniforms can be in arrays, so this is the count of array elements. If the subroutine uniform is not an array, 
* {{enum|GL_UNIFORM_NAME_LENGTH}}: The length of the uniform's name.

To get the subroutine uniform's name, call this function:

{{funcdef|void {{apifunc|glGetActiveSubroutineUniformName}}(GLuint {{param|program}}, GLenum {{param|shadertype}}, GLuint {{param|index}}, GLsizei {{param|bufsize}}, GLsizei *{{param|length}}, GLchar *{{param|name}});}}

The subroutine uniform location is used to know how to assign a subroutine function index to the subroutine uniform when it comes time to render with the shader.

Regular [[Uniform (GLSL)|uniform variables]] are assigned locations arbitrarily. Subroutine uniforms are a bit different. The number of subroutine uniform locations assigned to a particular shader stage can be determined by calling {{apifunc|glGetProgramStage}} with {{enum|GL_ACTIVE_SUBROUTINE_UNIFORM_LOCATIONS}}. ''All'' subroutine uniform locations less than that number (and >= 0) are active subroutine uniform locations. This is required by the specification.

Because subroutine uniforms can be arrays, there can be more subroutine uniform locations than there are subroutine uniform indices. Each subroutine uniform only counts as one for the index list, but arrayed subroutine uniforms take up multiple locations.

To get a subroutine uniform's location given the name, use this function:

{{funcdef|GLint {{apifunc|glGetSubroutineUniformLocation}}(GLuint {{param|program}}, GLenum {{param|shadertype}}, const GLchar *{{param|name}});}}

If {{param|name}} names an arrayed subroutine uniform, then the location refers to X consecutive locations starting from the returned location, where X is the array size declared in the shader. If the subroutine uniform is not active, this function will return -1.