GLTEXENV(3gl)GLTEXENV(3gl)NAME
glTexEnvf, glTexEnvi, glTexEnvfv, glTexEnviv - 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. Must be GL_TEXTURE_ENV.
pname Specifies the symbolic name of a single-valued texture environ‐
ment parameter. Either GL_TEXTURE_ENV_MODE or if target is
GL_TEXTURE_ENV then this can take texture env combiner modes.
See below.
param Specifies a single symbolic constant, one of GL_MODULATE,
GL_DECAL, GL_BLEND, GL_REPLACE, or GL_COMBINE_ARB or if target
is GL_TEXTURE_ENV and pname is any of the combiner modes then
this can take additional combiner operations as explained
below.
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. Must be GL_TEXTURE_ENV.
pname Specifies the symbolic name of a texture environment parameter.
Accepted values are GL_TEXTURE_ENV_MODE and GL_TEXTURE_ENV_COLOR
or any of the following env combine modes. GL_COMBINE_RGB_ARB,
GL_COMBINE_ALPHA_ARB, GL_SOURCE0_RGB_ARB, GL_SOURCE1_RGB_ARB,
GL_SOURCE2_RGB_ARB, GL_SOURCE0_ALPHA_ARB, GL_SOURCE1_ALPHA_ARB,
GL_SOURCE2_ALPHA_ARB, GL_OPERAND0_RGB_ARB, GL_OPERAND1_RGB_ARB,
GL_OPERAND2_RGB_ARB, GL_OPERAND0_ALPHA_ARB, GL_OPER‐
AND1_ALPHA_ARB, GL_OPERAND2_ALPHA_ARB, GL_RGB_SCALE_ARB,
GL_ALPHA_SCALE.
params Specifies a pointer to a parameter array that contains either a
single symbolic constant or an RGBA color.
DESCRIPTION
A texture environment specifies how texture values are interpreted when
a fragment is textured. target must be GL_TEXTURE_ENV. pname can be
GL_TEXTURE_ENV_MODE, GL_TEXTURE_ENV_COLOR, or GL_COMBINE_RGB_ARB,
GL_COMBINE_ALPHA_ARB, GL_SOURCE0_RGB_ARB, GL_SOURCE1_RGB_ARB,
GL_SOURCE2_RGB_ARB, GL_SOURCE0_ALPHA_ARB, GL_SOURCE1_ALPHA_ARB,
GL_SOURCE2_ALPHA_ARB, GL_OPERAND0_RGB_ARB, GL_OPERAND1_RGB_ARB, GL_OP‐
ERAND2_RGB_ARB, GL_OPERAND0_ALPHA_ARB, GL_OPERAND1_ALPHA_ARB, GL_OPER‐
AND2_ALPHA_ARB, GL_RGB_SCALE_ARB, GL_ALPHA_SCALE.
If pname is GL_TEXTURE_ENV_MODE, then params is (or points to) the sym‐
bolic name of a texture function. Six texture functions may be speci‐
fied: GL_ADD, GL_MODULATE, GL_DECAL, GL_BLEND, GL_REPLACE, and GL_COM‐
BINE_ARB.
If pname is GL_COMBINE_RGB_ARB or GL_COMBINE_ALPHA_ARB, then params is
the symbolic name of the combiner function, which can any of the fol‐
lowing. GL_REPLACE, GL_MODULATE, GL_ADD, GL_ADD_SIGNED_ARB, GL_INTER‐
POLATE_ARB, GL_SUBTRACT_ARB, GL_DOT3_RGB_ARB, and GL_DOT3_RGBA_ARB.
If pname is GL_SOURCE0_RGB_ARB, GL_SOURCE1_RGB_ARB, GL_SOURCE2_RGB_ARB,
GL_SOURCE0_ALPHA_ARB, GL_SOURCE1_ALPHA_ARB, GL_SOURCE2_ALPHA_ARB, then
params can be any of the following constants. GL_TEXTURE, GL_CON‐
STANT_ARB, GL_PRIMARY_COLOR_ARB, GL_PREVIOUS_ARB, and GL_TEX‐
TURE<u>_ARB, where <u> is in the range 0 to GL_MAX_TEXTURE_UNITS_ARB.
If pname is GL_OPERAND0_RGB_ARB, GL_OPERAND1_RGB_ARB, GL_OPER‐
AND2_RGB_ARB, GL_OPERAND0_ALPHA_ARB, GL_OPERAND1_ALPHA_ARB, GL_OPER‐
AND2_ALPHA_ARB, then params can be any of the following constants.
GL_SRC_COLOR, GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA, and
GL_ONE_MINUS_SRC_ALPHA.
If pname is GL_RGB_SCALE_ARB, GL_ALPHA_SCALE then params can be any of
the following values. 1.0, 2.0, 4.0.
A texture function acts on the fragment to be textured using the tex‐
ture 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 first four texture func‐
tions that can be chosen. For GL_COMBINE_ARB function, see the explana‐
tion at the end. 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, glCopyTexImage1D, and glCopyTexImage2D).
In a one-component image, Lt indicates that single component. A two-
component image uses Lt and At. A three-component image has only a
color value, Ct. A four-component image has both a color value Ct and
an alpha value At.
┌──────────────┬┬──────────────────────────────────────────────────────┐
│Base internal ││ Texture functions │
│ format ││GL_MODULATE GL_DECAL GL_BLEND GL_REPLACE │
├──────────────┼┼────────────┬─────────────┬──────────────┬────────────┤
│ GL_ALPHA ││ Cv=Cf │ undefined │ Cv=Cf │ Cv=Cf │
│ ││ Av=AfAt │ │ Av=Af │ Av=At │
├──────────────┼┼────────────┼─────────────┼──────────────┼────────────┤
│GL_LUMINANCE ││ Cv=LtCf │ undefined │ Cv=(1−Lt)Cf │ Cv=Lt │
│ 1 ││ │ │ +LtCc │ │
│ ││ │ │ │ │
│ ││ Av=Af │ │ Av=Af │ Av=Af │
├──────────────┼┼────────────┼─────────────┼──────────────┼────────────┤
│GL_LUMINANCE ││ Cv=LtCf │ undefined │ Cv=(1−Lt)Cf │ Cv=Lt │
│ \f3_ALPHA ││ │ │ +LtCc │ │
│ 2 ││ │ │ │ │
│ ││ Av=AtAf │ │ Av=AtAf │ Av=At │
├──────────────┼┼────────────┼─────────────┼──────────────┼────────────┤
│GL_INTENSITY ││ Cv=CfIt │ undefined │ Cv=(1−It)Cf │ Cv=It │
│ ││ │ │ +ItCc │ │
│ ││ │ │ │ │
│ ││ Av=AfIt │ │ Av=(1−It)Af │ Av=It │
│ ││ │ │ +ItAc │ │
├──────────────┼┼────────────┼─────────────┼──────────────┼────────────┤
│ GL_RGB ││ Cv=CtCf │ Cv=Ct │ Cv=(1−Ct)Cf │ Cv=Ct │
│ 3 ││ │ │ +CtCc │ │
│ ││ │ │ │ │
│ ││ Av=Af │ Av=Af │ Av=Af │ Av=Af │
├──────────────┼┼────────────┼─────────────┼──────────────┼────────────┤
│ GL_RGBA ││ Cv=CtCf │ Cv=(1−At)Cf │ Cv=(1−Ct)Cf │ Cv=Ct │
│ 4 ││ │ +AtCt │ +CtCc │ │
│ ││ │ │ │ │
│ ││ Av=AtAf │ Av=Af │ Av=AtAf │ Av=At │
└──────────────┴┴────────────┴─────────────┴──────────────┴────────────┘
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 compo‐
nents 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. Cc takes these
four values.
GL_TEXTURE_ENV_MODE defaults to GL_MODULATE and GL_TEXTURE_ENV_COLOR
defaults to (0, 0, 0, 0).
If the value of GL_TEXTURE_ENV_MODE is GL_COMBINE_ARB, the form of the
texture function depends on the values of GL_COMBINE_RGB_ARB and
GL_COMBINE_ALPHA_ARB, according to table below. The RGB and ALPHA
results of the texture function are then multiplied by the values of
GL_RGB_SCALE_ARB and GL_ALPHA_SCALE, respectively. The results are
clamped to [0,1].
GL_COMBINE_RGB_ARB Texture Function
----------------------------------
GL_REPLACE Arg0
GL_MODULATE Arg0 * Arg1
GL_ADD Arg0 + Arg1
GL_ADD_SIGNED_ARB Arg0 + Arg1 - 0.5
GL_INTERPOLATE_ARB Arg0 * (Arg2) + Arg1 * (1-Arg2)
GL_SUBTRACT_ARB Arg0 - Arg1
GL_DOT3_RGB_ARB 4 * ((Arg0_r - 0.5)*(Arg1_r - 0.5) +
(Arg0_g - 0.5)*(Arg1_g - 0.5) +
(Arg0_b - 0.5)*(Arg1_b - 0.5))
This value is placed into all three
r,g,b components of the output.
GL_DOT3_RGBA_ARB 4 * ((Arg0_r - 0.5)*(Arg1_r - 0.5) +
(Arg0_g - 0.5)*(Arg1_g - 0.5) +
(Arg0_b - 0.5)*(Arg1_b - 0.5))
This value is placed into all three
r,g,b,a components of the output.
Result generated from GL_COMBINE_ALPHA_ARB
is ignored.
GL_COMBINE_ALPHA_ARB Texture Function
----------------------------------
GL_REPLACE Arg0
GL_MODULATE Arg0 * Arg1
GL_ADD Arg0 + Arg1
GL_ADD_SIGNED_ARB Arg0 + Arg1 - 0.5
GL_INTERPOLATE_ARB Arg0 * (Arg2) + Arg1 * (1-Arg2)
GL_SUBTRACT_ARB Arg0 - Arg1
The arguments Arg0, Arg1 and Arg2 are determined by the values of
GL_SOURCE<n>_RGB_ARB, GL_SOURCE<n>_ALPHA_ARB, GL_OPERAND<n>_RGB_ARB and
GL_OPERAND<n>_ALPHA_ARB. In the following two tables, Ct and At are
the filtered texture RGB and alpha values; Ct<u> and At<u> are the
filtered texture RGB and alpha values from the texture bound to the
texture unit <u>. Cc and Ac are the
texture environment RGB and alpha values; Cf and Af are the RGB
and alpha of the primary color of the incoming fragment; and Cp
and Ap are the RGB and alpha values resulting from the previous
texture environment. On texture environment 0, Cp and Ap are
identical to Cf and Af, respectively. The relationship is
described in tables 2 and 3.
GL_SOURCE<n>_RGB_ARB GL_OPERAND<n>_RGB_ARB Argument
-------------------------------------------------
GL_TEXTURE GL_SRC_COLOR Ct
GL_ONE_MINUS_SRC_COLOR (1-Ct)
GL_SRC_ALPHA At
GL_ONE_MINUS_SRC_ALPHA (1-At)
GL_CONSTANT_ARB GL_SRC_COLOR Cc
GL_ONE_MINUS_SRC_COLOR (1-Cc)
GL_SRC_ALPHA Ac
GL_ONE_MINUS_SRC_ALPHA (1-Ac)
GL_PRIMARY_COLOR_ARB GL_SRC_COLOR Cf
GL_ONE_MINUS_SRC_COLOR (1-Cf)
GL_SRC_ALPHA Af
GL_ONE_MINUS_SRC_ALPHA (1-Af)
GL_PREVIOUS_ARB GL_SRC_COLOR Cp
GL_ONE_MINUS_SRC_COLOR (1-Cp)
GL_SRC_ALPHA Ap
GL_ONE_MINUS_SRC_ALPHA (1-Ap)
GL_TEXTURE<u>_ARB GL_SRC_COLOR Ct<u>
GL_ONE_MINUS_SRC_COLOR (1-Ct<u>)
GL_SRC_ALPHA At<u>
GL_ONE_MINUS_SRC_ALPHA (1-At<u>)
Table 2: Arguments for GL_COMBINE_RGB_ARB functions
GL_SOURCE<n>_ALPHA_ARB GL_OPERAND<n>_ALPHA_ARB Argument
-----------------------------------------------------
GL_TEXTURE GL_SRC_ALPHA At
GL_ONE_MINUS_SRC_ALPHA (1-At)
GL_CONSTANT_ARB GL_SRC_ALPHA Ac
GL_ONE_MINUS_SRC_ALPHA (1-Ac)
GL_PRIMARY_COLOR_ARB GL_SRC_ALPHA Af
GL_ONE_MINUS_SRC_ALPHA (1-Af)
GL_PREVIOUS_ARB GL_SRC_ALPHA Ap
GL_ONE_MINUS_SRC_ALPHA (1-Ap)
GL_TEXTURE<u>_ARB GL_SRC_ALPHA At<u>
GL_ONE_MINUS_SRC_ALPHA (1-At<u>)
Table 3: Arguments for GL_COMBINE_ALPHA_ARB functions
The mapping of texture components to source components is
summarized in Table 4. In the following table, At, Lt, It, Rt,
Gt and Bt are the filtered texel values.
Base Internal Format RGB Values Alpha Value
-----------------------------------------
GL_ALPHA 0, 0, 0 At
GL_LUMINANCE Lt, Lt, Lt 1
GL_LUMINANCE_ALPHA Lt, Lt, Lt At
GL_INTENSITY It, It, It It
GL_RGB Rt, Gt, Bt 1
GL_RGBA Rt, Gt, Bt At
Table 4: Correspondence of texture components to source
components for GL_COMBINE_RGB_ARB and GL_COMBINE_ALPHA_ARB arguments
NOTES
GL_REPLACE may only be used if the GL version is 1.1 or greater.
Internal formats other than 1, 2, 3, or 4 may only be used if the GL
version is 1.1 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_OPERATION is generated if glTexEnv is executed between the
execution of glBegin and the corresponding execution of glEnd.
GL_INVALID_ENUM is generated if params value for GL_SOURCE0_RGB_ARB,
GL_SOURCE1_RGB_ARB, GL_SOURCE2_RGB_ARB, GL_SOURCE0_ALPHA_ARB,
GL_SOURCE1_ALPHA_ARB or GL_SOURCE2_ALPHA_ARB is not one of GL_TEXTURE,
GL_CONSTANT_ARB, GL_PRIMARY_COLOR_ARB, GL_PREVIOUS_ARB, or GL_TEX‐
TURE<u>_ARB, where <u> is in the range 0 to GL_MAX_TEXTURE_UNITS_ARB.
GL_INVALID_ENUM is generated if params value for GL_OPERAND0_RGB_ARB,
GL_OPERAND1_RGB_ARB, or GL_OPERAND2_RGB_ARB is not one of GL_SRC_COLOR,
GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA or GL_ONE_MINUS_SRC_ALPHA.
GL_INVALID_ENUM is generated if params value for GL_OPERAND0_ALPHA_ARB,
GL_OPERAND1_ALPHA_ARB or GL_OPERAND2_ALPHA_ARB is not one of
GL_SRC_ALPHA, or GL_ONE_MINUS_SRC_ALPHA.
GL_INVALID_ENUM is generated if params value for GL_COMBINE_RGB_ARB, is
not one of GL_REPLACE, GL_MODULATE, GL_ADD, GL_ADD_SIGNED_ARB,
GL_INTERPOLATE_ARB, GL_SUBTRACT_ARB, GL_DOT3_RGB_ARB or
GL_DOT3_RGBA_ARB..
GL_INVALID_VALUE is generated if params value for GL_RGB_SCALE_ARB or
GL_ALPHA_SCALE is not one of 1.0, 2.0, or 4.0.
ASSOCIATED GETS
glGetTexEnv
SEE ALSO
glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D,
glCopyTexSubImage2D, glTexImage1D, glTexImage2D, glTexParameter, glTex‐
SubImage1D, glTexSubImage2D
15 Mar 97 GLTEXENV(3gl)