gDPSetTile [Macro]

Function

gDPSetTile [Macro]

Sets tile descriptor parameters

Syntax

#include <ultra64.h>        /* gbi.h */
gDPSetTile(
        Gfx *gdl,
        u32 fmt,
        u32 siz,
        u32 line,
        u32 tmem,
        u32 tile,
        u32 palette,
        u32 cmt,
        u32 maskt,
        u32 shiftt,
        u32 cms,
        u32 masks,
        u32 shifts )
gsDPSetTile(
        u32 fmt,
        u32 siz,
        u32 line,
        u32 tmem,
        u32 tile,
        u32 palette,
        u32 cmt,
        u32 maskt,
        u32 shiftt,
        u32 cms,
        u32 masks,
        u32 shifts )

Arguments

gdl

Display list pointer

fmt

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

Pixel component size:

G_IM_SIZ_4b (4 bits/texel)

G_IM_SIZ_8b (8 bits/texel)

G_IM_SIZ_16b (16 bits/texel)

G_IM_SIZ_32b (32 bits/texel)

 

line

The size of one row (s axis) of the texture tile (9-bit precision, 0~511)

 

tmem

Address of texture tile origin (9-bit precision, 0~511)

 

tile

Index of tile descriptors for which parameters are being set (3-bit precision, 0~7)

 

palette

Position of palette for 4-bit color index texture (4-bit precision, 0~15)

 

cmt

t-axis 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)

 

maskt

t-axis mask (4-bit precision, 0~15)

G_TX_NOMASK (do not mask, 0)

numeric value n (mask, 1~15)

 

shiftt

t-coordinate shift value (for low-level detail texture, 4-bit precision, 0~15)

G_TX_NOLOD (do not shift, 0)

numeric value n (shift, 1~15)

 

cms

s-axis 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

s-axis mask (4-bit precision, 0~15)

G_TX_NOMASK (do not mask, 0)

numeric value n (mask, 1~15)

 

shifts

t-coordinate shift value (for low-level detail texture, 4-bit precision, 0~15)

G_TX_NOLOD (do not shift, 0)

numeric value n (shift, 1~15)

Description

Sets texture tile information. This function is used in multi-tile texture modes such as MIP-mapping, detail and sharpen. Think of the 8 tile descriptors as TMEM addresses describing each texture tile. Multiple tile descriptors can specify the same texture tile in TMEM. Each tile descriptor has a sequence of parameters which together describe the texture memory region.

To set a multi-tile mode, load a number of texture tiles by using any gDPLoadTexture* macro. Each texture tile is described by a tile descriptor which indicates the location in TMEM with its parameters (arguments). For example, a texture tile MIP-map pyramid is loaded by using the gDPLoadTextureBlock* macro or several gDPLoadTextureTile* macros. The minimum descriptor number, which indicates the highest level (largest map), and the maximum descriptor number, which indicates the lowest level (smallest map), are described by consecutive tile descriptors. The indexing of these tiles is controlled by the cycle type (see gDPSetCycleType), the maximum number of primitive tiles and MIP-map levels (see gSPTexture), the detail mode (see gDPSetTextureDetail), and whether LOD is on or off (see gDPSetTextureLOD). (For information about primitive tiles, see Section 13.7.2 "LOD Disabled" in the N64 Programming Manual.

To perform MIP mapping, the RDP must be in 2-cycle mode with LOD enabled. The index within a texture tile is based on the texel/pixel ratio calculated by the RDP for each pixel. Filtering into a MIP-map level is controlled by gDPSetTextureFilter. Interpolation between two MIP-map levels is controlled by setting the color combiner (CC) to the appropriate mode (see gDPSetCombineMode). In detail texture mode, the texture tile used to add detail in accordance with the magnification is specified with a primitive tile. The degree to which the detail texture is blended with the original texture is controlled by the LOD limit parameter set by gDPSetPrimColor (see gDPSet*Color).

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 10 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.

Regarding the tmem argument

Indicates the tile offset position.

Regarding the palette argument

This 8-bit index, which specifies an address in the high-half of TMEM, is comprised of the 4MSB (high-order 4-bit) palette position and the 4LSB (low-order 4-bit) color index.

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⁵ X 2⁵). Set to 0 to perform clamping.

Regarding the shifts and shiftt arguments

G_TX_NOLOD(0)

No shifting is performed.

numeric value n (1~15)

Shifts the s,t texel coordinate by n bits. This enables the sampling of low-level LOD maps and detail textures.

 

