GXLoadTlut

C Specification

#include <revolution/gx.h>

void GXLoadTlut(
const GXTlutObj*   tlut_obj, 
u32                tlut_name );

Arguments

`tlut_obj`	pointer to a `GXTlutObj` structure The application must allocate the memory for this object.
`tlut_name`	name of the texture memory lookup table

Return Values

None.

Description

This function copies a texture lookup table (TLUT) from main memory to texture memory (TMEM). The tlut_name argument is the name of a pre-allocated region of TMEM. The callback function set by GXSetTlutRegionCallBack converts the tlut_name into a pointer to a GXTlutRegion structure. The TLUT is loaded in the TMEM region described by this pointer. tlut_obj describes the location of the TLUT in main memory, the TLUT format, and the TLUT size. tlut_obj will have been previously initialized with GXInitTlutObj.

GXLoadTlut will make an assertion check to make sure the TLUT size described by tlut_obj is less than or equal to the TLUT region size in TMEM described by tlut_name.

GXInit sets a default callback to convert tlut_names from GXTlut to pointers to GXTlutRegion structures. The default configuration of TMEM has 20 TLUTs, sixteen of which are 16-bit 256 entries, and four of which are 16-bit 1K entries. This configuration can be overwritten by calling the GXInitTlutRegion and GXInitTexCacheRegion functions to allocate TMEM. You can then define your own region allocation scheme using the GXSetTlutRegionCallBack and GXSetTexRegionCallBack functions.

NB:

Due to restrictions in the GX library, when calling fonts, they must always be followed with a call to GXLoadTexObj.

Here are two examples:

1. The GXTexObj structure (texel data) for CI textures must be loaded after the TLUT.

GXInitTexObjCI(texObj, ..., GX_TLUT0); GXInitTlutObj(tlut, ...); : GXLoadTlut(tlut, GX_TLUT0); // GXLoadTexObj(texObj, ...); // Always keep this order.

2. If the TLUT portion of the CI texture is updated with GXLoadTlut, the texel data portion must be reloaded with the GXLoadTexObj structure.

GXInitTexObjCI(texObj, ..., GX_TLUT0); GXInitTlutObj(tlutA, ...); GXInitTlutObj(tlutB, ...); : GXLoadTlut(tlutA, GX_TLUT0); GXLoadTexObj(texObj, ...); : GXLoadTlut(tlutB, GX_TLUT0); // Only TLUT is going to be updated. GXLoadTexObj(texObj, ...); // Must reload texobj.

There is an insignificant performance penalty for the extra GXLoadTexObj call because GXLoadTexObj won't actually load the entire texture into TMEM, but will only load the settings.

Revision History

03/01/2006 Initial version.