GXLoadTlut

Syntax

#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 the GXSetTlutRegionCallBack function converts 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. Initialize tlut_obj in advance with the GXInitTlutObj function.

The GXLoadTlut function 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 described by tlut_name.

The GXInit function sets a default callback to convert tlut_names from GXTlut to a pointer to aGXTlutRegion structure. 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.

Note:

Due to a restriction in the GX library, GXLoadTlut must be called before the GXLoadTexObj function that references it.

For this reason, the following two restrictions apply.

1. The GXTexObj structure (texel data) for CI textures must be loaded after the TLUT it uses, as shown in the following code sample.

// Example 1.
GXInitTexObjCI(texObj, ..., GX_TLUT0);
GXInitTlutObj(tlut, ...);
    :
GXLoadTlut(tlut, GX_TLUT0);
 GXLoadTexObj(texObj, ...);

// Example 2.
GXInitTexObjCI(texObj, ..., GX_TLUT0);
GXLoadTlut(tlut, GX_TLUT0);
    :
GXInitTlutObj(tlut, ...);
 GXLoadTexObj(texObj, ...);

2. If the TLUT portion of the CI texture is updated with the GXLoadTlut function, 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 the GXLoadTexObj function won't actually load the entire texture into TMEM, but will only load the settings.

Revision History

2006/09/08 Revised the wording of the Note.
2006/03/01 Initial version.

CONFIDENTIAL