Name

glTexEnv — set texture environment parameters

C Specification

void glTexEnvf(GLenum  target,
 GLenum  pname,
 GLfloat  param);

void glTexEnvi(GLenum  target,
 GLenum  pname,
 GLint  param);

Parameters

target

Specifies a texture environment. May be GL_TEXTURE_ENV, GL_TEXTURE_FILTER_CONTROL or GL_POINT_SPRITE.

pname

Specifies the symbolic name of a single-valued texture environment parameter. May be either GL_TEXTURE_ENV_MODE, GL_TEXTURE_LOD_BIAS, GL_COMBINE_RGB, GL_COMBINE_ALPHA, GL_SRC0_RGB, GL_SRC1_RGB, GL_SRC2_RGB, GL_SRC0_ALPHA, GL_SRC1_ALPHA, GL_SRC2_ALPHA, GL_OPERAND0_RGB, GL_OPERAND1_RGB, GL_OPERAND2_RGB, GL_OPERAND0_ALPHA, GL_OPERAND1_ALPHA, GL_OPERAND2_ALPHA, GL_RGB_SCALE, GL_ALPHA_SCALE, or GL_COORD_REPLACE.

param

Specifies a single symbolic constant, one of GL_ADD, GL_ADD_SIGNED, GL_INTERPOLATE, GL_MODULATE, GL_DECAL, GL_BLEND, GL_REPLACE, GL_SUBTRACT, GL_COMBINE, GL_TEXTURE, GL_CONSTANT, GL_PRIMARY_COLOR, GL_PREVIOUS, GL_SRC_COLOR, GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, a single boolean value for the point sprite texture coordinate replacement, a single floating-point value for the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying the GL_RGB_SCALE or GL_ALPHA_SCALE.

C Specification

void glTexEnvfv(GLenum  target,
 GLenum  pname,
 const GLfloat *  params);
void glTexEnviv(GLenum  target,
 GLenum  pname,
 const GLint *  params);

Parameters

target

Specifies a texture environment. May be either GL_TEXTURE_ENV, or GL_TEXTURE_FILTER_CONTROL.

pname

Specifies the symbolic name of a texture environment parameter. Accepted values are GL_TEXTURE_ENV_MODE, GL_TEXTURE_ENV_COLOR, or GL_TEXTURE_LOD_BIAS.

params

Specifies a pointer to a parameter array that contains either a single symbolic constant, single floating-point number, or an RGBA color.

Description

A texture environment specifies how texture values are interpreted when a fragment is textured. When target is GL_TEXTURE_FILTER_CONTROL, pname must be GL_TEXTURE_LOD_BIAS. When target is GL_TEXTURE_ENV, pname can be GL_TEXTURE_ENV_MODE, GL_TEXTURE_ENV_COLOR, GL_COMBINE_RGB, GL_COMBINE_ALPHA, RGB_SCALE, ALPHA_SCALE, SRC0_RGB, SRC1_RGB, SRC2_RGB, SRC0_ALPHA, SRC1_ALPHA, or SRC2_ALPHA.

If pname is GL_TEXTURE_ENV_MODE, then params is (or points to) the symbolic name of a texture function. Six texture functions may be specified: GL_ADD, GL_MODULATE, GL_DECAL, GL_BLEND, GL_REPLACE, or GL_COMBINE.

A texture function acts on the fragment to be textured using the texture image value that applies to the fragment (see glTexParameter) and produces an RGBA color for that fragment. The following table shows how the RGBA color is produced for each of the three texture functions that can be chosen. C is a triple of color values (RGB) and A is the associated alpha value. RGBA values extracted from a texture image are in the range [0,1]. The subscript f refers to the incoming fragment, the subscript t to the texture image, the subscript c to the texture environment color, and subscript v indicates a value produced by the texture function.

A texture image can have up to four components per texture element (see glTexImage1D, glTexImage2D, glTexImage3D, glCopyTexImage1D, and glCopyTexImage2D). In a one-component image, L t indicates that single component. A two-component image uses L t and A t . A three-component image has only a color value, C t . A four-component image has both a color value C t and an alpha value A t .

