gDPLoadTexture

Function

gDPLoadTexture, gDPLoadTextureBlock, gsDPLoadTextureBlock, gDPLoadTextureBlock_4b, gsDPLoadTextureBlock_4b, gDPLoadTextureTile, gsDPLoadTextureTile, gDPLoadTextureTile_4b, gsDPLoadTextureTile_4b, gDPLoadBlock, gsDPLoadBlock

Loads a contiguous texture block or subtitles of a large texture image onto RDP texture memory

Syntax

#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, 
        insigned int uls, 
        insigned int ult, 
        insigned int lrs, 
        insigned int dxt )

Arguments

*gdl: Pointer to graphics display
timg: Position of a texture image in DRAM It must be 64 bit border.
fmt: Texture image format. G_IM_FMT_RGBA, G_IM_FMT_YUV, G_IM_FMT_CI, G_IM_FMT_IA, G_IM_FMT_I
siz: Texel size. G_IM_SIZ_4b, G_IM_SIZ_8b, G_IM_SIZ_16b, G_IM_SIZ_32b
width, height: Width and height of a texture image (texel). Width and height of a (large) original texture image in DRAM needs to be specified to load texture tile.
uls, ult, lrs, lrt: s and t coordinates on the upper left and lower right corner of texture tile in source image.
pal: Indicates which texture look-up table palette the index texture should use.
cms, cmt: s and t-axis clamp, wrap, and mirror flags. G_TX_NOMIRROR, G_TX_WRAP , G_TX_MIRROR, G_TX_CLAMP
masks, maskt: s and t-axis mask. G_TX_NOMASK Value that specifies the wordwrap location.
shifts, shiftt: s and t coordinate shift values. Detailed texture for low-level use. G_TX_NOLOD is used when not shifted.
tile: Tile number for g*DPLoadBlock
dxt: Amount of change of t value per scan line for g*DPLoadBlock

Description

These commands load textures to on-tip texture memory(TMEM) from DRAM. gDPLoadBlock* command loads a contiguous texture image onto memory, which is the most efficient loading mechanism. DRAM transfer would be most efficient when handling large blocks. gDPLoadTile* loads the subtitles of a large texture image from memory.

When calculating the size of GBi display list to obtain conditions of memory, these commands consist of 64-bit commands.

There are several numbers of texture image formats to choose from, depending upon what kind of texture to use, or compression method to use. 4/8/16/32 bits in texel size are supported. For index, 1/2/4 bit component textures are supported. I stands for intensity texture. IA, RGBA, and CI stand for intensity alpha texture, true color texture, and color index texture, respectively.

Macros that have a suffix_b need to be used when loading a texture of 4 bits regardless of the type. The size is not included in the parameter list, hence it is hidden. 4 bit texture must be byte-border aligned.

Width and height refer to the texel space. It indicates the size of source texture image on DRAM.

ul (s,t) and lr (s, t) coordinates are only be used to load tiled textures. In the texel space, these specify the corners of a subtitle that loads in TMEM.

cms and cmt set clamp, mirror, and wrap flags for s and t axis. These flags are bitORed to specify the desired texture property. Mirror texture can used for a symmetrical texture. Clamp texture repeatedly operates texel edge color when sampling the exterior of a texture map. Wrap texture requests mask necessary for wrapping. The number n of masks and maskt indicates low n bits of s and t coordinates used to sample texture. Set 5 to masks and maskt to wrap at the edge when 32x32 texture is used.

Shift values shift the texel coordinates, s and t, to left and right, enabling proper sampling between the low-level LOD map and detail texture. Several steps are necessary to create mip map texture. So, the shift values might not be used in these commands.

Alternative formats to gDPLoadTextureBlock have been provided to support the maximum range for width and height. These formats end with "S" to indicate that the texture will swap in advance. (Therefore, odd lines of the texture will be wordwrapped.) For information on "-S" flag, see rgb2c(1).

The pixel addresses of four corners of a tile must be byte-aligned when loading a texture. However, when line width of a tile is not 64 bit-aligned, hardware will adjust the right side of each line automatically to 64-bit aligned in TMEM. (This is limited to LoadTextureTile command.)

gDPLoadBlock() and gsDPLoadBlock() are low-level macros that the program normally doesn't use. These macros perform one-time transfer to load TMEM, and there are some restrictions. The maximum number of texels that these commands can load is 2048. It is necessary to load a texture of G_IM_SIZ_16b type to load all TMEM of 4K, and the commands calculate the appropriate texel size after loading. g*DPLoadTextureBlock() always does this by itself, however, if you use these low-level macros directly, the application needs to handle the tile operation.

LoadBlock command itself does not do debugging. Data adjustment needed before loading blocks.

The additional texture macros are defined in gbi.h; see gbi.h for details.

Note

For how to use "S" format for these macros, please see the chapter on texture mapping in Appendix A of the N64 Programming Manual.