The values specified by shifts and shiftt (the shift parameter values) represent the amount by which the s,t coordinates are shifted to the left or to the right. This is used for the MIP-mapping, detail, and sharp mode settings. The values 0~10 are interpreted as right shifts, and the values 11~15 are interpreted as left shifts (see the table below). The value 11 corresponds to (<<5), 12 corresponds to (<<4), ..., and 15 corresponds to (<<1).

 

For details about each argument, see Section 13.4 "Tile Attributes" in the N64 Programming Manual. Also, for information about using this macro, see Section 13.5 "Tile Descriptor Loading."

 

About MIP map

When MIP map is used, all textures for each level will altogether be considered one image with the width as the following example says(The minimum value for width will be different for each texture tile, depending upon its pixel component size because TMEM needs to take 64 bit alignment.) and the height 1, and gDPLoadTextureBlock or gDPLoadTextureBlock_4b will be used to load.

For example, when MIP map level is 5, the size of a texture of level 5 is 32x32, and the size of pixel component is 16 bits, it would look as shown below.

 

32*32 + 16*16 + 8*8 + 4*4 + 2*4 + 1*4 = 1372

 

 

Set tile to level +1, masks/maskt to the maximum level(5 in this case) - level, and shifts/shiftt to the same values as the level, and use gDPSetTile and gDPSetTileSize to set tiles for each level.

Note

Since each row of the texture tile occupies contiguous TMEM (64-bit) words, the row end is extended to achieve TMEM word alignment. Also note that operation is not currently guaranteed for G_IM_FMT_YUV (YUV format).

Example

  gsDPPipeSync( ),
/* Set detail texture */
  gsDPSetTextureDetail(G_TD_CLAMP),
/* Set to 2 cycle mode */
  gsDPSetCycleType(G_CYC_2CYCLE),
/* Enable LOD texture */
  gsDPSetTextureLOD(G_TL_LOD),
/* Set scale = 0.5, MIP map level 2, primitive tile 0 and texture on */
  gsSPTexture(0x8000, 0x8000, 1, 0, G_ON),
/* Set rendering mode */
  gsDPSetRenderMode(G_RM_PASS, G_RM_AA_ZB_OPA_SURF2),
/* Set color combiner mode */
  gsDPSetCombineMode(G_CC_TRILERP, G_CC_PASS2),
  gsDPSetPrimColor(0, 0, 255, 255, 255, 255),
/* Set texture region (Sets image width 1 and changes it later) */
  gsDPSetTextureImage(G_IM_FMT_RGBA, G_IM_SIZ_16b, 1, RGBA16sand32x32),
/* Set G_TX_LOADTILE as tile to read texture image */
  gsDPSetTile(G_IM_FMT_RGBA, G_IM_SIZ_16b, 0, 0, G_TX_LOADTILE,
              0 , 0 , 5 ,G_TX_NOLOD, 0, 5, G_TX_NOLOD),      
  gsDPLoadSync( ),
/* Load a texture image to tile G_TX_LOADTILE */
  gsDPLoadBlock(G_TX_LOADTILE, 0, 0, 1344, 0),
  gsDPTileSync( ),
/* Set tile 0 */
  gsDPSetTile(G_IM_FMT_RGBA, G_IM_SIZ_16b, 8, 0,
              0, 0, 0, 5, 0, 0, 5, 0),
  gsDPSetTileSize(0, 0, 0,
              (32-1) << G_TEXTURE_IMAGE_FRAC,
              (32-1) << G_TEXTURE_IMAGE_FRAC),
/* Set tile 1 */
  gsDPSetTile(G_IM_FMT_RGBA, G_IM_SIZ_16b, 4, 0,
              1, 0, 0, 4, 1, 0, 4, 1),
  gsDPSetTileSize(1, 0, 0,
              (16-1) << G_TEXTURE_IMAGE_FRAC,
              (16-1) << G_TEXTURE_IMAGE_FRAC),
/* Set tile 2 */
  gsDPSetTile(G_IM_FMT_RGBA, G_IM_SIZ_16b, 2, 0,
              2, 0, 0, 3, 2, 0, 3, 2),
  gsDPSetTileSize(2, 0, 0,
              (8-1) << G_TEXTURE_IMAGE_FRAC,
              (8-1) << G_TEXTURE_IMAGE_FRAC),

See Also

gDPSetBlendColor, gDPSetEnvColor, gDPSetFillColor, gDPSetFogColor, gDPSetPrimColor, gDPSetTextureDetail, gDPSetTextureFilter, gDPSetTextureLOD, gDPSetTextureLUT, gDPSetTexturePersp, and gSPTexture

Revision History

02/01/99 Completely rewritten.
03/31/99 Changed Syntax and Argument sections so the argument order matches the prototype in gbi.h. Also modified the Description and Example.