1991-2006
Silicon Graphics, Inc.
glTexEnv
3G

# 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`, `GL_RGB_SCALE`, `GL_ALPHA_SCALE`, `GL_SRC0_RGB`, `GL_SRC1_RGB`, `GL_SRC2_RGB`, `GL_SRC0_ALPHA`, `GL_SRC1_ALPHA`, or `GL_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`.

The following table shows the correspondence of filtered texture values R t, G t, B t, A t, L t, I t to texture source components. C s and A s are used by the texture functions described below.

Texture Base Internal Format | C s | A s
--- | --- | ---
`GL_ALPHA` | (0, 0, 0) | A t
`GL_LUMINANCE` | ( L t, L t, L t ) | 1
`GL_LUMINANCE_ALPHA` | ( L t, L t, L t ) | A t
`GL_INTENSITY` | ( I t, I t, I t ) | I t
`GL_RGB` | ( R t, G t, B t ) | 1
`GL_RGBA` | ( R t, G t, B t ) | A t

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 first five 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 p refers to the color computed from the previous texture stage (or the incoming fragment if processing texture stage 0), the subscript s to the texture source color, the subscript c to the texture environment color, and the subscript v indicates a value produced by the texture function.

Texture Base Internal Format | `Value` | `GL_REPLACE` Function | `GL_MODULATE` Function | `GL_DECAL` Function | `GL_BLEND` Function | `GL_ADD` Function
--- | --- | --- | --- | --- | --- | ---
`GL_ALPHA` | C v = | C p | C p | undefined | C p | C p
| A v = | A s | A p &it; A s |  | A v = A p &it; A s | A p &it; A s
`GL_LUMINANCE` | C v = | C s | C p &it; C s | undefined | C p &it; 1 - C s + C c &it; C s | C p + C s
(or 1) | A v = | A p | A p |  | A p | A p
`GL_LUMINANCE_ALPHA` | C v = | C s | C p &it; C s | undefined | C p &it; 1 - C s + C c &it; C s | C p + C s
(or 2) | A v = | A s | A p &it; A s |  | A p &it; A s | A p &it; A s
`GL_INTENSITY` | C v = | C s | C p &it; C s | undefined | C p &it; 1 - C s + C c &it; C s | C p + C s
| A v = | A s | A p &it; A s |  | A p &it; 1 - A s + A c &it; A s | A p + A s
`GL_RGB` | C v = | C s | C p &it; C s | C s | C p &it; 1 - C s + C c &it; C s | C p + C s
(or 3) | A v = | A p | A p | A p | A p | A p
`GL_RGBA` | C v = | C s | C p &it; C s | C p &it; 1 - A s + C s &it; A s | C p &it; 1 - C s + C c &it; C s | C p + C s
(or 4) | A v = | A s | A p &it; A s | A p | A p &it; A s | A p &it; A s

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 C f 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` or `GL_ALPHA_SCALE` are 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/.