7.9. Samplers

glUniform1i and glUniform1iv load uniform variables defined as sampler types (i.e., uniform variables of type sampler1D, sampler2D, sample3D, samplerCube, sampler1DShadow, or sampler2DShadow). They may be declared within either vertex shaders or fragment shaders.

The value contained in a sampler is used within a shader to access a particular texture map. The value loaded into the sampler by the application should be the number of the texture unit to be used to access the texture. For vertex shaders, this value should be less than the implementationdependent constant GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS, which can be queried with glGet. For fragment shaders, this value should be less than the implementation-dependent constant GL_MAX_TEXTURE_IMAGE_UNITS.

The suffix on the sampler type indicates the texture type to be accessed: 1D, 2D, 3D, cube map, 1D shadow, or 2D shadow. In OpenGL, a texture object of each of the first four texture types can be bound to a single texture unit, and this suffix allows the desired texture object to be chosen. A 1D shadow sampler is used to access the 1D texture when depth comparisons are enabled, and a 2D shadow sampler is used to access the 2D texture when depth comparisons are enabled. If two uniform variables of different sampler types contain the same value, an error is generated when the next rendering command is issued. Attempting to load a sampler with any command other than glUniform1i or glUniform1iv results in an error being generated.

From within a shader, samplers should be considered an opaque data type. The current API provides a way of specifying an integer representing the texture image unit to be used. In the future, the API may be extended to allow a sampler to refer directly to a texture object.

Samplers that can be accessed when a program is executed are called ACTIVE SAMPLERS. The link operation fails if it determines that the number of active samplers exceeds the maximum allowable limits. The number of active samplers permitted on the vertex processor is specified by GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS, the number of active samplers permitted on the fragment processor is specified by GL_MAX_TEXTURE_IMAGE_UNITS, and the number of active samplers permitted on both processors combined is GL_COMBINED_TEXTURE_IMAGE_UNITS.

More detail on using samplers within a shader is provided in Section 10.1.