texdef(3G) texdef(3G)
NAME
texdef2d - convert a 2-dimensional image into a texture
texdef3d - convert a 3-dimensional image into a texture
C SPECIFICATION
void texdef2d(long index, long nc,
long width, long height,
unsigned long * image, long np, float *props)
void texdef3d(long index, long nc,
long width, long height, long depth,
unsigned long * image, long np, float *props)
PARAMETERS
index expects the name of the texture function being defined. Index 0
is reserved as a null definition, and cannot be redefined.
nc expects the number of components per image pixel. 1, 2, 3, and
4 component textures and 8-bit and 16-bit components are
supported.
width expects the width of image in pixels.
height expects the height of image in pixels.
depth expects the depth of image in pixels. (texdef3d only).
image expects a long-word-aligned array containing the pixel data.
This texture image is loaded from left to right, bottom to top,
and back to front. The pixels are packed, but each row must
begin on a long word boundary. The end of each row must be
byte-padded if necessary. The Graphics Library Programmer's
Guide shows how to load a texture array.
np expects the number of symbols and floating point values in
props, including the termination symbol TX_NULL. If np is zero,
it is ignored. Operation over network connections is more
efficient when np is correctly specified.
props expects the array of floating point symbols and values that
control definition of the texture function. props must contain
a sequence of symbols, each followed by the appropriate number
of floating point values. The last symbol must be TX_NULL.
DESCRIPTION
Texture coordinates, s,t,r,q may be specified at geometry vertices,
similarly to color, depth, and vertex normals. The texture coordinates
are interpolated from the values specified at the vertices for each
screen pixel touched by the geometry. A texture function maps the
texture coordinates s,t, or s,t,r, corresponding to a screen pixel into
nc values, called texture function outputs, using an image and a set of
properties. The texture function outputs may be translated into an equal
Page 1
texdef(3G) texdef(3G)
or greater number of texture function outputs with a texture look-up
table. The texture function outputs are used by the texture environment
function to modify the screen pixel color.
texdef2d and texdef3d define such a texture function and associate it
with index. texbind selects which texture function definition to use.
The texture environment function is defined by tevdef and selected by
tevbind. The texture lookup table is defined by tlutdef and selected by
tlutbind. The texture coordinates are specified with the t family of
commands.
Multiple image pixels may correspond to one screen pixel, and vice versa.
Sophisticated sample-filtering may be needed to generate texture function
outputs free of distracting visual artifacts. The filters may be
specified with the props array.
Regardless of the size of the image, it is mapped into s,t,r-coordinates
such that its lower-left-back corner is (0,0,0), and its upper-right-
front corner is (1,1,1). The way that s,t,r map onto the image when they
are out of the range 0.0 through 1.0 is specified in the props array.
A useful texture function can be defined by simply passing an image and a
null props array to texdef2d and texdef3d. The options specified in the
props array, however, give control over both texture mapping quality and
performance. The following symbols are accepted in props:
TXFASTDEFINE specifies that the GL should not copy the passed
texture array to another buffer before loading the texture to
texture memory. This token is a synonym for the experimental tokens
TX_NOCOPY and TX_SUBTEXLOAD, and when used with fbsubtexload,
replaces the experimental TX_FRAMEBUFFER_SRC token. The TX_NOCOPY,
TX_SUBTEXLOAD and TX_FRAMEBUFFER_SRC tokens are obsolete.
The advantages of using this token are that 1) texture definition
time is greatly reduced, sometimes by a factor of 10,000, and it
allows the use of subtexload and fbsubtexload to load new texture
data while the texture is bound. This allows dynamic textures. 2)
CPU memory use is also reduced since the user's array is used to
load texture memory directly, the GL does not need to copy the array
to a separate buffer for texture memory loading purposes. 3) The
TX_EXTERNAL_FORMAT, TX_PIXMODE token pair can be used to allow
automatic data conversions and scale and bias on the input texture
array when it is loaded to texture memory.
The disadvantages are that 1) the cost of a texbind in the case that
texture that was not resident in texture memory and thus had to be
loaded is slightly greater, 2) No minification or magnification
filter which requires the generation of a MIPmap may be used. 3) The
token can only be used with textures that are size 2^M x 2^N where
M,N are integers. 4) The token is ignored by texdef3d.
Page 2
texdef(3G) texdef(3G)
The passed array should not be overwritten or freed while the
texture is active because the array may be needed to reload texture
memory if the texture memory is invalidated by the need to load
other textures.
The user may also pass a null array, and later fill all or part of
the texture memory allocated for the texture with the subtexload or
fbsubtexload commands.
TXMINFILTER specifies the sample-filtering function used to
generate the texture function output when multiple image pixels
correspond to one pixel on the screen. This token is followed by a
single symbol that specifies which minification filter to use. For
many Graphics Library implementations, texturing performance is
constrained by the number of samples used by the filter per texture
function output. The classical 2D MIPmap filter needs to access
eight image pixels for each screen pixel. Performance and quality
may be traded by limiting the number of samples used, and the
computations necessary to find the samples.
TXPOINT selects the value of the image pixel nearest to the s,t,r
mapping onto the texture. (2d or 3d)
TXBILINEAR selects the weighted average of the values of the four
image pixels nearest to the s,t mapping onto the texture. (2d
only)
TXBILINEARLEQUAL (or TXBILINEARGEQUAL) selects the four image
pixels nearest to the s,t mapping onto the texture. The value of
the r texture coordinate is compared with each image pixel. If r
is less than (or greater than) the image pixel, the result is
maximum image pixel value. Otherwise it is 0. The four
comparison results are bilinear blended. This feature is useful
for real-time shadow computations. (2d only)
TXTRILINEAR selects the weighted average of the values of the
eight image pixels nearest to the s,t,r mapping onto the texture.
(3d only)
TXBICUBIC uses a smooth weighting of a 4x4 region of image pixels
nearest to the s,t mapping onto the texture. (2d only)
TXMIPMAPPOINT chooses a prefiltered version of the image, based
on the number of image pixels that correspond to one screen pixel,
then selects the value of the pixel that is nearest to the s,t,r
mapping onto that image. (2d or 3d)
TXMIPMAPLINEAR chooses the two prefiltered versions of the image
that have the nearest image pixel to screen pixel size
correspondence, then selects the weighted average of the values of
the pixel in each of these images that is nearest the s,t,r
mapping onto that image. (2d or 3d)
TXMIPMAPBILINEAR chooses a prefiltered version of the image,
based on the number of image pixels that correspond to one screen
pixel, then selects the weighted average of the values of the four
pixels nearest to the s,t mapping onto that image. (2d only)
TXMIPMAPTRILINEAR chooses the two prefiltered versions of the
Page 3
texdef(3G) texdef(3G)
image that have the nearest image pixel to screen pixel size
correspondence, then selects the weighted average of the values of
the four pixels in each of these images that is nearest the s,t
mapping onto that image. The weighted averages from the two levels
are then themselves interpolated. (2d only)
TXMIPMAPQUADLINEAR chooses the two prefiltered versions of the
image that have the nearest image pixel to screen pixel size
correspondence, then selects the weighted average of the values of
the eight pixels in each of these images that is nearest the s,t,r
mapping onto that image. The weighted averages from the two levels
are then themselves interpolated. (3d only)
The default minification filter is TX_MIPMAP_LINEAR or a filter of
equal performance, but better quality. Prefiltered versions of the
image, when required by the minification filter, are computed
automatically by the Graphics Library. The TX_MIPMAP_FILTER_KERNEL
token, described below, specifies the 8x8 (2D) or 8x8x8 (3D) filter
kernel used by the Graphics Library to generate MIPmap levels.
TXMAGFILTER or TXMAGFILTERALPHA or TXMAGFILTERCOLOR specifies
the filter function used to generate the texture function output
when multiple screen pixels correspond to one image pixel. It is
followed by a single symbol that specifies which magnification
filter to use. The sample-filtering function can be specified
seperately for alpha and non-alpha texture function outputs with
TX_MAGFILTER_ALPHA and TX_MAGFILTER_COLOR. One possible use of this
seperation of alpha and color magnification filters is for the case
where non-zero alpha defines a geometry-approximating template such
as a tree outline. The following token sequence TX_MAGFILTER_ALPHA,
TX_SHARPEN, TX_MAGFILTER_COLOR, TX_BILINEAR can be used to keep the
outline of the tree sharp without any color-shift side effects of
the sharpening magnification filter. The magnification filter
symbols are:
TXPOINT selects the value of the image pixel nearest to the s,t,r
mapping onto the texture. (2d or 3d)
TXBILINEAR selects the weighted average of the values of the four
image pixels nearest to the s,t mapping onto the texture. (2d
only)
TXBILINEARLEQUAL (or TXBILINEARGEQUAL) must be used in
conjunction with the same TXMINFILTER. (see TXMINFILTER above)
TXTRILINEAR selects the weighted average of the values of the
eight image pixels nearest to the s,t,r mapping onto the texture.
(3d only)
TXBICUBIC computes a smooth weighted average of a 4x4 region of
image pixels nearest to the s,t mapping onto the texture. (2d
only)
TXSHARPEN attempts to magnify the image without blurring. It may
only be used with mipmapped textures. It computes the weighted
average of the values of the four pixels that are nearest the s,t
mapping onto that image for each of the top two levels of a
Page 4
texdef(3G) texdef(3G)
MIPmap. The two values are then extrapolated rather than
interpolated to get a final texel value. A formulaic description
is
final_texture_function =
(1 + sharpen_scale(LOD)) * bilinearly_interpolated_image_level_0 -
( sharpen_scale(LOD)) * bilinearly_interpolated_image_level_1
where LOD, or Level Of Detail, is a logarithmic function of the
ratio of screen pixel scale to image pixel scale. LOD is 0 when
screen pixel scale equals image pixel scale, positive when screen
pixels are larger, and negative when screen pixels are smaller.
For magnification filters, LOD is negative. The sharpen_scale
function is a positive valued function that may be specified with
the TX_CONTROL_POINT token, described below. Because color
components may be pushed out of range, color shift may be evident
at large magnifications.
TXADDDETAIL may also be used to magnify the image while
maintaining fine detail. However, instead of using a filtered down
version of the image and the image, as with TX_SHARPEN, an
explicitly specified TX_DETAIL image is used. The TX_DETAIL image
is added to the image, scaled as a function of LOD at a rate that
can be specified by the user. A formulaic description of the
operation is
final_texture_function =
bilinearly_interpolated_image +
(bilin_interpolated_detail_image - max_pixel_val*0.5) *
detail_scale(LOD)
The detail_scale(LOD) function is a positive valued function of
LOD. The TX_CONTROL_POINT token, described below, can be used to
control the detail_scale(LOD) function.
TXMODULATEDETAIL is similar to TX_ADD_DETAIL, but modulates the
image with an explicitly specified detail image, rather than
adding the detail image. A formulaic description of the operation
is
final_texture_function =
bilinearly_interpolated_image +
(bilin_interpolated_detail_image - max_pixel_val*0.5) *
bilin_interpolated_image * detail_scale(LOD)
The TX_CONTROL_POINT token, described below, can be used to
control the additive detail magnification function.
Page 5
texdef(3G) texdef(3G)
The default magnification filter is TXBILINEAR for texdef2d and
TXTRILINEAR for texdef3d.
TXWRAP specifies how texture coordinates outside the range 0.0
through 1.0 are handled.
TXREPEAT uses the fractional parts of the texture coordinates.
TXCLAMP clamps the texture coordinates to the range 0.0 through
1.0.
TXSELECT does not render pixels which fall outside the 0.0 to 1.0
texture coordinate range.
The default texture coordinate handling is TXREPEAT.
TXWRAPS is like TX_WRAP, but it specifies behavior only for the s
texture coordinate.
TXWRAPT is like TX_WRAP, but it specifies behavior only for the t
texture coordinate.
TXWRAPR is like TX_WRAP, but it specifies behavior only for the r
texture coordinate.
TXINTERNALFORMAT is a hint used to trade image quality for speed.
It affects the precision used internally in texture function
computations in the Graphics Library. Because the performance of
texture function implementations is typically constrained by image
pixel accesses per screen pixel, the user can specify a smaller
internal image pixel size and often realize performance gain. Most
Graphics Library implementations will default to the smallest image
pixel size that still yields a performance increase. When the
external format is larger than the internal format, the most
significant bits of the external format pixel are used. When the
external format is smaller than the internal format, the most
significant bits of the external format pixel are replicated in the
lower order bits of the internal format. Thus, three 8-bit external
format components with the hexadecimal values AB,FF,00 become the
three 12-bit internal format components with the hexadecimal values
ABA,FFF,000. It is an error to specify an internal format with a
different number of components than in the external format. For
example, an ABGR external texel should not be mapped to a TX_RGB_5
interal texel. There are two exceptions. One component textures may
be used with TX_I_12A_4 and TX_IA_8 internal formats. For
completeness, TX_I_12 and TX_I_8 are defined as synonyms. Three
component textures may be used with TX_RGBA_8 internal formats. For
completeness, TX_RGB_8 is defined as a synonym for TX_RGBA_8.
TXI12A4 specifies that a one or two component texture should be
computed with at least 12 bits for intensity and 4 bits for alpha.
Image pixel size: 16 bits.
Page 6
texdef(3G) texdef(3G)
TXIA8 specifies that a two component texture should be computed
with at least 8 bits for intensity and 8 bits for alpha. Image
pixel size: 16 bits.
TXRGB5 specifies that a 3 component texture should be computed
with at least 5 bits for red and blue and at least 6 bits for
green. Image pixel size: 16 bits.
TXRGBA4 specifies that a 4 component texture should be computed
with at least 4 bits per component. Image pixel size: 16 bits.
TXIA12 specifies that a 2 component texture should be computed
with at least 12 bits per component. Image pixel size: 24 bits;
may be rounded up to 32 bits.
TXRGBA8 specifies that a 3 or 4 component texture should be
computed with at least 8 bits per component. Image pixel size: 32
bits.
TXRGBA12 specifies that a 4 component texture should be computed
with at least 12 bits per component. Image pixel size: 64 bits.
TXRGB12 specifies that a 3 component texture should be computed
with at least 12 bits per component. Image pixel size: 64 bits.
TXI16 specifies that a 1 component texture is used as a shadow
map for real-time shadow computations. Image pixel size: 16 bits.
TXEXTERNALFORMAT tells the Graphic Library what size components
are being used in image.
TXPACK8 specifies that image is composed of 8-bit components.
This is the default.
TXPACK16 specifies that image is composed of 16-bit components.
TXPIXMODE specifies that the input pixel format and type
specifications and scale and bias values specified with pixmode
should be applied to the texture when it is loaded. This can only
be used with textures defined with the TX_FAST_DEFINE token.
TXMIPMAPFILTERKERNEL specifies an 8x8x8 kernel to use as a
separable symmetric filter to generate MIPmap levels. Since it is
separable and symmetric, only one dimension needs to be specified.
The eight floating point values that follow the token specify the
token. The default used for some implementations which do not
correct for perspective distortion is
0.0, 0.0, 0.125, 0.375, 0.375, 0.125, 0.0, 0.0.
The default used for implementations which correct for perspective
distortion is
0.0, -0.03125, 0.05, 0.48125, 0.48125, 0.05, -0.03125, 0.0.
This filter blurs less.
TXCONTROLPOINT is followed by a pair of floating point values, LOD
and scale.
TXCONTROLCLAMP is followed by one value. The pairs of lod and
scale values specify the rate at which the TX_SHARPEN or
TX_ADD_DETAIL or TX_MODULATE_DETAIL magnification filter is applied,
as a function of LOD. If no control points are specified, the
default control points are (0.,0.), (3.,3.), (4.,4.), (6.5, 6.5). If
Page 7
texdef(3G) texdef(3G)
any control points are specified, the default control points are not
used. Only the first 4 control points will have any effect. The
TX_CONTROL_CLAMP token clamps the scale at a maximum value. Its
default is 6.5.
TXDETAIL is followed by five values, J, K, M, N, and scramble. To
be used as a detail texture, that is, bound to the TX_TEXTURE_DETAIL
target rather than the familiar TX_TEXTURE_0 target, and used with a
texture that has TX_ADD_DETAIL or TX_MODULATE_DETAIL as a
magnification filter, this token must appear. A detail texture is
interpreted as a J x K collection of detail subimages which modulate
or add to a M x N block of texture pixels. When a texture is used as
a detail texture, the properties MINFILTER, MAGFILTER,
MAGFILTER_COLOR, MAGFILTER_ALPHA, TX_WRAP, TX_WRAP_S, TX_WRAP_T,
TX_WRAP_R, TX_MIPMAP_FILTER_KERNEL, TX_CONTROL_POINT,
TX_CONTROL_CLAMP, and TX_TILE have no effect.
TXTILE specifies a subregion of an image to be turned into a
texture. It is followed by four floating point coordinates that
specify the x and y coordinates of the lower-left corner of the
subregion, then the x and y coordinates of the upper-right corner of
the subregion. The original texture image continues to be addressed
in the range 0,0 through 1,1. However, the subregion occupies only
a fraction of this space, and pixels that map outside the subregion
are not drawn.
If the image (or the specified subregion) is larger than can be
handled by the hardware, it is reduced to the maximum supported size
automatically (with no indication other than the resulting visual
quality). Because subregions are specified independently, they
should all be the same size (otherwise some may be reduced and
others not).
TX_TILE supports mapping of high-resolution images with multiple
rendering passes. By splitting the texture into multiple pieces,
each piece can be rendered at the maximum supported texture
resolution. For example, to render a scene with 2x texture
resolution, texdef2d is called four times. Each call includes the
entire image, but specifies a different subregion of that image to
be converted into a texture. To divide the image both horizontally
and vertically into quadrants the subregions should be (0,0 .5,.5),
(.5,0 1,.5), (0,.5 .5,1), and (.5,.5 1,1). The scene is then drawn
four times, each time calling texbind with the texture id of one of
the four quadrants. In each pass, only the pixels whose texture
coordinates map within that quadrant are drawn. Pixels outside of
this quadrant are effectively clipped.
TXBICUBICFILTER is followed by two values, B and C, that specify
the blurring and ringing quality of the bicubic texture filter used
for TX_MINFILTER and/or TX_MAGFILTER. The detailed usage of these
values is described in Don Mitchell's paper, ``Reconstruction
Filters in Computer Graphics'', on SIGGRAPH'88. The same B and C
Page 8
texdef(3G) texdef(3G)
will be applied to both s and t. If B and C are not specified when
bicubic texture mapping is performed (TX_BICUBIC is used for
TX_MINFILTER and/or TX_MAGFILTER), a default bicubic texture filter
will be used.
SEE ALSO
afunction, scrsubdivide, t, tevbind, tevdef, texbind, texgen, tlutdef,
tlutbind
NOTES
texdef2d is immediate mode only. IRIS-4D G, GT, and GTX models, and the
Personal Iris, do not support texture mapping. texdef2d is ignored by
these machines. texdef3d only accepts images of size 2^j x 2^k x 2^l
where j,k,l are non-negative integers. Non-power of two images are not
accepted. This is different than texdef2d, but consistent with OpenGL.
The Iris Indy, Indigo Entry, and XL support texture mapping except for
lines. Use getgdesc to determine whether texture mapping is supported.
TXMIPMAPTRILINEAR is not supported on the VGX model.
It is acceptable to define a 4-component texture function on an IRIS-4D
VGX, or VGXT, system that does not have alpha bitplanes. However, this
definition will be treated as a 3-component definition by tevdef. Use
getgdesc(GDBITSNORMALPHA) to determine whether alpha bitplanes are
available.
Points, lines, and characters, as well as polygons, are texture mapped.
Filter selection and wrap modes are applicable to lines. Points are
filtered by the magnification filter, assuming a 1-to-1 correspondence
between texture pixel and screen pixel size. Characters use the same
magnification filter, but are mapped assuming that both s and t are zero.
IRIS screen pixels have integer coordinates at their centers. Texture
images, however, have integer coordinates (0 and 1) at their exact edges,
not at the centers of pixels on their edges.
On IRIS-4D VGXT models tiling large images will improve texture quality
only when the individual tiles measure no more than 1/4 the original
image size in either dimension.
On IRIS-4D RealityEngine models the only MIPmap filter used is
TX_MIPMAP_TRILINEAR for 2D and TX_MIPMAP_QUADLINEAR for 3d. All the other
forms of MIPmap filters will default to these filters.
The IRIS-4D G, GT, GTX, VGX, VGXT models, Personal Iris, Iris Indigo, and
Indy do not support texdef3d, TX_BICUBIC, TX_MAGFILTER_COLOR,
TX_MAGFILTER_ALPHA, TX_SHARPEN, TX_ADD_DETAIL, TX_MODULATE_DETAIL,
TX_INTERNAL_FORMAT, TX_EXTERNAL_FORMAT, TX_MIPMAP_FILTER_KERNEL,
TX_CONTROL_POINT, TX_CONTROL_CLAMP, TX_DETAIL, TX_BILINEAR_LEQUAL,
TX_BILINEAR_GEQUAL, TX_BICUBIC_FILTER, or TX_FAST_DEFINE.
Page 9
texdef(3G) texdef(3G)
BUGS
On IRIS-4D RealityEngine models:
- Discrepancies between the number of components in the external
format texel and the internal format texel are not detected.
Mismatched numbers of external and internal components will often
work anyway in the case of non- TX_FAST_DEFINE textures, but will
usually cause undesired results if TX_FAST_DEFINE is used.
- If a 1 component TX_FAST_DEFINE texture is used with a texture
look up table, (tlutdef,tlutbind), TX_INTERNAL_FORMAT, TX_IA_8
should be used rather than the default 1 component format TX_I_12A_4
to get the alpha lookup to perform correctly. The reason for this is
that the hardware considers the I_12A_4 format to be a two component
format and A is used to lookup A in the tlut, rather than using I to
lookup A. The top 4 bits of I can be copied to A in the GL to get
this to work correctly but this affects performance. Since the tlut
is only 8 bits in and not 12, we take the time to copy the I channel
to A for the IA_8 format when the user texture is one component, so
the tlut will function correctly.
- using TX_DETAIL, requires J,K to be 4 and the detail image to be
256x256, forcing the subimage size to be 64x64. Allowable values of
M,N are {4,4} (the default), {8,8}, {16,16}, {32,32}, or {64,64}.
Scramble has no effect.
- If TX_BICUBIC is used for either TX_MINFILTER, or TX_MAGFILTER it
will be used for both TX_MINFILTER and TX_MAGFILTER. This filter
must always be used with an internal format that has at least 12
bits per component.
- 3D textures do not support TX_TILE.
- 3D textures do not support TX_SELECT.
- If TX_MAGFILTER_COLOR and/or TX_MAGFILTER_ALPHA are used, one
filter must be TX_MIPMAP_TRILINEAR and the other must be TX_SHARPEN,
TX_MODULATE_DETAIL or TX_ADD_DETAIL.
- The TX_POINT filter may not produce the exact value of the
texture pixel sampled due to arithmetic approximations.
- The TX_BILINEAR_LEQUAL, TX_BILINEAR_GEQUAL minification and
magnification filters and TX_I_16 format texel are tied together in
the implementation so that they must be used together and in fact
cannot be used with any other minification and magnification filters
and texel formats. Similarly, the texture environment TV_ALPHA (see
tevdef) can be used only with TX_I_16. This combination of features
is used for a real-time shadows effect.
Page 10
texdef(3G) texdef(3G)
On IRIS-4D VGX, and VGXT when using TXTILE, width and height of both the
original image and the specified subregion must be a power of 2.
On IRIS-4D VGX model when using TXTILE, texture coordinate t is always
clamped to the range 0.0 through 1.0 regardless of the value of
TXWRAPT.
On IRIS-4D VGX model when TXWRAPS is set to TXCLAMP, TXWRAPT also be
set to TXCLAMP. Otherwise operation is undefined.
On IRIS-4D VGXT models when using TXTILE, and TXWRAPT, TXWRAPS, or
TXWRAP are set to TXCLAMP, the texture coordinates in the corresponding
dimension must be within the closed range [0,1].
On IRIS-4D RealityEngine models TXTILE and TXSELECT do not work
together.
In the Graphics Library Programmer's Guide (1992) pg. 18-30 eq. 18-1
should read:
M,N = 256/(2^(2+N))
and the TX_DETAIL example that follows should read:
TX_DETAIL,4.,4.,16.,16.,0,
On Infinite Reality and Impact TXTILE , TXSELECT , TXDETAIL, and
TXSHARPEN are not supported. They do not support TXMAGFILTERCOLOR or
TXMAGFILTERALPHA. They do not support TXFASTDEFINE with TXPIXMODE
TXBILINEARLEQUAL, TXBILINEARGEQUAL, and they do not support
TXBICUBIC
Page 11