Texture Base Internal Format GL_MODULATE Function GL_DECAL Function GL_BLEND Function
GL_ALPHA C v = C f undefined C v = C f
A v = A f ⁢ A t A v = A t ⁢ A f
GL_LUMINANCE C v = L t ⁢ C f undefined C v = 1 - L t ⁢ C f
(or 1) A v = A f A v = A f
GL_LUMINANCE_ALPHA C v = L t ⁢ C f undefined C v = 1 - L t ⁢ C f
(or 2) A v = A t ⁢ A f A v = A t ⁢ A f
GL_INTENSITY C v = C f ⁢ I t undefined C v = 1 - I t ⁢ C f
A v = A f ⁢ I t A v = 1 - I t ⁢ A f
GL_RGB C v = C t ⁢ C f C v = C t C v = 1 - C t ⁢ C f
(or 3) A v = A f A v = A f A v = A f
GL_RGBA C v = C t ⁢ C f C v = 1 - A t ⁢ C f + A t ⁢ C t C v = 1 - C t ⁢ C f
(or 4)
A v = A t ⁢ A f A v = A f A v = A t ⁢ A f

Texture Base Internal Format GL_REPLACE Function GL_ADD Function
GL_ALPHA C v = C f C v = C f
A v = A t A v = A f ⁢ A t
GL_LUMINANCE C v = L t C v = C f + L t
(or 1) A v = A f A v = A f
GL_LUMINANCE_ALPHA C v = L t + L t ⁢ C c C v = C f + L t
(or 2) A v = A t A v = A f ⁢ A t
GL_INTENSITY C v = I t + I t ⁢ C c C v = C f + I t
A v = I t + I t ⁢ A c A v = A f + I t
GL_RGB C v = C t + C t ⁢ C c C v = C f + C t
(or 3) A v = A f A v = A t
GL_RGBA C v = C t + C t ⁢ C c C v = C f + C t
(or 4) A v = A t A v = A t

If pname is GL_TEXTURE_ENV_MODE, and params is GL_COMBINE, the form of the texture function depends on the values of GL_COMBINE_RGB and GL_COMBINE_ALPHA.

The following describes how the texture sources, as specified by GL_SRC0_RGB, GL_SRC1_RGB, GL_SRC2_RGB, GL_SRC0_ALPHA, GL_SRC1_ALPHA, and GL_SRC2_ALPHA, are combined to produce a final texture color. In the following tables, GL_SRC0_c is represented by Arg0, GL_SRC1_c is represented by Arg1, and GL_SRC2_c is represented by Arg2.

GL_COMBINE_RGB accepts any of GL_REPLACE, GL_MODULATE, GL_ADD, GL_ADD_SIGNED, GL_INTERPOLATE, GL_SUBTRACT, GL_DOT3_RGB, or GL_DOT3_RGBA.

GL_COMBINE_RGB Texture Function
GL_REPLACE Arg0
GL_MODULATE Arg0 × Arg1
GL_ADD Arg0 + Arg1
GL_ADD_SIGNED Arg0 + Arg1 - 0.5
GL_INTERPOLATE Arg0 × Arg2 + Arg1 × 1 - Arg2
GL_SUBTRACT Arg0 - Arg1
GL_DOT3_RGB 4 × Arg0 r - 0.5 × Arg1 r - 0.5 +
or Arg0 g - 0.5 × Arg1 g - 0.5 +
GL_DOT3_RGBA Arg0 b - 0.5 × Arg1 b - 0.5

The scalar results for GL_DOT3_RGB and GL_DOT3_RGBA are placed into each of the 3 (RGB) or 4 (RGBA) components on output.

Likewise, GL_COMBINE_ALPHA accepts any of GL_REPLACE, GL_MODULATE, GL_ADD, GL_ADD_SIGNED, GL_INTERPOLATE, or GL_SUBTRACT. The following table describes how alpha values are combined:

GL_COMBINE_ALPHA Texture Function
GL_REPLACE Arg0
GL_MODULATE Arg0 × Arg1
GL_ADD Arg0 + Arg1
GL_ADD_SIGNED Arg0 + Arg1 - 0.5
GL_INTERPOLATE Arg0 × Arg2 + Arg1 × 1 - Arg2
GL_SUBTRACT Arg0 - Arg1

In the following tables, the value C s represents the color sampled from the currently bound texture, C c represents the constant texture-environment color, C f represents the primary color of the incoming fragment, and C p represents the color computed from the previous texture stage, or zero if processing texture stage 0. Likewise, A s , A c , A f , and A p represent the respective alpha values.

The following table describes the values assigned to Arg0, Arg1, and Arg2 based upon the RGB sources and operands:

