349 lines
12 KiB
Plaintext
349 lines
12 KiB
Plaintext
|
'\" e
|
||
|
|
'\"! eqn | mmdoc
|
||
|
|
'\"macro stdmacro
|
||
|
|
.ds Vn Version 1.2
|
||
|
|
.ds Dt 24 September 1999
|
||
|
|
.ds Re Release 1.2.1
|
||
|
|
.ds Dp Jan 14 18:30
|
||
|
|
.ds Dm 01 texparame
|
||
|
|
.ds Xs 38873 13 texparameter.gl
|
||
|
|
.TH GLTEXPARAMETER 3G
|
||
|
|
.SH NAME
|
||
|
|
.B "glTexParameterf, glTexParameteri, glTexParameterfv, glTexParameteriv
|
||
|
|
\- set texture parameters
|
||
|
|
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
void \f3glTexParameterf\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglTexParameterf( 'u
|
||
|
|
GLenum \fIpname\fP,
|
||
|
|
GLfloat \fIparam\fP )
|
||
|
|
.fi
|
||
|
|
void \f3glTexParameteri\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglTexParameteri( 'u
|
||
|
|
GLenum \fIpname\fP,
|
||
|
|
GLint \fIparam\fP )
|
||
|
|
.fi
|
||
|
|
|
||
|
|
.EQ
|
||
|
|
delim $$
|
||
|
|
.EN
|
||
|
|
.SH PARAMETERS
|
||
|
|
.TP \w'\f2target\fP\ \ 'u
|
||
|
|
\f2target\fP
|
||
|
|
Specifies the target texture,
|
||
|
|
which must be either \%\f3GL_TEXTURE_1D\fP, \%\f3GL_TEXTURE_2D\fP, or
|
||
|
|
\%\f3GL_TEXTURE_3D\fP.
|
||
|
|
.TP
|
||
|
|
\f2pname\fP
|
||
|
|
Specifies the symbolic name of a single-valued texture parameter.
|
||
|
|
\f2pname\fP can be one of the following:
|
||
|
|
\%\f3GL_TEXTURE_MIN_FILTER\fP,
|
||
|
|
\%\f3GL_TEXTURE_MAG_FILTER\fP,
|
||
|
|
\%\f3GL_TEXTURE_MIN_LOD\fP,
|
||
|
|
\%\f3GL_TEXTURE_MAX_LOD\fP,
|
||
|
|
\%\f3GL_TEXTURE_BASE_LEVEL\fP,
|
||
|
|
\%\f3GL_TEXTURE_MAX_LEVEL\fP,
|
||
|
|
\%\f3GL_TEXTURE_WRAP_S\fP,
|
||
|
|
\%\f3GL_TEXTURE_WRAP_T\fP,
|
||
|
|
\%\f3GL_TEXTURE_WRAP_R\fP, or
|
||
|
|
\%\f3GL_TEXTURE_PRIORITY\fP.
|
||
|
|
.TP
|
||
|
|
\f2param\fP
|
||
|
|
Specifies the value of \f2pname\fP.
|
||
|
|
.SH C SPECIFICATION
|
||
|
|
void \f3glTexParameterfv\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglTexParameterfv( 'u
|
||
|
|
GLenum \fIpname\fP,
|
||
|
|
const GLfloat \fI*params\fP )
|
||
|
|
.fi
|
||
|
|
void \f3glTexParameteriv\fP(
|
||
|
|
GLenum \fItarget\fP,
|
||
|
|
.nf
|
||
|
|
.ta \w'\f3void \fPglTexParameteriv( 'u
|
||
|
|
GLenum \fIpname\fP,
|
||
|
|
const GLint \fI*params\fP )
|
||
|
|
.fi
|
||
|
|
|
||
|
|
.SH PARAMETERS
|
||
|
|
.TP
|
||
|
|
\f2target\fP
|
||
|
|
Specifies the target texture,
|
||
|
|
which must be either \%\f3GL_TEXTURE_1D\fP, \%\f3GL_TEXTURE_2D\fP or
|
||
|
|
\%\f3GL_TEXTURE_3D\fP.
|
||
|
|
.TP
|
||
|
|
\f2pname\fP
|
||
|
|
Specifies the symbolic name of a texture parameter.
|
||
|
|
\f2pname\fP can be one of the following:
|
||
|
|
\%\f3GL_TEXTURE_MIN_FILTER\fP,
|
||
|
|
\%\f3GL_TEXTURE_MAG_FILTER\fP,
|
||
|
|
\%\f3GL_TEXTURE_MIN_LOD\fP,
|
||
|
|
\%\f3GL_TEXTURE_MAX_LOD\fP,
|
||
|
|
\%\f3GL_TEXTURE_BASE_LEVEL\fP,
|
||
|
|
\%\f3GL_TEXTURE_MAX_LEVEL\fP,
|
||
|
|
\%\f3GL_TEXTURE_WRAP_S\fP,
|
||
|
|
\%\f3GL_TEXTURE_WRAP_T\fP,
|
||
|
|
\%\f3GL_TEXTURE_WRAP_R\fP,
|
||
|
|
\%\f3GL_TEXTURE_BORDER_COLOR\fP, or
|
||
|
|
\%\f3GL_TEXTURE_PRIORITY\fP.
|
||
|
|
.TP
|
||
|
|
\f2params\fP
|
||
|
|
Specifies a pointer to an array where the value or values of \f2pname\fP
|
||
|
|
are stored.
|
||
|
|
.SH DESCRIPTION
|
||
|
|
Texture mapping is a technique that applies an image onto an object's surface
|
||
|
|
as if the image were a decal or cellophane 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.
|
||
|
|
.P
|
||
|
|
\%\f3glTexParameter\fP assigns the value or values in \f2params\fP to the texture parameter
|
||
|
|
specified as \f2pname\fP.
|
||
|
|
\f2target\fP defines the target texture,
|
||
|
|
either \%\f3GL_TEXTURE_1D\fP, \%\f3GL_TEXTURE_2D\fP, or \%\f3GL_TEXTURE_3D\fP.
|
||
|
|
The following symbols are accepted in \f2pname\fP:
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_MIN_FILTER\fP
|
||
|
|
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 nearest one or nearest four texture elements
|
||
|
|
to compute the texture value.
|
||
|
|
The other four use mipmaps.
|
||
|
|
.IP
|
||
|
|
A mipmap is an ordered set of arrays representing the same image
|
||
|
|
at progressively lower resolutions.
|
||
|
|
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 \%\f3glTexImage1D\fP, \%\f3glTexImage2D\fP,
|
||
|
|
\%\f3glTexImage3D\fP,
|
||
|
|
\%\f3glCopyTexImage1D\fP, or \%\f3glCopyTexImage2D\fP
|
||
|
|
with the \f2level\fP argument indicating the order of the mipmaps.
|
||
|
|
Level 0 is the original texture;
|
||
|
|
level $ bold max ( n, m ) $ is the final $1 ~times~ 1$ mipmap.
|
||
|
|
.IP
|
||
|
|
\f2params\fP supplies a function for minifying the texture as one of the following:
|
||
|
|
.RS 10
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_NEAREST\fP
|
||
|
|
Returns the value of the texture element that is nearest
|
||
|
|
(in Manhattan distance)
|
||
|
|
to the center of the pixel being textured.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_LINEAR\fP
|
||
|
|
Returns the weighted average of the four texture elements
|
||
|
|
that are closest to the center of the pixel being textured.
|
||
|
|
These can include border texture elements,
|
||
|
|
depending on the values of \%\f3GL_TEXTURE_WRAP_S\fP and \%\f3GL_TEXTURE_WRAP_T\fP,
|
||
|
|
and on the exact mapping.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_NEAREST_MIPMAP_NEAREST\fP
|
||
|
|
Chooses the mipmap that most closely matches the size of the pixel
|
||
|
|
being textured and uses the \%\f3GL_NEAREST\fP criterion
|
||
|
|
(the texture element nearest to the center of the pixel)
|
||
|
|
to produce a texture value.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_LINEAR_MIPMAP_NEAREST\fP
|
||
|
|
Chooses the mipmap that most closely matches the size of the pixel
|
||
|
|
being textured and uses the \%\f3GL_LINEAR\fP criterion
|
||
|
|
(a weighted average of the four texture elements that are closest
|
||
|
|
to the center of the pixel)
|
||
|
|
to produce a texture value.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_NEAREST_MIPMAP_LINEAR\fP
|
||
|
|
Chooses the two mipmaps that most closely match the size of the pixel
|
||
|
|
being textured and uses the \%\f3GL_NEAREST\fP 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.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_LINEAR_MIPMAP_LINEAR\fP
|
||
|
|
Chooses the two mipmaps that most closely match the size of the pixel
|
||
|
|
being textured and uses the \%\f3GL_LINEAR\fP 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.
|
||
|
|
.RE
|
||
|
|
.IP
|
||
|
|
As more texture elements are sampled in the minification process,
|
||
|
|
fewer aliasing artifacts will be apparent.
|
||
|
|
While the \%\f3GL_NEAREST\fP and \%\f3GL_LINEAR\fP 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 produce moire patterns
|
||
|
|
or ragged transitions.
|
||
|
|
The initial value of \%\f3GL_TEXTURE_MIN_FILTER\fP is
|
||
|
|
\%\f3GL_NEAREST_MIPMAP_LINEAR\fP.
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_MAG_FILTER\fP
|
||
|
|
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 \%\f3GL_NEAREST\fP
|
||
|
|
or \%\f3GL_LINEAR\fP (see below). \%\f3GL_NEAREST\fP is generally faster
|
||
|
|
than \%\f3GL_LINEAR\fP,
|
||
|
|
but it can produce textured images with sharper edges
|
||
|
|
because the transition between texture elements is not as smooth.
|
||
|
|
The initial value of \%\f3GL_TEXTURE_MAG_FILTER\fP is \%\f3GL_LINEAR\fP.
|
||
|
|
.RS 10
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_NEAREST\fP
|
||
|
|
Returns the value of the texture element that is nearest
|
||
|
|
(in Manhattan distance)
|
||
|
|
to the center of the pixel being textured.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_LINEAR\fP
|
||
|
|
Returns the weighted average of the four texture elements
|
||
|
|
that are closest to the center of the pixel being textured.
|
||
|
|
These can include border texture elements,
|
||
|
|
depending on the values of \%\f3GL_TEXTURE_WRAP_S\fP and \%\f3GL_TEXTURE_WRAP_T\fP,
|
||
|
|
and on the exact mapping.
|
||
|
|
.P
|
||
|
|
.RE
|
||
|
|
.P
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_MIN_LOD\fP
|
||
|
|
Sets the minimum level-of-detail parameter. This floating-point value
|
||
|
|
limits the selection of highest resolution mipmap (lowest mipmap
|
||
|
|
level). The initial value is -1000.
|
||
|
|
.P
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_MAX_LOD\fP
|
||
|
|
Sets the maximum level-of-detail parameter. This floating-point value
|
||
|
|
limits the selection of the lowest resolution mipmap (highest mipmap
|
||
|
|
level). The initial value is 1000.
|
||
|
|
.P
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_BASE_LEVEL\fP
|
||
|
|
Specifies the index of the lowest defined mipmap level. This is an
|
||
|
|
integer value. The initial value is 0.
|
||
|
|
.P
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_MAX_LEVEL\fP
|
||
|
|
Sets the index of the highest defined mipmap level. This is an integer
|
||
|
|
value. The initial value is 1000.
|
||
|
|
.P
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_WRAP_S\fP
|
||
|
|
Sets the wrap parameter for texture coordinate $s$ to either
|
||
|
|
\%\f3GL_CLAMP\fP, \%\f3GL_CLAMP_TO_EDGE\fP, or \%\f3GL_REPEAT\fP.
|
||
|
|
\%\f3GL_CLAMP\fP 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.
|
||
|
|
\%\f3GL_CLAMP_TO_EDGE\fP causes $s$ coordinates to be clamped to the range
|
||
|
|
$left [ {1 over 2N}, 1 - {1 over 2N} right ]$, where $N$ is the size
|
||
|
|
of the texture in the direction of clamping.
|
||
|
|
\%\f3GL_REPEAT\fP 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 \%\f3GL_CLAMP\fP.
|
||
|
|
Initially, \%\f3GL_TEXTURE_WRAP_S\fP is set to \%\f3GL_REPEAT\fP.
|
||
|
|
.P
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_WRAP_T\fP
|
||
|
|
Sets the wrap parameter for texture coordinate $t$ to either
|
||
|
|
\%\f3GL_CLAMP\fP, \%\f3GL_CLAMP_TO_EDGE\fP, or \%\f3GL_REPEAT\fP.
|
||
|
|
See the discussion under \%\f3GL_TEXTURE_WRAP_S\fP.
|
||
|
|
Initially, \%\f3GL_TEXTURE_WRAP_T\fP is set to \%\f3GL_REPEAT\fP.
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_WRAP_R\fP
|
||
|
|
Sets the wrap parameter for texture coordinate $r$ to either
|
||
|
|
\%\f3GL_CLAMP\fP, \%\f3GL_CLAMP_TO_EDGE\fP, or \%\f3GL_REPEAT\fP.
|
||
|
|
See the discussion under \%\f3GL_TEXTURE_WRAP_S\fP.
|
||
|
|
Initially, \%\f3GL_TEXTURE_WRAP_R\fP is set to \%\f3GL_REPEAT\fP.
|
||
|
|
.TP
|
||
|
|
\%\f3GL_TEXTURE_BORDER_COLOR\fP
|
||
|
|
Sets a border color.
|
||
|
|
\f2params\fP contains four values that comprise the RGBA color
|
||
|
|
of the texture border.
|
||
|
|
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.
|
||
|
|
Initially, the border color is (0, 0, 0, 0).
|
||
|
|
.TP 10
|
||
|
|
\%\f3GL_TEXTURE_PRIORITY\fP
|
||
|
|
Specifies the texture residence priority of the currently bound texture.
|
||
|
|
Permissible values are in the range [0,\ 1].
|
||
|
|
See \%\f3glPrioritizeTextures\fP and \%\f3glBindTexture\fP for more information.
|
||
|
|
.SH NOTES
|
||
|
|
\%\f3GL_TEXTURE_3D\fP, \%\f3GL_TEXTURE_MIN_LOD\fP, \%\f3GL_TEXTURE_MAX_LOD\fP,
|
||
|
|
\%\f3GL_TEXTURE_BASE_LEVEL\fP, and \%\f3GL_TEXTURE_MAX_LEVEL\fP are only
|
||
|
|
available if the GL version is 1.2 or greater.
|
||
|
|
.P
|
||
|
|
Suppose that a program has enabled texturing
|
||
|
|
(by calling \%\f3glEnable\fP
|
||
|
|
with argument \%\f3GL_TEXTURE_1D\fP, \%\f3GL_TEXTURE_2D\fP, or \%\f3GL_TEXTURE_3D\fP)
|
||
|
|
and has set \%\f3GL_TEXTURE_MIN_FILTER\fP to one of the functions
|
||
|
|
that requires a mipmap.
|
||
|
|
If either the dimensions of the texture images currently defined
|
||
|
|
(with previous calls to \%\f3glTexImage1D\fP, \%\f3glTexImage2D\fP,
|
||
|
|
\%\f3glTexImage3D\fP,
|
||
|
|
\%\f3glCopyTexImage1D\fP, or \%\f3glCopyTexImage2D\fP)
|
||
|
|
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.
|
||
|
|
.P
|
||
|
|
Linear filtering accesses the four nearest texture elements only in 2D
|
||
|
|
textures.
|
||
|
|
In 1D textures, linear filtering accesses the two nearest texture
|
||
|
|
elements.
|
||
|
|
.P
|
||
|
|
When the \%\f3GL_ARB_multitexture\fP extension is supported, \%\f3glTexParameter\fP
|
||
|
|
specifies the texture parameters for the active texture unit, specified
|
||
|
|
by calling \%\f3glActiveTextureARB\fP.
|
||
|
|
.SH ERRORS
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2target\fP or \f2pname\fP is not
|
||
|
|
one of the accepted defined values.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_ENUM\fP is generated if \f2params\fP should have a defined
|
||
|
|
constant value (based on the value of \f2pname\fP) and does not.
|
||
|
|
.P
|
||
|
|
\%\f3GL_INVALID_OPERATION\fP is generated if \%\f3glTexParameter\fP
|
||
|
|
is executed between the execution of \%\f3glBegin\fP
|
||
|
|
and the corresponding execution of \%\f3glEnd\fP.
|
||
|
|
.SH ASSOCIATED GETS
|
||
|
|
\%\f3glGetTexParameter\fP
|
||
|
|
.br
|
||
|
|
\%\f3glGetTexLevelParameter\fP
|
||
|
|
.SH SEE ALSO
|
||
|
|
\%\f3glActiveTextureARB(3G)\fP,
|
||
|
|
\%\f3glBindTexture(3G)\fP,
|
||
|
|
\%\f3glCopyPixels(3G)\fP,
|
||
|
|
\%\f3glCopyTexImage1D(3G)\fP,
|
||
|
|
\%\f3glCopyTexImage2D(3G)\fP,
|
||
|
|
\%\f3glCopyTexSubImage1D(3G)\fP,
|
||
|
|
\%\f3glCopyTexSubImage2D(3G)\fP,
|
||
|
|
\%\f3glCopyTexSubImage3D(3G)\fP,
|
||
|
|
\%\f3glDrawPixels(3G)\fP,
|
||
|
|
\%\f3glPixelStore(3G)\fP,
|
||
|
|
\%\f3glPixelTransfer(3G)\fP,
|
||
|
|
\%\f3glPrioritizeTextures(3G)\fP,
|
||
|
|
\%\f3glTexEnv(3G)\fP,
|
||
|
|
\%\f3glTexGen(3G)\fP,
|
||
|
|
\%\f3glTexImage1D(3G)\fP,
|
||
|
|
\%\f3glTexImage2D(3G)\fP,
|
||
|
|
\%\f3glTexImage3D(3G)\fP,
|
||
|
|
\%\f3glTexSubImage1D(3G)\fP,
|
||
|
|
\%\f3glTexSubImage2D(3G)\fP,
|
||
|
|
\%\f3glTexSubImage3D(3G)\fP
|
||
|
|
|
||
|
|
|