Shader Subroutine/Layout Qualifier

From OpenGL Wiki
Jump to: navigation, search

Shader Subroutines use a number of resources that can be automatically assigned to each shader stage at link time. However, the user can explicitly define them within the shader text as well, to avoid having to query them.

Subroutine functions each have a specific index that identifies that particular subroutine among all subroutines in a shader stage. This subroutine can be set from within a shader using the index​ layout qualifier:

layout(index = 2) subroutine(SubroutineTypeName, ...) ...;

This sets the particular subroutine function definition to index 2. No two subroutine functions may have the same index. Also, this index is subject to the limitations on the number of subroutines in a shader stage.

Each subroutine uniform variable within a shader stage has a particular position in that stage's list of subroutine uniforms. This location in the array can be set using the location​ layout qualifer:

layout(location = 1) subroutine uniform SubroutineTypeName subroutineVariableName;

This means that array index 1 in the call to glUniformSubroutines refers to the variable subroutineVariableName​.

The number of active subroutine uniforms for this shader stage will be the largest location + 1. This means that some "active" uniform locations may be unused. If the above example were the only subroutine uniform, then the number of active subroutine uniforms will be considered to be 2, with location 0 going unusued.

Arrays of subroutine uniforms are always assigned consecutive uniform locations.

If some uniforms are user-assigned and some are linker-assigned, the linker will fill in the unused indices first, before increasing the number of active uniforms. So the number of active subroutine uniforms can be larger than this. The linker will never assign a subroutine uniform to a user-assigned subroutine uniform, even if the user-assigned one is not active.

The linking can fail if user-defined subroutine uniform assignments do not leave enough room for linker-assigned ones. Linker-assigned subroutine uniform locations for arrays must also be consecutively assigned, so if there is insufficient space to assign that many uniform locations, the linking will fail.