NAME

glBindTexture - bind a named texture to a texturing target

C SPECIFICATION

void ggllBBiinnddTTeexxttuurree( GLenum _t_a_r_g_e_t,
                    GLuint _t_e_x_t_u_r_e )

PARAMETERS

_t_a_r_g_e_t
Specifies the target to which the texture is bound. Must be either GGLL__TTEEXXTTUURREE__11DD, GGLL__TTEEXXTTUURREE__22DD, or GGLL__TTEEXXTTUURREE__33DD.
_t_e_x_t_u_r_e
Specifies the name of a texture.

DESCRIPTION

ggllBBiinnddTTeexxttuurree lets you create or use a named texture. Calling ggllBBiinnddTTeexxttuurree with
_t_a_r_g_e_t set to GGLL__TTEEXXTTUURREE__11DD, GGLL__TTEEXXTTUURREE__22DD, GGLL__TTEEXXTTUURREE__33DD and _t_e_x_t_u_r_e set to the name of the newtexture binds the texture name to the target. When a texture is bound to a target, the previous binding for that target is automatically broken.

Texture names are unsigned integers. The value zero is reserved to represent the default texture for each texture target. Texture names and the corresponding texture contents are local to the shared display-list space (see ggllXXCCrreeaatteeCCoonntteexxtt) of the current GL rendering context; two rendering contexts share texture names only if they also share display lists.

You may use ggllGGeennTTeexxttuurreess to generate a set of new texture names.

When a texture is first bound, it assumes the dimensionality of its target: A texture first bound to GGLL__TTEEXXTTUURREE__11DD becomes one-dimensional, and a texture first bound to GGLL__TTEEXXTTUURREE__22DD becomes two-dimensional, and a texture first bound to GGLL__TTEEXXTTUURREE__33DD becomes a three-dimensional texture. The state of a one-dimensional texture immediately after it is first bound is equivalent to the state of the default GGLL__TTEEXXTTUURREE__11DD at GL initialization, and similarly for two-, and three-dimensional textures.

While a texture is bound, GL operations on the target to which it is bound affect the bound texture, and queries of the target to which it is bound return state from the bound texture. If texture mapping of the dimensionality of the target to which a texture is bound is active, the bound texture is used. In effect, the texture targets become aliases for the textures currently bound to them, and the texture name zero refers to the default textures that were bound to them at initialization.

A texture binding created with ggllBBiinnddTTeexxttuurree remains active until a different texture is bound to the same target, or until the bound texture is deleted with ggllDDeelleetteeTTeexxttuurreess.

Once created, a named texture may be re-bound to the target of the matching dimensionality as often as needed. It is usually much faster to use ggllBBiinnddTTeexxttuurree to bind an existing named texture to one of the texture targets than it is to reload the texture image using ggllTTeexxIImmaaggee11DD, ggllTTeexxIImmaaggee22DD, or ggllTTeexxIImmaaggee33DD. For additional control over performance, use ggllPPrriioorriittiizzeeTTeexxttuurreess.

ggllBBiinnddTTeexxttuurree is included in display lists.

NOTES

ggllBBiinnddTTeexxttuurree is available only if the GL version is 1.1 or greater.

ERRORS

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_a_r_g_e_t is not one of the allowable values.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _t_e_x_t_u_r_e has a dimensionality that doesn't match that of _t_a_r_g_e_t.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllBBiinnddTTeexxttuurree is executed between the execution of ggllBBeeggiinn and the corresponding execution of ggllEEnndd.

ASSOCIATED GETS

ggllGGeett with argument GGLL__TTEEXXTTUURREE__BBIINNDDIINNGG__11DD
ggllGGeett with argument GGLL__TTEEXXTTUURREE__BBIINNDDIINNGG__22DD
ggllGGeett with argument GGLL__TTEEXXTTUURREE__BBIINNDDIINNGG__33DD

SEE ALSO

ggllAArreeTTeexxttuurreessRReessiiddeenntt((33GG)), ggllDDeelleetteeTTeexxttuurreess((33GG)), ggllGGeennTTeexxttuurreess((33GG)), ggllGGeett((33GG)),
ggllGGeettTTeexxPPaarraammeetteerr((33GG)), ggllIIssTTeexxttuurree((33GG)), ggllPPrriioorriittiizzeeTTeexxttuurreess((33GG)), ggllTTeexxIImmaaggee11DD((33GG)), ggllTTeexxIImmaaggee22DD((33GG)), ggllTTeexxPPaarraammeetteerr((33GG))