guLoadTextureBlockMipMap

guLoadTextureBlockMipMap [Function]

Function

guLoadTextureBlockMipMap

Creates MIP map texture and display list

Syntax

#include <ultra64.h>        /* gu.h */
int guLoadTextureBlockMipMap(
        Gfx           **glist,
        unsigned char *tbuf,
        Image         *im, 
        unsigned char startTile,
        unsigned char pal,
        unsigned char cms,
        unsigned char cmt,
        unsigned char masks,
        unsigned char maskt, 
        unsigned char shifts,
        unsigned char shiftt,
        unsigned char cfs,
        unsigned char cft);

Arguments

glist: Address of pointer of resulting display list (the pointer is incremented to point to end of display list)
tbuf: RSP segment address of buffer holding the MIP-map tiles. Make sure it is no bigger than TMEM - tbuf is an RSP segment address
im: Pointer to the Image structure containing the source image information
startTile: Tile descriptor index (0 ~ 7)
pal: Location of color index texture palette (0 ~ 15)
cms: s-axis mirror and wrap flags; G_TX_MIRROR (Enable mirror operations); G_TX_NOMIRROR (Disable mirror operations); G_TX_WRAP (Enable wrap operations)
cmt: t-axis mirror and wrap flags; G_TX_MIRROR (Enable mirror operations); G_TX_NOMIRROR (Disable mirror operations); G_TX_WRAP (Enable wrap operations)
masks: s-axis masks (0 ~ 15); G_TX_NOMASK (Do not mask, 0); Numeric value n (Mask, 1 ~ 15)
maskt: t-axis masks (0 ~ 15); G_TX_NOMASK (Do not mask, 0); Numeric value n (Mask, 1 ~ 15)
shifts: s-coordinate shift value (for lower level of detail textures, 0 ~ 15); G_TX_NOLOD (Do not shift, 0); Numerical value n (Shift, 1 ~ 15)
shiftt: t-coordinate shift value (for lower level of detail textures, 0 ~ 15); G_TX_NOLOD (Do not shift, 0); Numerical value n (Shift, 1 ~ 15)
cfs: s-axis clamp flag; G_TX_CLAMP (Enable clamp operations)
cft: t-axis clamp flag; G_TX_CLAMP (Enable clamp operations)

Returned Value

Termination flag

0	Done	Normal termination.
1	Size Error	MIP map too big for loading in texture memory (TMEM). When not a fatal error, only the part that can be stored in the space is loaded.
2	Format Error	The texel format is not supported. (All N64 texel formats are supported except RGBA32 and YUV)

Description

This function calculates a MIP map pyramid from the source texture array, and returns to glist the display list that is needed for loading and rendering of the MIP map texture. Texture images are extracted from system memory and the MIP map pyramid is created in tbuf. Each level of the pyramid is created from the previous level by filtering using a box filter. The display list for loading the tiles and setting the tile parameters is inserted into the display list specified by glist.

Concerning the glist argument:

After the function is terminated, the pointer is incremented to the end of the inserted display list.

Concerning the cfs, cft arguments:

When cfs and cft are set, the part that overhangs the filter kernel picks up the same texels as the edge of the texture. When the arguments are not set, then the kernel overhang wraps to the opposite end of the texture array.

For details about the other arguments, see gDPLoadTextureBlock. For details about MIP maps, see Section 13.7.4 "MIP Mapping" in the N64 Programming Manual.

Note

The MIP map texture must be smaller than the size of TMEM.

The alpha channel is used for trees and other cutout-like textures. Note that the cutout shapes of the MIP map textures used by the alpha channel will change, depending on the LOD. This is especially prone to happen with 1-bit alpha texel formats (i.e., RGBA16, IA4, etc.)

Comment

The Image structure is shown below:

typedef struct {
     unsigned char  *base;
     int            fmt, siz;      // Texture image format, pixel component size
     int            xsize, ysize;  // x,y size of source image 
     int            lsize;         // Line size of source image
     /* Current tile information */
     int            addr;          // Storage buffer offset ( = 0)
     int            w, h;          // Width, height of rectangular section of image (tile)
     int            s, t;          // s,t offset of source image
} Image;

Example

The following is for a 32 x 32 16-bit RGBA source image

im->base = (unsigned char *)&RGBA16grid_32[0];
im->fmt = G_IM_FMT_RGBA;
im->siz = G_IM_SIZ_16b;
/* source image 'x' size */
im->xsize= 32;  
/* source image 'y' size */
im->ysize= 32;  
/* size of a source image row */
im->lsize= 32* sizeof(unsigned short);   
/* offset into storage buffer. Must be zero */
im->addr = 0; 
/* width of rectangular section of image(tile) to be extracted for MIP mapping Extract for MIP mapping */
im->w = 32;
/* height of rectangular section of image to be extracted for MIP mapping */
im->h = 32;
/* 's' and 't' offsets into source image to */
im->s = 0;
/* Define rectangular tile */
im->t = 0;

Revision History

03/01/99 Completely rewritten