.TH gDPSetTile 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gDPSetTile, gsDPSetTile,
gDPSetTileSize, gsDPSetTileSize
\- Set parameters for one of the eight tile descriptors.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gDPSetTile(Gfx *gdl,
			unsigned int	fmt, 
			unsigned int	siz,
			unsigned int	line, 
			unsigned int	tmem, 
			unsigned int	tile, 
			unsigned int	palette, 
			unsigned int	cmt, 
			unsigned int	maskt,
			unsigned int	shiftt,
			unsigned int	cms, 
			unsigned int	masks,
			unsigned int	shifts )

gDPSetTileSize(Gfx *gdl,
			unsigned int	tile, 
			unsigned int	uls, ult, 
			unsigned int	lrs, lrt )
\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I fmt
Texture image format.
\fBG_IM_FMT_RGBA, G_IM_FMT_YUV, G_IM_FMT_CI, G_IM_FMT_IA, G_IM_FMT_I\fP
.TP
.I siz
Texel size.
\fBG_IM_SIZ_4b, G_IM_SIZ_8b, G_IM_SIZ_16b, G_IM_SIZ_32b\fP
.TP
.I line
Size of one row (s axis) of the texture tile in tmem words (64-bits).
.TP
.I tmem
Address (0-511) of the origin of the texture tile in tmem words (64-bits).
.TP
.I tile
Index number (0-7) of the tile descriptor whose parameters are being set.
.TP
.I palette
For 4-bit indexed textures, indicates which texture lookup table palette (0-15) 
to use. An 8-bit index into the high half of tmem is formed by placing the palette
number in the 4 MSBs and the color index in the 4 LSBs.
.TP
.I cmt, cms
Clamp, wrap and mirror flag for s and t axis.
\f3G_TX_NOMIRROR, G_TX_WRAP, G_TX_MIRROR, G_TX_CLAMP\fP
.TP
.I maskt, masks
Mask for s and t texture axis. \f3G_TX_NOMASK\fP or a number specifing a power-of-two boundary to wrap on.
.TP
.I shiftt, shifts
Shift value for s and t coordinates. Both left and right shifts are handled. 
Used for scaling mipmap levels and for setting the scale of the detail texture tile.
.TP
.I uls, ult
Upper left s and t coordinates of the texture tile. Can be used to offset tile. Also used as lower boundary in clamp mode.
.TP
.I lrs, lrt
Lower right s and t coordinates of the texture tile. Used only in clamp mode as 
upper boundary for clamp.
.SH DESCRIPTION
These commands are used for setting up multi-tile texture modes like mip-mapping, 
detail and sharpen. There are 8 tile descriptors, each of which can be thought of 
as a pointer into tmem that describes a texture tile (A rectangular texture in 
tmem). Multiple tile descriptors may point to the same texture tile in tmem. 
Each tile descriptor has a set of parameters that describe the region of texture 
memory it is pointing to.
.PP
To set up a multi-tile mode, n texture tiles are loaded using one of the 
\f2gDPLoadTexture\fP commands. Each texture tile is then described by setting a tile
descriptor to point to the appropriate location in tmem followed by the parameters 
for that tile. A mipmap pyramid of texture tiles for example, might be loaded using
a \f2gDPLoadTextureBlock\fP(3P) or several \f2gDPLoadTextureTiles\fP(3P) and described 
by a
contiguous sequence of tile descriptors with the smallest descriptor number 
pointing to the finest level (largest map) and the largest one pointing to the
coarsest level (smallest map). Indexing into these tiles is controlled by the
cycleType (See \f2gDPSetCycleType\fP(3P)), primTile and maxLevel 
(See \f2gSPTexture\fP(3P)), the Detail mode (See \f2gDPSetTextureDetail\fP(3P)) and 
whether LOD is turned on or not (See \f2gDPSetTextureLOD\fP(3P)).
.PP
For mip-mapping LOD needs to be turned on with the  RDP in two cyle mode. 
Indexing into the texture tiles is then based on the texel/pixel ratio computed 
by the RDP on a per-pixel basis. Filtering within a mipmap level is controlled
by \f2gDPSetTextureFilter\fP(3P). Interpolation between two levels of the mipmap is 
controlled by setting the Color Combiner to the appropriate mode. (See 
\f2gDPSetCombineMode\fP(3P)). For Detail texture mode, primTile points to a texture tile
that is used to provide extra detail under magnification. The extent to which
the detail texture is blended in with the base texture is controlled by the
minimum LOD clamp parameter set thru \f2gDPSetPrimColor\fP(3P) (See \f2gDPSetColor\fP(3P)).
.PP
There are many texture image formats, the choice of which is best depends upon the
image content and the desired compression.
4/8/16/32 bit texel sizes are supported.  Indexed, 
2/4 component textures are supported. I is intensity textures.  IA is intensity 
alpha textures.  RGBA is true color textures.  CI is color indexed textures.
.PP 
Each line (row) of a texture tile occupies sequential tmem words (64-bits). The end
of the line is padded to a tmem word boundary.
.PP
cms and cmt set clamp, mirror, and wrap flags for the s and t axes.  These flags are bit 
ORed together to specify the desired wrap properties.  Mirror mode is
useful for textures with symmetry. Advantage can be taken of symmetry
to reduce texture storage.  Clamp mode replicates the edge texel 
color when sampling outside of the texture map.  Clamping is done at the uls, ult and
lrs, lrt  boundaries. Wraped textures require the proper 
mask be set for wrapping.
A number n in masks or maskt indicates (n) LSBs of the s or t texture coordinate are used to sample the textures. For example to wrap a 32x32 texture about its boundary
use a mask value of 5. A mask value of zero forces clamping.
.PP
The shifts and shiftt parameters are used to shift the incoming texture coordinates
left or right by the appropriate amount. 0-10 are right shifts. 11-15 are 
interpreted as left shifts with 11 corresponding to (<< 5), 12: (<< 4) ... 15: (<< 1).
These are used to setup mip-mapping, detail and sharpen modes. For example, a
mip-map pyramid with 6 levels (32x32 16x16, 8x8, 4x4, 2x2, 1x1) and a detail level 
(32x16 say)
would have each one of these levels loaded in tmem with tile descriptor 1 pointing to the 
32x32, tile descriptor 2 to the 16x16 and so on. The shift parameters would be 0 for tile 1, 1 for tile 2 and so on. If Detail mode is turned on, Tile descriptor 0 (primTile=0) 
might point to the 32x16 detail level with a shift of 15 (-1) in the s and t axes. 
This would map 2x2 detail texels onto one base texel under magnification.
.PP
The setTileSize macro is used to set tile parameters that define the origin and
extent of the texture tile. uls and ult define the s and t texure coordinates of the origin
of the tile and are useful for shifting textures across a polygon face. They also 
define the lower boundary for clamping. lrs and lrt are used only for clamping 
and define the upper boundary.
.SH SEE ALSO
.IR gDPLoadTexture (3p)
.IR gDPSetTextureLUT (3p)
.IR gSPTexture (3p)
.IR gDPSetTextureLOD (3p)
.IR gDPSetTextureFilter (3p)
.IR gDPSetTextureDetail (3p)
.IR gDPSetTexturePersp (3p)
.IR gDPSync (3p)