GL_SRCn_RGB GL_OPERANDn_RGB Argument Value
GL_TEXTURE GL_SRC_COLOR C s
GL_ONE_MINUS_SRC_COLOR 1 - C s
GL_SRC_ALPHA A s
GL_ONE_MINUS_SRC_ALPHA 1 - A s
GL_TEXTUREn GL_SRC_COLOR C s
GL_ONE_MINUS_SRC_COLOR 1 - C s
GL_SRC_ALPHA A s
GL_ONE_MINUS_SRC_ALPHA 1 - A s
GL_CONSTANT GL_SRC_COLOR C c
GL_ONE_MINUS_SRC_COLOR 1 - C c
GL_SRC_ALPHA A c
GL_ONE_MINUS_SRC_ALPHA 1 - A c
GL_PRIMARY_COLOR GL_SRC_COLOR C f
GL_ONE_MINUS_SRC_COLOR 1 - C f
GL_SRC_ALPHA A f
GL_ONE_MINUS_SRC_ALPHA 1 - A f
GL_PREVIOUS GL_SRC_COLOR C p
GL_ONE_MINUS_SRC_COLOR 1 - C p
GL_SRC_ALPHA A p
GL_ONE_MINUS_SRC_ALPHA 1 - A p

For GL_TEXTUREn sources, C s and A s represent the color and alpha, respectively, produced from texture stage n.

The follow table describes the values assigned to Arg0, Arg1, and Arg2 based upon the alpha sources and operands:

GL_SRCn_ALPHA GL_OPERANDn_ALPHA Argument Value
GL_TEXTURE GL_SRC_ALPHA A s
GL_ONE_MINUS_SRC_ALPHA 1 - A s
GL_TEXTUREn GL_SRC_ALPHA A s
GL_ONE_MINUS_SRC_ALPHA 1 - A s
GL_CONSTANT GL_SRC_ALPHA A c
GL_ONE_MINUS_SRC_ALPHA 1 - A c
GL_PRIMARY_COLOR GL_SRC_ALPHA A f
GL_ONE_MINUS_SRC_ALPHA 1 - A f
GL_PREVIOUS GL_SRC_ALPHA A p
GL_ONE_MINUS_SRC_ALPHA 1 - A p

The RGB and alpha results of the texture function are multipled by the values of GL_RGB_SCALE and GL_ALPHA_SCALE, respectively, and clamped to the range 0 1 .

If pname is GL_TEXTURE_ENV_COLOR, params is a pointer to an array that holds an RGBA color consisting of four values. Integer color components are interpreted linearly such that the most positive integer maps to 1.0, and the most negative integer maps to -1.0. The values are clamped to the range [0,1] when they are specified. C c takes these four values.

If pname is GL_TEXTURE_LOD_BIAS, the value specified is added to the texture level-of-detail parameter, that selects which mipmap, or mipmaps depending upon the selected GL_TEXTURE_MIN_FILTER, will be sampled.

GL_TEXTURE_ENV_MODE defaults to GL_MODULATE and GL_TEXTURE_ENV_COLOR defaults to (0, 0, 0, 0).

If target is GL_POINT_SPRITE and pname is GL_COORD_REPLACE, the boolean value specified is used to either enable or disable point sprite texture coordinate replacement. The default value is GL_FALSE.

Notes

GL_REPLACE may only be used if the GL version is 1.1 or greater.

GL_TEXTURE_FILTER_CONTROL and GL_TEXTURE_LOD_BIAS may only be used if the GL version is 1.4 or greater.

GL_COMBINE mode and its associated constants may only be used if the GL version is 1.3 or greater.

GL_TEXTUREn may only be used if the GL version is 1.4 or greater.

Internal formats other than 1, 2, 3, or 4 may only be used if the GL version is 1.1 or greater.

For OpenGL versions 1.3 and greater, or when the ARB_multitexture extension is supported, glTexEnv controls the texture environment for the current active texture unit, selected by glActiveTexture.

GL_POINT_SPRITE and GL_COORD_REPLACE are available only if the GL version is 2.0 or greater.

Errors

GL_INVALID_ENUM is generated when target or pname is not one of the accepted defined values, or when params should have a defined constant value (based on the value of pname) and does not.

GL_INVALID_VALUE is generated if the params value for GL_RGB_SCALE is not one of 1.0, 2.0, or 4.0.

GL_INVALID_OPERATION is generated if glTexEnv is executed between the execution of glBegin and the corresponding execution of glEnd.

Associated Gets

glGetTexEnv

See Also

glActiveTexture, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D

Copyright

Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.