gSPObjLoadTxtr [macro]

Loads the texture loading parameters.

Syntax

#include <ultra64.h> /* gs2dex.h */
gSPObjLoadTxtr(Gfx *gdl, uObjTxtr *tx)
gsSPObjLoadTxtr(uObjTxtr *tx)

Arguments

• gdl is the pointer to the graphics display list.

• tx is the pointer to the texture load data structure

Explanation
References the texture loading parameters maintained in three different structures and carries out the corresponding loading processes.

Cautions
The three uObjTxtr structures are shown below:

GS_PIX2TMEM(pix, siz)

GS_TB_TSIZE(pix, siz)
GS_TB_TLINE(pix, siz)

typedef struct {
  u32   type;   /* Structure identifier (G_OBJLT_TXTRBLOCK) */
  u64   *image; /* Texture source address in DRAM (8-byte alignment) */
  u16   tmem;   /* TMEM word address where texture will be loaded (8-byte word) */
  u16   tsize;  /* Texture size (specified by GS_TB_TSIZE) */
  u16   tline;  /* Texture line width (specified by GS_TB_TLINE) */
  u16   sid;    /* Status ID (multiple of 4: either 0, 4, 8, or 12) */
  u32   flag;   /* Status flag */
  u32   mask;   /* Status mask */
} uObjTxtrBlock_t;     /* 24 bytes */

GS_TT_TWIDTH(pix, siz)
GS_TT_THEIGHT(pix, siz)

typedef struct {
  u32   type;   /* Structure identifier (G_OBJLT_TXTRTILE) */
  u64   *image; /* Texture source address in DRAM (8-byte alignment) */
  u16   tmem;   /* TMEM word address where texture will be loaded (8-byte word) */
  u16   twidth; /* Texture width (specified by GS_TT_TWIDTH) */
  u16   theight;/* Texture height (specified by GS_TT_THEIGHT) */
  u16   sid;    /* Status ID (multiple of 4: either 0, 4, 8, or 12) */
  u32   flag;   /* Status flag */
  u32   mask;   /* Status mask  */
} uObjTxtrTile_t;      /* 24 bytes */

GS_PAL_HEAD(head)
GS_PAL_NUM(num)

typedef struct {
  u32   type;   /* Structure identifier (G_OBJLT_TLUT) */
  u64   *image; /* Texture source address in DRAM */
  u16   phead;  /* Palette position at start of load (256~511) */
  u16   pnum;   /* Number of palettes to load - 1 */
  u16   zero;   /* Always assign 0 */
  u16   sid;    /* Status ID (multiple of 4: either 0, 4, 8, or 12) */
  u32   flag;   /* Status flag */
  u32   mask;   /* Status mask */
} uObjTxtrTLUT_t;      /* 24 bytes */

typedef union {
  uObjTxtrBlock_t      block;
  uObjTxtrTile_t       tile;
  uObjTxtrTLUT_t       tlut;
  long long int        force_structure_alignment;
} uObjTxtr;

The three structures described above (uObjTxtrBlock_t, uObjTxtrTile_t, and uObjTxtrTLUT_t) have the common elements type, image, sid, flag, and mask.

type

G_OBJLT_TXTRBLOCK (uObjTxtrBlock_t structure)

Loads texture using LoadBlock.

G_OBJLT_TXTRTILE (uObjTxtrTile_t structure)

Loads texture using LoadTile.

G_OBJLT_TLUT (uObjTxtrTLUT_t structure)

Loads a TLUT.

image

Specifies the address of the texture or texture lookup table (TLUT) data in DRAM with 8-byte alignment.

sid, flag, mask

Evaluate so a texture that is already loaded will not be loaded again. If it is determined that the texture that is about to be loaded has already been loaded, that texture is not loaded and processing stops. The load decision method is described later.

The uObjTxtrBlock_t structure has the following elements in addition to the common elements described above:

tmem

Specifies the load destination TMEM address. Normally, this is used as the imageAdrs value in the uObjSprite structure. GS_PIX2TMEM is useful when this value is specified in pixel units.

tsize

Specifies the size of the texture to be loaded. To get this value from the texture size, specify the number of texels to be loaded (= texture width x height) (pix) and the size of one texel (siz) in GS_TB_TSIZE.

tline

Specifies the width of the texture to be loaded. To get this value from the texture width, specify the number of texels in the texture width (pix) and the size of one texel (siz) in GS_TB_TLINE

The uObjTxtrTile_t structure has the following elements in addition to the common elements described above:

tmem

Specifies the load destination TMEM address. Normally, this is used as the imageAdrs value in the uObjSprite structure. GS_PIX2TMEM is useful when this value is specified in pixel units.

twidth

Specifies the width of the texture to be loaded. To get this value from the texture width, specify the texture width (pix) and the size of one texel (siz) in GS_TT_TWIDTH.

theight

