gDPLoadTextureBlock [macro]

Loads a texture as a contiguous texture block.

Syntax

#include <ultra64.h> /* gbi.h */
gDPLoadTextureBlock(
        Gfx *gdl, 
        u32 timg, 
        u32 fmt, 
        u32 siz, 
        u32 width, 
        u32 height, 
        u32 pal, 
        u32 cms, 
        u32 cmt, 
        u32 masks, 
        u32 maskt, 
        u32 shifts, 
        u32 shiftt )
gsDPLoadTextureBlock(
        u32 timg,
        u32 fmt, 
        u32 siz, 
        u32 width,
        u32 height, 
        u32 pal, 
        u32 cms,
        u32 cmt, 
        u32 masks,
        u32 maskt, 
        u32 shifts,
        u32 shiftt )

Arguments

• gdl is the display list pointer

• timg is the address of the texture image (64-bit alignment)

• fmt is the texture image format:
  G_IM_FMT_RGBA (RGBA format)
  G_IM_FMT_YUV (YUV format)
  G_IM_FMT_CI (CI format)
  G_IM_FMT_IA (IA format)
  G_IM_FMT_I (I format)

• siz is the pixel component size:
  G_IM_SIZ_8b (8 bits/texel)
  G_IM_SIZ_16b (16 bits/texel)
  G_IM_SIZ_32b (32 bits/texel)

• width is the texture image width

• height is the texture image height

• pal is the location of palette for 4-bit color index texture (4-bit precision, 0-15)

• cms is the s-axis mirror, no-mirror, wrap and clamp flags
  G_TX_MIRROR (enable mirror operations)
  G_TX_NOMIRROR (disable mirror operations)
  G_TX_WRAP (enable wrap operations)
  G_TX_CLAMP (enable clamp operations)

• cmt is the t-axis mirror, no-mirror, wrap and clamp flags
  G_TX_MIRROR (enable mirror operations)
  G_TX_NOMIRROR (disable mirror operations)
  G_TX_WRAP (enable wrap operations)
  G_TX_CLAMP (enable clamp operations)

• masks is the s-axis mask (4-bit precision, 0-15)
  G_TX_NOMASK (do not mask, 0)
  numeric value n (mask, 1-15)

• maskt is the t-axis mask (4-bit precision, 0-15)
  G_TX_NOMASK (do not mask, 0)
  numeric value n (mask, 1-15)

• shifts is the s-coordinate shift value (4-bit precision, 0-15)
  G_TX_NOLOD (do not shift, 0)
  numeric value n (shift, 1-15)

• shiftt is the t-coordinate shift value (4-bit precision, 0-15)
  G_TX_NOLOD (do not shift, 0)
  numeric value n (shift, 1-15)

Explanation
Loads a texture from DRAM into texture memory (TMEM). Because this macro loads the texture image into a contiguous region in memory, it is the most efficient way to load a texture. DRAM transfers are also most efficient with large blocks.

This macro is actually comprised of a number of 64-bit GBI commands. Thus, if you need to find out the exact size of the display list, you need to consider how many GBI commands it is comprised of.

Regarding the fmt argument:

G_IM_FMT_RGBA

Each texel comprises four elements of information: RGB (red, green, blue) and alpha (opacity).

G_IM_FMT_YUV

Each texel comprises a Y (intensity) component and a UV (color difference) component.

G_IM_FMT_CI

Each texel is comprised of index information specifying palette data.

G_IM_FMT_IA

Each texel is comprised of I (intensity) information and alpha information.

G_IM_FMT_I

Each texel is a texture with only I information. Since this is extremely compact, it is useful when only a few colors are being used.

You can choose from among 7 different texture image formats. The table shows the valid combinations of format and size. Select the format that best suits the texture compression method and type.

		G_IM_SIZ_ (Size)
		8b	16b	32b
G_IM_FMT_ (Format)	RGBA		X (5/5/5/1)	X (8/8/8/8)
	YUV		X
	CI	X
	IA	X (4/4)	X (8/8)
	I	X

Regarding the cms and cmt arguments:

Multiple specifications can be made with a bit sum of the following flags:

G_TX_MIRROR

Enables mirroring. Mirror textures can be used for textures with axial symmetry, like a tree. Symmetric textures are an effective way to reduce texture volume.

G_TX_NOMIRROR

Disables mirroring.

G_TX_WRAP

Enables wrapping. A wrapped texture repeats a texel. The wrapping cycle can be specified by a mask.

G_TX_CLAMP

Enables clamping. A clamped texture repeats the edge texel color when sampling outside of the texture map. Clamping is performed at the boundary of the texture tile.

Regarding the masks and maskt arguments:

G_TX_NOMASK (0)

No mask is used.

numeric value n (1-15)

Specifies the wrap position with the value of n. The low-order n bits of the s,t texel coordinates are used for texture sampling.

Texture sampling utilizes the low-order n bits of the s,t texture coordinates. You would set to 5 to wrap a texture with a boundary of 32x32 (2⁵x2⁵). Set to 0 to perform clamping.

Regarding the shifts and shiftt arguments: