5.7. Texture Access Functions

Texture access functions are available to both vertex and fragment shaders. Each of these functions takes as its first argument a variable of type sampler. If a variable qualified by sampler1D is used, then the texture access operation reads from the 1D texture that has previously been associated with that sampler by the application. (It is an error for the application to associate a non-1D texture with a sampler1D variable.) Similarly, a sampler2D variable is used to access a 2D texture, and so on. The texture precedence rules for OpenGL fixed functionality are ignored. It is up to the application to set up texture state before the shader executes in order to get the expected results (see Section 7.9).

The texture access functions obtain texture values from either mipmapped or non-mipmapped textures. However, level-of-detail is not computed by fixed functionality for vertex shaders, so there are some differences in operation between vertex and fragment texture access functions. Texture properties such as size, pixel format, number of dimensions, filtering method, number of mipmap levels, depth comparison, and so on are also defined by OpenGL API calls. Such properties are taken into account as the texture is accessed through the built-in functions defined in this section.

In all functions that follow, the bias parameter is optional for fragment shaders. The bias parameter is not accepted in a vertex shader. For a fragment shader, if bias is present, it is added to the calculated level of detail before the texture access operation is performed. If the bias parameter is not provided, the implementation automatically selects level-of-detail. For a texture that is not mipmapped, the texture is used directly. If a mipmap texture is accessed from a fragment shader, the level-of-detail computed by the implementation is used during the texture lookup. If a mipmapped texture is accessed from a vertex shader, the base texture is used.

The built-in functions suffixed with "Lod" are allowed only in a vertex shader. For the "Lod" functions, lod is directly used as the level-of-detail. The built-in functions suffixed with "Proj" can perform projective texturing. This allows a texture to be projected onto an object in much the same way that a slide projector projects an image onto a surface. Functions suffixed with "Proj" can compute shadow maps for rendering shadows, among other things.

A number of examples in later sections illustrate the use of these functions. With the programmability available with the OpenGL Shading Language, texture memory can store much more than just image data. These texture access functions provide fast, flexible access to such data in order to achieve a wide variety of effects (see Table 5.7).

Table 5.7. Texture access functions

Syntax	Description
vec4 texture1D (sampler1D sampler, float coord [, float bias]) vec4 texture1DProj (sampler1D sampler, vec2 coord [, float bias]) vec4 texture1DProj (sampler1D sampler, vec4 coord [, float bias]) vec4 texture1DLod (sampler1D sampler, float coord, float lod) vec4 texture1DProjLod (sampler1D sampler, vec2 coord, float lod) vec4 texture1DProjLod (sampler1D sampler, vec4 coord, float lod)	Use the texture coordinate coord to access the 1D texture currently specified by sampler. For the projective ("Proj") versions, the texture coordinate coord.s is divided by the last component of coord. The second and third components of coord are ignored for the vec4 coord variant.
vec4 texture2D (sampler2D sampler, vec2 coord [, float bias]) vec4 texture2DProj (sampler2D sampler, vec3 coord [, float bias]) vec4 texture2DProj (sampler2D sampler, vec4 coord [, float bias]) vec4 texture2DLod (sampler2D sampler, vec2 coord, float lod) vec4 texture2DProjLod (sampler2D sampler, vec3 coord, float lod) vec4 texture2DProjLod (sampler2D sampler, vec4 coord, float lod)	Use the texture coordinate coord to access the 2D texture currently specified by sampler. For the projective ("Proj") versions, the texture coordinate (coord.s, coord.t) is divided by the last component of coord. The third component of coord is ignored for the vec4 coord variant.
vec4 texture3D (sampler3D sampler, vec3 coord [, float bias]) vec4 texture3DProj (sampler3D sampler, vec4 coord [, float bias]) vec4 texture3DLod (sampler3D sampler, vec3 coord, float lod) vec4 texture3DProjLod (sampler3D sampler, vec4 coord, float lod)	Use the texture coordinate coord to access the 3D texture currently specified by sampler. For the projective ("Proj") versions, the texture coordinate is divided by coord.q.
vec4 textureCube (samplerCube sampler, vec3 coord [, float bias]) vec4 textureCubeLod (samplerCube sampler, vec3 coord, float lod)	Use the texture coordinate coord to access the cube map texture currently specified by sampler. The direction of coord selects the face in which to do a two-dimensional texture lookup.
vec4 shadow1D (sampler1DShadow sampler, vec3 coord [, float bias]) vec4 shadow2D (sampler2DShadow sampler, vec3 coord [, float bias]) vec4 shadow1DProj (sampler1DShadow sampler, vec4 coord [, float bias]) vec4 shadow2DProj (sampler2DShadow sampler, vec4 coord [, float bias]) vec4 shadow1DLod (sampler1DShadow sampler, vec3 coord, float lod) vec4 shadow2DLod (sampler2DShadow sampler, vec3 coord, float lod) vec4 shadow1DProjLod (sampler1DShadow sampler, vec4 coord, float lod) vec4 shadow2DProjLod (sampler2DShadow sampler, vec4 coord, float lod)	Use texture coordinate coord to do a depth comparison lookup on the depth texture specified by sampler. The third component of coord (coord.p) is compared to the value read from the depth texture. The texture bound to sampler must be a depth texture or results are undefined. For the projective ("Proj") version of each built-in, the texture coordinate is divided by coord.q, giving a depth value of coord.p/coord.q. The second component of coord is ignored for the "1D" variants.

Texturing results are undefined if

• A texture function other than one of the shadow variants is called with a sampler whose texture is a depth texture with depth comparisons enabled,

• A shadow texture call is made to a sampler whose texture is a depth texture with depth comparisons disabled, or

• A shadow texture call is made to a sampler whose texture is not a depth texture.