GLTEXPARAMETER() MachTen Programmer’s Manual GLTEXPARAMETER()

NAME
glTexParameterf, glTexParameteri, glTexParameterfv, glTex-
Parameteriv - set texture parameters

C SPECIFICATION
void glTexParameterf( GLenum target,
GLenum pname,
GLfloat param )
void glTexParameteri( GLenum target,
GLenum pname,
GLint param )

delim $$

PARAMETERS
target Specifies the target texture, which must be either
GL_TEXTURE_1D or GL_TEXTURE_2D.

pname Specifies the symbolic name of a single-valued
texture parameter. pname can be one of the fol-
lowing: GL_TEXTURE_MIN_FILTER,
GL_TEXTURE_MAG_FILTER, GL_TEXTURE_WRAP_S,
GL_TEXTURE_WRAP_T, or GL_TEXTURE_PRIORITY.

param Specifies the value of pname.

C SPECIFICATION
void glTexParameterfv( GLenum target,
GLenum pname,
const GLfloat *params )
void glTexParameteriv( GLenum target,
GLenum pname,
const GLint *params )

PARAMETERS
target Specifies the target texture, which must be either
GL_TEXTURE_1D or GL_TEXTURE_2D.

pname Specifies the symbolic name of a texture parameter.
pname can be one of the following:
GL_TEXTURE_MIN_FILTER, GL_TEXTURE_MAG_FILTER,
GL_TEXTURE_WRAP_S, GL_TEXTURE_WRAP_T,
GL_TEXTURE_BORDER_COLOR, or GL_TEXTURE_PRIORITY.

params Specifies a pointer to an array where the value or
values of pname are stored.

DESCRIPTION
Texture mapping is a technique that applies an image onto
an object’s surface as if the image were a decal or cello-
phane shrink-wrap. The image is created in texture space,
with an ($s$, $t$) coordinate system. A texture is a one-
or two-dimensional image and a set of parameters that
determine how samples are derived from the image.

glTexParameter assigns the value or values in params to
the texture parameter specified as pname. target defines
the target texture, either GL_TEXTURE_1D or GL_TEXTURE_2D.
The following symbols are accepted in pname:

GL_TEXTURE_MIN_FILTER
The texture minifying function is used whenever
the pixel being textured maps to an area greater
than one texture element. There are six defined
minifying functions. Two of them use the near-
est one or nearest four texture elements to com-
pute the texture value. The other four use
mipmaps.

A mipmap is an ordered set of arrays represent-
ing the same image at progressively lower reso-
lutions. If the texture has dimensions $2 sup n
times 2 sup m$, there are $ bold max ( n, m ) +
1 $ mipmaps. The first mipmap is the original
texture, with dimensions $2 sup n times 2 sup
m$. Each subsequent mipmap has dimensions $2
sup { k - 1 } times 2 sup { l - 1 }$, where $2
sup k times 2 sup l$ are the dimensions of the
previous mipmap, until either $k = 0$ or $l=0$.
At that point, subsequent mipmaps have dimension
$ 1 times 2 sup { l - 1 } $ or $ 2 sup { k - 1}
times 1 $ until the final mipmap, which has
dimension $1 times 1$. To define the mipmaps,
call glTexImage1D, glTexImage2D, glCopyTexIm-
age1D, or glCopyTexImage2D with the level argu-
ment indicating the order of the mipmaps. Level
0 is the original texture; level $ bold max ( n,
m ) $ is the final $1 times 1$ mipmap.

params supplies a function for minifying the
texture as one of the following:

GL_NEAREST
Returns the value of the texture ele-
ment that is nearest (in Manhattan
distance) to the center of the pixel
being textured.

GL_LINEAR Returns the weighted average of the
four texture elements that are closest
to the center of the pixel being tex-
tured. These can include border tex-
ture elements, depending on the values
of GL_TEXTURE_WRAP_S and
GL_TEXTURE_WRAP_T, and on the exact
mapping.

GL_NEAREST_MIPMAP_NEAREST
Chooses the mipmap that most closely
matches the size of the pixel being
textured and uses the GL_NEAREST cri-
terion (the texture element nearest to
the center of the pixel) to produce a
texture value.

GL_LINEAR_MIPMAP_NEAREST
Chooses the mipmap that most closely
matches the size of the pixel being
textured and uses the GL_LINEAR crite-
rion (a weighted average of the four
texture elements that are closest to
the center of the pixel) to produce a
texture value.

GL_NEAREST_MIPMAP_LINEAR
Chooses the two mipmaps that most
closely match the size of the pixel
being textured and uses the GL_NEAREST
criterion (the texture element nearest
to the center of the pixel) to produce
a texture value from each mipmap. The
final texture value is a weighted
average of those two values.

