path: root/nx-X11/extras/ogl-sample/main/doc/man/mangl/standard/texparameter.gl

_C_ License Applicability. Except to the extent portions of this file are
_C_ made subject to an alternative license as permitted in the SGI Free
_C_ Software License B, Version 1.1 (the "License"), the contents of this
_C_ file are subject only to the provisions of the License. You may not use
_C_ this file except in compliance with the License. You may obtain a copy
_C_ of the License at Silicon Graphics, Inc., attn: Legal Services, 1600
_C_ Amphitheatre Parkway, Mountain View, CA 94043-1351, or at:
_C_ 
_C_ http://oss.sgi.com/projects/FreeB
_C_ 
_C_ Note that, as provided in the License, the Software is distributed on an
_C_ "AS IS" basis, with ALL EXPRESS AND IMPLIED WARRANTIES AND CONDITIONS
_C_ DISCLAIMED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES AND
_C_ CONDITIONS OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR A
_C_ PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
_C_ 
_C_ Original Code. The Original Code is: OpenGL Sample Implementation,
_C_ Version 1.2.1, released January 26, 2000, developed by Silicon Graphics,
_C_ Inc. The Original Code is Copyright (c) 1991-2000 Silicon Graphics, Inc.
_C_ Copyright in any portions created by third parties is as indicated
_C_ elsewhere herein. All Rights Reserved.
_C_ 
_C_ Additional Notice Provisions: The application programming interfaces
_C_ established by SGI in conjunction with the Original Code are The
_C_ OpenGL(R) Graphics System: A Specification (Version 1.2.1), released
_C_ April 1, 1999; The OpenGL(R) Graphics System Utility Library (Version
_C_ 1.3), released November 4, 1998; and OpenGL(R) Graphics with the X
_C_ Window System(R) (Version 1.3), released October 19, 1998. This software
_C_ was created using the OpenGL(R) version 1.2.1 Sample Implementation
_C_ published by SGI, but has not been independently verified as being
_C_ compliant with the OpenGL(R) version 1.2.1 Specification.
_C_
_C_ The first character in this file must be an '_'!
_C_ Anything on a line after _C_ is ignored
_define(_filters,eqn)_C_
_C_      eqn is automatically replaced with neqn for nroff
_header(TexParameter, set texture parameters)
_names(TexParameter,[fi])
.EQ
delim $$
.EN
.SH PARAMETERS
_phead(_param1)
Specifies the target texture,
which must be either _const(TEXTURE_1D), _const(TEXTURE_2D), or
_const(TEXTURE_3D).
_phead(_param2)
Specifies the symbolic name of a single-valued texture parameter.
_param2 can be one of the following:
_const(TEXTURE_MIN_FILTER),
_const(TEXTURE_MAG_FILTER),
_const(TEXTURE_MIN_LOD),
_const(TEXTURE_MAX_LOD),
_const(TEXTURE_BASE_LEVEL),
_const(TEXTURE_MAX_LEVEL),
_const(TEXTURE_WRAP_S), 
_const(TEXTURE_WRAP_T),
_const(TEXTURE_WRAP_R), or
_const(TEXTURE_PRIORITY).
_phead(_param3)
Specifies the value of _param2.
_names(TexParameter,[fi]v)
.SH PARAMETERS
_phead(_param1)
Specifies the target texture,
which must be either _const(TEXTURE_1D), _const(TEXTURE_2D) or
_const(TEXTURE_3D).
_phead(_param2)
Specifies the symbolic name of a texture parameter.
_param2 can be one of the following:
_const(TEXTURE_MIN_FILTER),
_const(TEXTURE_MAG_FILTER),
_const(TEXTURE_MIN_LOD),
_const(TEXTURE_MAX_LOD),
_const(TEXTURE_BASE_LEVEL),
_const(TEXTURE_MAX_LEVEL),
_const(TEXTURE_WRAP_S),
_const(TEXTURE_WRAP_T),
_const(TEXTURE_WRAP_R), 
_const(TEXTURE_BORDER_COLOR), or
_const(TEXTURE_PRIORITY).
_phead(_param3)
Specifies a pointer to an array where the value or values of _param2
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
_cmnd assigns the value or values in _param3 to the texture parameter
specified as _param2. 
_param1 defines the target texture,
either _const(TEXTURE_1D), _const(TEXTURE_2D), or _const(TEXTURE_3D).
The following symbols are accepted in _param2:
.TP 10
_const(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 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 _cmnd(TexImage1D), _cmnd(TexImage2D),
_cmnd(TexImage3D), 
_cmnd(CopyTexImage1D), or _cmnd(CopyTexImage2D)
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
_param3 supplies a function for minifying the texture as one of the following:
.RS 10
.TP 10
_const(NEAREST)
Returns the value of the texture element that is nearest
(in Manhattan distance)
to the center of the pixel being textured.
.TP
_const(LINEAR)
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 _const(TEXTURE_WRAP_S) and _const(TEXTURE_WRAP_T),
and on the exact mapping.
.TP
_const(NEAREST_MIPMAP_NEAREST)
Chooses the mipmap that most closely matches the size of the pixel
being textured and uses the _const(NEAREST) criterion
(the texture element nearest to the center of the pixel)
to produce a texture value.
.TP
_const(LINEAR_MIPMAP_NEAREST)
Chooses the mipmap that most closely matches the size of the pixel
being textured and uses the _const(LINEAR) criterion
(a weighted average of the four texture elements that are closest
to the center of the pixel)
to produce a texture value.
.TP
_const(NEAREST_MIPMAP_LINEAR)
Chooses the two mipmaps that most closely match the size of the pixel
being textured and uses the _const(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.
.TP
_const(LINEAR_MIPMAP_LINEAR)
Chooses the two mipmaps that most closely match the size of the pixel
being textured and uses the _const(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.
.RE
.IP
As more texture elements are sampled in the minification process,
fewer aliasing artifacts will be apparent. 
While the _const(NEAREST) and _const(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 produce moire patterns
or ragged transitions. 
The initial value of _const(TEXTURE_MIN_FILTER) is
_const(NEAREST_MIPMAP_LINEAR).
.TP 10
_const(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 _const(NEAREST)
or _const(LINEAR) (see below). _const(NEAREST) is generally faster
than _const(LINEAR), 
but it can produce textured images with sharper edges
because the transition between texture elements is not as smooth. 
The initial value of _const(TEXTURE_MAG_FILTER) is _const(LINEAR).
.RS 10
.TP 10
_const(NEAREST)
Returns the value of the texture element that is nearest
(in Manhattan distance)
to the center of the pixel being textured.
.TP
_const(LINEAR)
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 _const(TEXTURE_WRAP_S) and _const(TEXTURE_WRAP_T),
and on the exact mapping.
.P
.RE
.P
.TP 10
_const(TEXTURE_MIN_LOD)
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
_const(TEXTURE_MAX_LOD)
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
_const(TEXTURE_BASE_LEVEL)
Specifies the index of the lowest defined mipmap level. This is an
integer value. The initial value is 0.
.P
.TP 10
_const(TEXTURE_MAX_LEVEL)
Sets the index of the highest defined mipmap level. This is an integer
value. The initial value is 1000.
.P
.TP 10
_const(TEXTURE_WRAP_S)
Sets the wrap parameter for texture coordinate $s$ to either
_const(CLAMP), _const(CLAMP_TO_EDGE), or _const(REPEAT).
_const(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.
_const(CLAMP_TO_EDGE) 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.
_const(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 _const(CLAMP).
Initially, _const(TEXTURE_WRAP_S) is set to _const(REPEAT).
.P
.TP 10
_const(TEXTURE_WRAP_T)
Sets the wrap parameter for texture coordinate $t$ to either
_const(CLAMP), _const(CLAMP_TO_EDGE), or _const(REPEAT).
See the discussion under _const(TEXTURE_WRAP_S). 
Initially, _const(TEXTURE_WRAP_T) is set to _const(REPEAT).
.TP 10
_const(TEXTURE_WRAP_R)
Sets the wrap parameter for texture coordinate $r$ to either
_const(CLAMP), _const(CLAMP_TO_EDGE), or _const(REPEAT).
See the discussion under _const(TEXTURE_WRAP_S). 
Initially, _const(TEXTURE_WRAP_R) is set to _const(REPEAT).
.TP
_const(TEXTURE_BORDER_COLOR)
Sets a border color.
_param3 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
_const(TEXTURE_PRIORITY)
Specifies the texture residence priority of the currently bound texture.
Permissible values are in the range [0,\ 1].
See _cmnd(PrioritizeTextures) and _cmnd(BindTexture) for more information.
.SH NOTES
_const(TEXTURE_3D), _const(TEXTURE_MIN_LOD), _const(TEXTURE_MAX_LOD),
_const(TEXTURE_BASE_LEVEL), and _const(TEXTURE_MAX_LEVEL) are only
available if the GL version is 1.2 or greater.
.P
Suppose that a program has enabled texturing
(by calling _cmnd(Enable)
with argument _const(TEXTURE_1D), _const(TEXTURE_2D), or _const(TEXTURE_3D))
and has set _const(TEXTURE_MIN_FILTER) to one of the functions
that requires a mipmap.
If either the dimensions of the texture images currently defined
(with previous calls to _cmnd(TexImage1D), _cmnd(TexImage2D), 
_cmnd(TexImage3D),
_cmnd(CopyTexImage1D), or _cmnd(CopyTexImage2D)) 
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 _arbstring(multitexture) extension is supported, _cmnd
specifies the texture parameters for the active texture unit, specified
by calling _cmnd(ActiveTextureARB).
.SH ERRORS
_const(INVALID_ENUM) is generated if _param1 or _param2 is not
one of the accepted defined values.
.P
_const(INVALID_ENUM) is generated if _param3 should have a defined
constant value (based on the value of _param2) and does not.
.P
_const(INVALID_OPERATION) is generated if _cmnd
is executed between the execution of _cmnd(Begin)
and the corresponding execution of _cmnd(End).
.SH ASSOCIATED GETS
_cmnd(GetTexParameter)
.br
_cmnd(GetTexLevelParameter)
.SH SEE ALSO
_cmnd(ActiveTextureARB),
_cmnd(BindTexture),
_cmnd(CopyPixels),
_cmnd(CopyTexImage1D),
_cmnd(CopyTexImage2D),
_cmnd(CopyTexSubImage1D),
_cmnd(CopyTexSubImage2D),
_cmnd(CopyTexSubImage3D),
_cmnd(DrawPixels),
_cmnd(PixelStore),
_cmnd(PixelTransfer),
_cmnd(PrioritizeTextures),
_cmnd(TexEnv),
_cmnd(TexGen),
_cmnd(TexImage1D),
_cmnd(TexImage2D),
_cmnd(TexImage3D),
_cmnd(TexSubImage1D),
_cmnd(TexSubImage2D),
_cmnd(TexSubImage3D)