N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential



gDPLoadTexture
and other texture loading macros

Format
#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)
 Arguments
  • gdl is the pointer to the graphics display list
  • timg is the location of the texture image in DRAM. It must be 64-bit aligned
  • fmt is the texture image format (G_IM_FMT_RGBA, G_IM_FMT_YUV, G_IM_FMT_CI, G_IM_FMT_IA, G_IM_FMT_I)
  • siz is the texel size (G_IM_SIZ_4b, G_IM_SIZ_8b, G_IM_SIZ_16b, G_IM_SIZ_32b)
  • width, height specify the texture image width and height in texels. When you load a texture tile, specify the width and height of the original larger texture image in DRAM
  • uls, ult specify the upper-left s and t coordinates of a texture tile in the source image
  • lrs, lrt specify the lower-right s and t coordinates of a texture tile in the source image
  • pal for indexed textures, this specifies which texture lookup table palette to use
  • cms, cmt gives the clamp, wrap, and mirror flag for the s and t axis (G_TX_NOMIRROR, G_TX_WRAP, G_TX_MIRROR, G_TX_CLAMP)
  • masks, maskt specify the mask for the s and t axis (G_TX_NOMASK or a number specifying where to wrap)
  • shifts, shiftt gives the shift value for the s and t coordinates for lower level of detail textures. Use G_TX_NOLOD for no shifts
  • tile is the tile number for gDPLoadBlock.
  • dxt is the t increment value per scanline for gDPLoadBlock
What These Macros Do
These macros load texture images from DRAM to on-chip texture memory (TMEM) in the RDP. The following macros and macros are included:
  • gDPLoadTextureBlock
  • gDPLoadTextureBlock_4b
  • gDPLoadTextureTile,
  • gDPLoadTextureTile_4b
  • gDPLoadBlock
In addition, there are is also a static version for each:
  • gsDPLoadTextureBlock
  • gsDPLoadTextureBlock_4b
  • gsDPLoadTextureTile,
  • gsDPLoadTextureTile_4b
  • gsDPLoadBlock
The following Block macros load a texture image in a contiguous block of memory, which is the most efficient loading mechanism because DRAM transfers are most efficient in large blocks:
  • gDPLoadTextureBlock, gsDPLoadTextureBlock
  • gDPLoadTextureBlock_4b, gsDPLoadTextureBlock_4b
  • gDPLoadBlock, gsDPLoadBlock
The following Tile macros load a subtile of a larger texture image from memory:
  • gDPLoadTextureTile, gsDPLoadTextureTile
  • gDPLoadTextureTile_4b, gsDPLoadTextureTile_4b
If you are counting GBI display list size to understand memory requirements, you need to note that each of these macros is actually made up of several GBI commands. They are macros.

There are many texture image formats. The best choice depends on the desired compression and on the content of the texture image. 4-bit, 8-bit, 16-bit, and 32-bit texel sizes are supported. Indexed 1/2/4 component textures are supported. I is for intensity textures. IA is for intensity-alpha textures. RGBA is for true-color textures. CI is for color-indexed textures.

When loading 4-bit textures, regardless of the type, use the macros that have the suffix _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.

The width and height are in texel space, indicating the size of the source texture image in DRAM.

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.

The cms and cmt set clamp, mirror, and wrap flags for the s and t axes are bit OR'ed together to specify the desired texture properties. Mirrored textures are useful on axial-aligned textures like a tree. Clamped textures replicate the edge texel color when sampling outside of the texture map. Wrapped 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.

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 MIP mapped texture. Therefore, the shift values are often not used in these macros.

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
for more information on the "S" flag.

When loading a texture tile, only the addresses of the four corner pixels of the tile 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 on-chip texture memory. However, this is only true for the LoadTextureTile macros.

The gDPLoadBlock and gsDPLoadBlock are low-level macros that usually should not be used in programs. They load TMEM in a single transfer, but have some restrictions. For example, the maximum number of texels that can be loaded is 2048. T load all 4K of TMEM, you might need to load the texture as G_IM_SIZ_16b, and then change the tile to the proper texel size after the load. The gDPLoadTextureBlock macros already do this, but if you use this low-level macro directly, you will need to handle the tile manipulation yourself.

The LoadBlock macros do not do any padding for you. You must pad the data before doing the load block.

Additional texture macros are defined in the gbi.h header file; examine that file for details.

Caveats
See Appendix A of the Texture Mapping chapter in the N64 Programming Manual for a list of restrictions on the gDPLoadTextureBlock macro that you can easily work around by using the "S" form of these macros.

See Also
gDPLoadTLUT
guLoadTextureBlockMipMap
rgb2c


Nintendo® Confidential

Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility.
Copyright © 1998
Nintendo of America Inc. All rights reserved
Nintendo and N64 are registered trademarks of Nintendo
Last updated March 1998