GL_LINEAR_MIPMAP_LINEAR
Chooses the two mipmaps that most
closely match the size of the pixel
being textured and uses the GL_LINEAR
criterion (a weighted average of the
four texture elements that are closest
to the center of the pixel) to produce
a texture value from each mipmap. The
final texture value is a weighted
average of those two values.

As more texture elements are sampled in the
minification process, fewer aliasing artifacts
will be apparent. While the GL_NEAREST and
GL_LINEAR minification functions can be faster
than the other four, they sample only one or
four texture elements to determine the texture
value of the pixel being rendered and can pro-
duce moire patterns or ragged transitions. The
initial value of GL_TEXTURE_MIN_FILTER is
GL_NEAREST_MIPMAP_LINEAR.

GL_TEXTURE_MAG_FILTER
The texture magnification function is used when
the pixel being textured maps to an area less
than or equal to one texture element. It sets
the texture magnification function to either
GL_NEAREST or GL_LINEAR (see below). GL_NEAREST
is generally faster than GL_LINEAR, but it can
produce textured images with sharper edges
because the transition between texture elements
is not as smooth. The initial value of
GL_TEXTURE_MAG_FILTER is GL_LINEAR.

GL_NEAREST
Returns the value of the texture ele-
ment that is nearest (in Manhattan
distance) to the center of the pixel
being textured.

GL_LINEAR Returns the weighted average of the
four texture elements that are closest
to the center of the pixel being tex-
tured. These can include border tex-
ture elements, depending on the values
of GL_TEXTURE_WRAP_S and
GL_TEXTURE_WRAP_T, and on the exact
mapping.

GL_TEXTURE_WRAP_S
Sets the wrap parameter for texture coordinate s
to either GL_CLAMP or GL_REPEAT. GL_CLAMP
causes $s$ coordinates to be clamped to the
range [0,1] and is useful for preventing
wrapping artifacts when mapping a single image
onto an object. GL_REPEAT causes the integer
part of the $s$ coordinate to be ignored; the GL
uses only the fractional part, thereby creating
a repeating pattern. Border texture elements
are accessed only if wrapping is set to
GL_CLAMP. Initially, GL_TEXTURE_WRAP_S is set
to GL_REPEAT.

GL_TEXTURE_WRAP_T
Sets the wrap parameter for texture coordinate t
to either GL_CLAMP or GL_REPEAT. See the dis-
cussion under GL_TEXTURE_WRAP_S. Initially,
GL_TEXTURE_WRAP_T is set to GL_REPEAT.

GL_TEXTURE_BORDER_COLOR
Sets a border color. params contains four val-
ues that comprise the RGBA color of the texture
border. Integer color components are inter-
preted linearly such that the most positive
integer maps to 1.0, and the most negative inte-
ger maps to -1.0. The values are clamped to the
range [0,1] when they are specified. Initially,
the border color is (0, 0, 0, 0).

GL_TEXTURE_PRIORITY
Specifies the texture residence priority of the
currently bound texture. Permissible values are
in the range [0, 1]. See glPrioritizeTextures
and glBindTexture for more information.

NOTES
Suppose that a program has enabled texturing (by calling
glEnable with argument GL_TEXTURE_1D or GL_TEXTURE_2D) and
has set GL_TEXTURE_MIN_FILTER to one of the functions that
requires a mipmap. If either the dimensions of the tex-
ture images currently defined (with previous calls to
glTexImage1D, glTexImage2D, glCopyTexImage1D, or glCopy-
TexImage2D) do not follow the proper sequence for mipmaps
(described above), or there are fewer texture images
defined than are needed, or the set of texture images have
differing numbers of texture components, then it is as if
texture mapping were disabled.

Linear filtering accesses the four nearest texture ele-
ments only in 2D textures. In 1D textures, linear filter-
ing accesses the two nearest texture elements.

ERRORS
GL_INVALID_ENUM is generated if target or pname is not one
of the accepted defined values.

GL_INVALID_ENUM is generated if params should have a
defined constant value (based on the value of pname) and
does not.

GL_INVALID_OPERATION is generated if glTexParameter is
executed between the execution of glBegin and the corre-
sponding execution of glEnd.

ASSOCIATED GETS
glGetTexParameter
glGetTexLevelParameter

SEE ALSO
glBindTexture, glCopyPixels, glCopyTexImage1D, glCopyTex-
Image2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glDraw-
Pixels, glPixelStore, glPixelTransfer, glPrioritizeTex-
tures, glTexEnv, glTexGen, glTexImage1D, glTexImage2D,
glTexSubImage1D, glTexSubImage2D

MachTen 5