texdef(3G)texdef(3G)NAME
texdef2d - convert a 2-dimensional image into a texture
texdef3d - convert a 3-dimensional image into a texture
FORTRAN SPECIFICATION
subroutine texdf2(index, nc, width, height, depth, image, np, props)
integer*4 index, nc, width, height
integer*4 image(*)
integer*4 np
real props(np)
subroutine texdf3(index, nc, width, height, depth, image, np, props)
integer*4 index, nc, width, height, depth
integer*4 image(*)
integer*4 np
real props(np)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. (texdf3 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 TXNULL. 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 TXNULL.
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
Page 1
texdef(3G)texdef(3G)
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
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.
texdef and texd3d 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 texdf2 and texdf3. The options specified in the
props array, however, give control over both texture mapping quality and
performance. The following symbols are accepted in props:
TXFSDF 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
Page 2
texdef(3G)texdef(3G)
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.
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.
TXMINF 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.
TXPOIN selects the value of the image pixel nearest to the s,t,r
mapping onto the texture. (2d or 3d)
TXBILI selects the weighted average of the values of the four
image pixels nearest to the s,t mapping onto the texture. (2d
only)
TXBLLE (or TXBLGE) 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)
TXTRIL selects the weighted average of the values of the eight
image pixels nearest to the s,t,r mapping onto the texture. (3d
only)
TXBICU uses a smooth weighting of a 4x4 region of image pixels
nearest to the s,t mapping onto the texture. (2d only)
TXMMP 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)
TXMML 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)
TXMMBL chooses a prefiltered version of the image, based on the
number of image pixels that correspond to one screen pixel, then
Page 3
texdef(3G)texdef(3G)
selects the weighted average of the values of the four pixels
nearest to the s,t mapping onto that image. (2d only)
TXMMTL 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 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)
TXMMQL 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 TXMML 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 TXMIPM token, described below,
specifies the 8x8 (2D) or 8x8x8 (3D) filter kernel used by the
Graphics Library to generate MIPmap levels.
TXMAGF or TXMAFA or TXMAFC 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 TXMAFA and TXMAFC. 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_MAFA, TXSHAR, TXMAFC, TXBILI, 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:
TXPOIN selects the value of the image pixel nearest to the s,t,r
mapping onto the texture. (2d or 3d)
TXBILI selects the weighted average of the values of the four
image pixels nearest to the s,t mapping onto the texture. (2d
only)
TXBLLE (or TXBLGE) must be used in conjunction with the same
TXMINF. (see TXMINF above)
TXTRIL selects the weighted average of the values of the eight
image pixels nearest to the s,t,r mapping onto the texture. (3d
only)
TXBICU computes a smooth weighted average of a 4x4 region of image
pixels nearest to the s,t mapping onto the texture. (2d only)
TXSHAR 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
Page 4
texdef(3G)texdef(3G)
onto that image for each of the top two levels of a 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 TXCPNT token, described below. Because color components may
be pushed out of range, color shift may be evident at large
magnifications.
TXADDD 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.
TXMODU 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 TXBILI for texdef2d and TXTRIL
for texdef3d.
TXWRAP specifies how texture coordinates outside the range 0.0
through 1.0 are handled.
TXREPE uses the fractional parts of the texture coordinates.
TXCLAM clamps the texture coordinates to the range 0.0 through
1.0.
TXSELE does not render pixels which fall outside the 0.0 to 1.0
texture coordinate range.
The default texture coordinate handling is TX_REPE.
TXWRPS is like TXWRAP, but it specifies behavior only for the s
texture coordinate.
TXWRPT is like TXWRAP, but it specifies behavior only for the t
texture coordinate.
TXWRPR is like TXWRAP, but it specifies behavior only for the r
texture coordinate.
TXINTE 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.
TX12A4 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.
TXRGBA 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.
RGBA8 specifies that a 3 or 4 component texture should be computed
with at least 8 bits per component. Image pixel size: 32 bits.
RGBA12 specifies that a 4 component texture should be computed
with at least 12 bits per component. Image pixel size: 64 bits.
TXRGB1 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.
TXEXTE tells the Graphic Library what size components are being used
in image.
TXPK08 specifies that image is composed of 8-bit components. This
is the default.
TXPK16 specifies that image is composed of 16-bit components.
TXPXMD 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.
TXMIPM 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.
TXCPNT is followed by a pair of floating point values, LOD and
scale.
TXCCLP 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 any control points are
specified, the default control points are not used. Only the first 4
Page 7
texdef(3G)texdef(3G)
control points will have any effect. The TX_CONTROL_CLAMP token
clamps the scale at a maximum value. Its default is 6.5.
TXDETA 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).
TXTILE 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, texdef 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 texbin 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.
TXBCF 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
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
Page 8
texdef(3G)texdef(3G)
TX_MINFILTER and/or TX_MAGFILTER), a default bicubic texture filter
will be used.
SEE ALSO
afunct, scrsub, t, tevbin, tevdef, texbin, texgen, tltdef, tltbin
NOTES
texdef is immediate mode only. IRIS-4D G, GT, and GTX models, and the
Personal Iris, do not support texture mapping. texdef is ignored by
these machines. texd3d 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 getgde to determine whether texture mapping is supported.
TXMMTL 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
getgde(GDBNSA) 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, TXBICU, TXMAFC, TXMAFA, TXSHAR, TXADDD,
TXMODU, TXINTE, TXEXTE, TXMIPM, TXCPNT, TXCCLP, TXDETA, TXBLLE, TXBLGE,
or TXBCF.
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
Page 9
texdef(3G)texdef(3G)
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 TXDETA, 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 TXBICU is used for either TXMINF, or TXMAGF 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 TXTILE.
- 3D textures do not support TXSELE.
- If TXMAFC and/or TXMAFA are used, one filter must be TX_MMTL and
the other must be TXSHAR, TXMODU or TXADDD.
- The TX_POINT filter may not produce the exact value of the
texture pixel sampled due to arithmetic approximations.
- The TXBILL, TXBILG minification and magnification filters and
TXI16 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 TVALPH (see tevdef) can be used
only with TXI16. This combination of features is used for a real-
time shadows effect.
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 TXWRPT.
Page 10
texdef(3G)texdef(3G)
On IRIS-4D VGX model when TXWRPS is set to TXCLAM, TXWRPT also be set to
TXCLAM. Otherwise operation is undefined.
On IRIS-4D VGXT models when using TXTILE, and TXWRPT, TXWRPS, or TXWRAP
are set to TXCLAM, the texture coordinates in the corresponding dimension
must be within the closed range [0,1].
On IRIS-4D RealityEngine models TXTILE and TXSELE 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 , TXSELE , TXDETA, and TXSHAR are
not supported. They do not support TXMAFCP or TXMAFAP They do not
support TXFSDF with TXPXMD TXBILL, TXBILG and they do not support TXBICU
Page 11