Specifies the height of the texture to be loaded. To get this value from the texture height, specify the texture height (pix) and the size of one texel (siz) in GS_TT_THEIGHT.

The uObjTxtrTLUT_t structure has the following elements in addition to the common elements described above:

phead

Specifies the load destination palette position. The palette position is the value obtained by adding 256 to the normal palette ID. Therefore, the value can be set in the range 256~511. Set this value using GS_PAL_HEAD.

pnum

Specifies the numeric value obtained by subtracting 1 from the number of palette colors to be loaded. Use GS_PAL_NUM to set this.

zero

Although this is not used by the uObjTxtrTLUT_t structure, enter 0 for compatibility with other structures.

The macro arguments for changing units are as follows:

pix

When values are specified in pixel units, they are converted to TMEM address units.

siz

Specifies the size of one texel:

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)

head

Specifies the load destination palette position.

num

Specifies the number of palette colors.

Concerning the method used to decide whether to load a texture:

For the RSP to completely handle the process of deciding whether or not a given texture already exists inside TMEM, the RSP must analyze the load destination area each time a texture is loaded. Spending time on this decision process is not efficient. Therefore, the S2DEX microcode does not have the RSP perform any analysis on the texture to be loaded. Instead, data related to the area in which the texture data structure is to be loaded is added in advance, and the loading decision is made by a simple calculation on this data.

For example, a simple loading decision could be made by writing the ID corresponding to the loaded texture in a status area within the RSP when data is loaded in TMEM, and then making a comparison with that ID the next time data is loaded in TMEM. The loading decision process implemented in S2DEX is based on an extension of this concept. By setting the two 32-bit values for flag and mask, the loading decision process can also support the subdivision of TMEM and partial loads.

Four 32-bit variable Status areas have been prepared as the status region in the RSP. The Status region values are all 0 when the microcode is booted. Which Status value to use is determined by sid. The values that sid can take are {0, 4, 8, 12}.

This macro actually uses the following processes to decide whether or not a texture is to be loaded:

• Checks whether (Status[sid] & mask) == flag.
• If the result is true, decide that the texture has already been loaded and end the load process.
• If the result is false, load the texture and update Status[sid] so

     Status[sid] = (Status[sid] & ~mask) | (flag & mask);

The simplest way of using flag is to assign -1 (=0xffffffff) to mask and the address of the texture source data (= image value) to flag. If no other texture data starts at the same address, this operates as a single texture cache. When (flag & ~mask) != 0, the texture will always be loaded since the decision expression is always false .

When TMEM is managed by subdividing it into two parts, the Status[0] bits 31-16 are assigned to the first half of the TMEM area, the bits 15-0 are assigned to the second half, and a serial number is assigned to each texture. The value of sid is always zero.

To give an example, consider that all of texture 3 is loaded by C. If the first half of TMEM is subsequently changed by loading by A, the texture 3 data will still remain in the second half of TMEM. If D now attempts to load only the second half of texture 3, no loading will actually be performed. S2DEX makes use of this status-based processing to make similar decisions for display list branching in gSPSelectDL and gSPSelectBranchDL.

Example
Sample settings for the three structures are shown below:

(1) Loading a RGBA16 texture with LoadBlock
      uObjTxtr objTxtrBlock_RGBA16 = {
        G_OBJLT_TXTRBLOCK,                /* type */
        (u64 *)textureRGBA16,             /* image */
        GS_PIX2TMEM(0,     G_IM_SIZ_16b), /* tmem */
        GS_TB_TSIZE(32*32, G_IM_SIZ_16b), /* tsize */
        GS_TB_TLINE(32,    G_IM_SIZ_16b), /* tline */
        0,                                /* sid */
        (u32)textureRGBA16,               /* flag */
        -1                                /* mask */
      };

(2) Loading a CI4 texture with LoadTile
      uObjTxtr objTxtrTile_CI4 = {
        G_OBJLT_TXTRTILE,                 /* type */
        (u64 *)textureCI4,                /* image */
        GS_PIX2TMEM  (0,    G_IM_SIZ_4b), /* tmem */
        GS_TT_TWIDTH (32,   G_IM_SIZ_4b), /* twidth */
        GS_TT_THEIGHT(32,   G_IM_SIZ_4b), /* theight */
        0,                                /* sid */
        (u32)textureCI4,                  /* flag */
        -1                                /* mask */
      };

(3) Loading a CI4 texture via a TLUT
      uObjTxtr objTLUT_CI4 = {
        G_OBJLT_TLUT,                     /* type */
        (u64 *)textureCI4pal,             /* image */
        GS_PAL_HEAD(0),                   /* phead */
        GS_PAL_NUM(16),                   /* pnum */
        0,                                /* zero */
        0,                                /* sid */
        (u32)textureCI4pal,               /* flag */
        -1                                /* mask */
      };

See Also
gSPObjLoadTxRect
gSPObjLoadTxRectR
gSPObjLoadTxSprite