texdef3d(3G)
texdef2d - convert a 2-dimensional image into a texture texdef3d - convert a 3-dimensional image into a texture
Showing IRIX 6.5.30 (default release). Unchanged since IRIX 6.5.
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 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: TX_FAST_DEFINE 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. 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. TX_MINFILTER 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. TX_POINT selects the value of the image pixel nearest to the s,t,r mapping onto the texture. (2d or 3d) TX_BILINEAR selects the weighted average of the values of the four image pixels nearest to the s,t mapping onto the texture. (2d only) TX_BILINEAR_LEQUAL (or TX_BILINEAR_GEQUAL) 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) TX_TRILINEAR selects the weighted average of the values of the eight image pixels nearest to the s,t,r mapping onto the texture. (3d only) TX_BICUBIC uses a smooth weighting of a 4x4 region of image pixels nearest to the s,t mapping onto the texture. (2d only) TX_MIPMAP_POINT 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) TX_MIPMAP_LINEAR 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) TX_MIPMAP_BILINEAR 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) TX_MIPMAP_TRILINEAR 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) TX_MIPMAP_QUADLINEAR 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. TX_MAGFILTER or TX_MAGFILTER_ALPHA or TX_MAGFILTER_COLOR 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: TX_POINT selects the value of the image pixel nearest to the s,t,r mapping onto the texture. (2d or 3d) TX_BILINEAR selects the weighted average of the values of the four image pixels nearest to the s,t mapping onto the texture. (2d only) TX_BILINEAR_LEQUAL (or TX_BILINEAR_GEQUAL) must be used in conjunction with the same TX_MINFILTER. (see TX_MINFILTER above) TX_TRILINEAR selects the weighted average of the values of the eight image pixels nearest to the s,t,r mapping onto the texture. (3d only) TX_BICUBIC computes a smooth weighted average of a 4x4 region of image pixels nearest to the s,t mapping onto the texture. (2d only) TX_SHARPEN 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 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. TX_ADD_DETAIL 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. TX_MODULATE_DETAIL 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. The default magnification filter is TX_BILINEAR for texdef2d and TX_TRILINEAR for texdef3d. TX_WRAP specifies how texture coordinates outside the range 0.0 through 1.0 are handled. TX_REPEAT uses the fractional parts of the texture coordinates. TX_CLAMP clamps the texture coordinates to the range 0.0 through 1.0. TX_SELECT does not render pixels which fall outside the 0.0 to 1.0 texture coordinate range. The default texture coordinate handling is TX_REPEAT. TX_WRAP_S is like TX_WRAP, but it specifies behavior only for the s texture coordinate. TX_WRAP_T is like TX_WRAP, but it specifies behavior only for the t texture coordinate. TX_WRAP_R is like TX_WRAP, but it specifies behavior only for the r texture coordinate. TX_INTERNAL_FORMAT 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. TX_I_12A_4 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. TX_IA_8 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. TX_RGB_5 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. TX_RGBA_4 specifies that a 4 component texture should be computed with at least 4 bits per component. Image pixel size: 16 bits. TX_IA_12 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. TX_RGBA_8 specifies that a 3 or 4 component texture should be computed with at least 8 bits per component. Image pixel size: 32 bits. TX_RGBA_12 specifies that a 4 component texture should be computed with at least 12 bits per component. Image pixel size: 64 bits. TX_RGB_12 specifies that a 3 component texture should be computed with at least 12 bits per component. Image pixel size: 64 bits. TX_I_16 specifies that a 1 component texture is used as a shadow map for real-time shadow computations. Image pixel size: 16 bits. TX_EXTERNAL_FORMAT tells the Graphic Library what size components are being used in image. TX_PACK_8 specifies that image is composed of 8-bit components. This is the default. TX_PACK_16 specifies that image is composed of 16-bit components. TX_PIXMODE 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. TX_MIPMAP_FILTER_KERNEL 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. TX_CONTROL_POINT is followed by a pair of floating point values, LOD and scale. TX_CONTROL_CLAMP 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 control points will have any effect. The TX_CONTROL_CLAMP token clamps the scale at a maximum value. Its default is 6.5. TX_DETAIL 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. TX_TILE 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. TX_BICUBIC_FILTER 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 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. TX_MIPMAP_TRILINEAR 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(GD_BITS_NORM_ALPHA) 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. 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. On IRIS-4D VGX, and VGXT when using TX_TILE, 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 TX_TILE, texture coordinate t is always clamped to the range 0.0 through 1.0 regardless of the value of TX_WRAP_T. On IRIS-4D VGX model when TX_WRAP_S is set to TX_CLAMP, TX_WRAP_T also be set to TX_CLAMP. Otherwise operation is undefined. On IRIS-4D VGXT models when using TX_TILE, and TX_WRAP_T, TX_WRAP_S, or TX_WRAP are set to TX_CLAMP, the texture coordinates in the corresponding dimension must be within the closed range [0,1]. On IRIS-4D RealityEngine models TX_TILE and TX_SELECT 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 TX_TILE , TX_SELECT , TX_DETAIL, and TX_SHARPEN are not supported. They do not support TX_MAGFILTER_COLOR or TX_MAGFILTER_ALPHA. They do not support TX_FAST_DEFINE with TX_PIXMODE TX_BILINEAR_LEQUAL, TX_BILINEAR_GEQUAL, and they do not support TX_BICUBIC