.TH gDPLoadTexture 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gDPLoadTexture,
gDPLoadTextureBlock, gsDPLoadTextureBlock,
gDPLoadTextureBlock_4b, gsDPLoadTextureBlock_4b,
gDPLoadTextureTile, gsDPLoadTextureTile,
gDPLoadTextureTile_4b, gsDPLoadTextureTile_4b,
gDPLoadBlock, gsDPLoadBlock
\- load a contiguous texture block or a subtile of a larger texture image into the RDP texture memory.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gDPLoadTextureBlock(Gfx *gdl,
			unsigned int	timg,
			unsigned int	fmt, 
			unsigned int	siz,
			unsigned int	width, height,
			unsigned int	pal,
			unsigned int	cms, cmt,
			unsigned int	masks, maskt,
			unsigned int	shifts, shiftt )

gDPLoadTextureBlock_4b(Gfx *gdl,
			unsigned int	timg,
			unsigned int	fmt, 
			unsigned int	width, height,
			unsigned int	pal,
			unsigned int	cms, cmt,
			unsigned int	masks, maskt,
			unsigned int	shifts, shiftt )

gDPLoadTextureTile(Gfx *gdl,
			unsigned int	timg,
			unsigned int	fmt, 
			unsigned int	siz,
			unsigned int	width, height,
			unsigned int	uls, ult, lrs, lrt,
			unsigned int	pal,
			unsigned int	cms, cmt,
			unsigned int	masks, maskt,
			unsigned int	shifts, shiftt )

gDPLoadTextureTile_4b(Gfx *gdl,
			unsigned int	timg,
			unsigned int	fmt, 
			unsigned int	width, height,
			unsigned int	uls, ult, lrs, lrt,
			unsigned int	pal,
			unsigned int	cms, cmt,
			unsigned int	masks, maskt,
			unsigned int	shifts, shiftt )

gDPLoadBlock(Gfx *gdl,
		unsigned int	tile,
		unsigned int	uls,
		unsigned int	ult,
		unsigned int	lrs,
		unsigned int	dxt)

\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I timg
Location of the texture image in dram.
Must be 64 bit aligned.
.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 width, height
Texture image width and height in texels.
When loading a texture tile, specify the width and height of the original larger texture image in dram.
.TP
.I uls, ult, lrs, lrt
Upper left s and t, lower right s and t coordinates of a texture tile in the source image.
.TP
.I pal
For indexed textures, indicate which texture lookup table palette to use.
.TP
.I cms, cmt
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 masks, maskt
Mask for s and t axis.
\f3G_TX_NOMASK\fP or a number specifing where to wrap.
.TP
.I shifts, shiftt
Shift value for s and t coordinates.
For lower level of detail textures.
If no shifts, use \fBG_TX_NOLOD\fP.
.TP
.I tile
the tile number for
.B g*DPLoadBlock().
.TP
.I dxt
the 
.B t
increment value, per scanline for
.B g*DPLoadBlock().

.SH DESCRIPTION
These commands load texture from dram to on chip texture memory (TMEM) in the RDP.
gDPLoadBlock* commands load a texture image contiguous in memory.
This is the most efficient loading mechanism.
DRAM transfers are most efficient in large blocks.
gDPLoadTile* commands load a subtile of a larger texture image from memory.
.PP
If you are counting gbi display list size to understand memory requirements.
Each of these commands is actually made up of several gbi 64 commands.
.PP
There are many texture image formats. The best choice depends upon the desired
compression and on the content of the texture image.
4/8/16/32 bit texel sizes are supported.
Indexed, 1/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
When loading 4-bit textures, regardless of the type, use the macros 
that have the suffix 
.B _4b.
When using these macros, the size is implied and
is not included in the parameter list.  4-bit textures should be aligned
on byte boundaries.
.PP
The width and height are in texel space,
indicating the size of the source texture image in dram.
.PP
The upper left and lower right (s,t) coordinates are only used for tiled texture loads.
They specify in texel space the corners of the subtile to load into TMEM.
.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 texture properties.
Mirrored textures are useful on axial aligned textures like a tree.
Clamped textures replicates the edge texel color when sampling outside of the texture map.
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 texel coordinate are used to sample the textures.
If you have a 32x32 texture and want to wrap at the edge, use 5 for masks and maskt.
.PP
The shift values are used to shift s or t texel coordinates left or right.
This enables the proper sampling of lower LOD maps and detail textures.
There are many other steps necessary in making a mipmaped textures.
Therefore, the shift values are often not used in these commands.
.PP
There are alternative forms of the gDPLoadTextureBlock macros
to support the full range of possible widths and heights.
These forms end in "S" to indicate that the texture has
been pre-swapped (that is, odd lines of textures have been
word swapped).  See rgb2c(1) for more info on the "-S" flag.
.PP
When loading a texture tile, the addresses of the four corner pixels of the tile only need to be byte aligned.
However, if the row width of the tile is not 64 bit aligned, the hardware will automatically pad to 64 bit alignment on the right of each row in the RDP onchip texture memory (this is only true for LoadTextureTile commands).
.PP
.B gDPLoadBlock()
and
.B gsDPLoadBlock()
are low-level macros which should not normally be used in programs.
They load TMEM in a single transfer, but have some restrictions.
The maximum number of texels that can be loaded using this command is
2048. In order to load all 4K of TMEM, you might need to load the texture
as G_IM_SIZ_16b, then change the tile to the proper texel size after the
load. The
.B g*DPLoadTextureBlock()
macros already do this, but if you use this low-level macro directly,
you will need to handle the tile manipulation yourself.
.PP
LoadBlock commands do not do any padding for you. You must pad the
data before doing the load block.
.PP
Additional texture macros are defined in gbi.h; examine that file for details.
.SH BUGS
Also see Appendix A of the Texture Mapping chapter in the
Developers Document for a list of restrictions on gDPLoadTextureBlock
that can be worked around by using the "S" form of these macros.
.SH SEE ALSO
.IR gDPLoadTLUT (3P)
.IR guLoadTextureBlockMipMap (3P)
.IR rgb2c (1)