GXInitTexCacheRegion

Syntax

#include <revolution/gx.h>

void GXInitTexCacheRegion(
    GXTexRegion*      region, 
    GXBool            is_32b_mipmap,
    u32               tmem_even,
    GXTexCacheSize    size_even,
    u32               tmem_odd,
    GXTexCacheSize    size_odd );

Arguments

region Pointer to a GXTexRegion structure
is_32b_mipmap If the flag is TRUE, the argument is interpreted according to 32-bit mipmap format.
tmem_even Base pointer in texture memory for even-numbered LODs (see table below). Must be in multiples of 2KB.
size_even Size of even-numbered cache. Possible settings are GX_TEXCACHE_32K, GX_TEXCACHE_128K and GX_TEXCACHE_512K.
tmem_odd Base pointer in texture memory for odd-numbered LODs (see table below). Must be in multiples of 2KB.
size_odd Size of odd-numbered cache. Possible settings are GX_TEXCACHE_32K, GX_TEXCACHE_128K and GX_TEXCACHE_512K.

Return Values

None.

Description

This function initializes a texture memory (TMEM) region object for the cache. The region is allocated by the application and can be used as a cache. To use pre-loaded textures, the region must be configured using the GXInitTexPreLoadRegion function. An application can create many region objects and some of them can overlap; however, no two overlapping regions can be active at the same time.

The possible sizes of a TMEM cache region are 32, 128 or 512 KB.

The GXInit function creates the default texture regions, so it is not necessary for the application to use this function unless a different Texture Memory configuration is desired. In that case, the application should also define a region allocator using the GXSetTexRegionCallBack function.

When changing the use of a region of TMEM from preloaded to cached, you must first call the GXTexModeSync function to ensure that all preloaded textures are rendered.

The GXInvalidateTexRegion function can be used to force the textures in main memory associated with this region to be reloaded. This will be necessary whenever the texture data in main memory changes. You may invalidate all cached regions at once using the GXInvalidateTexAll function.

Texture Memory Region Allocation Rules

Texture memory is divided into high and low banks. The first 512 Kbytes is the low bank, the next 512 Kbytes is the high bank. Textures will have their components stored in the banks according to the rules below.  Note that no component may span the boundary between two banks. The notation m:n refers to the address (m) and size (n) for a given range of the texture memory. CI is an abbreviation for color-index.

Texture Types Allocation Rules
planar, non-32 bit RGB, non-CI  Uses only tmem_even:size_even.
Can use both banks.
The argument tmem_odd must be set to 0, and size_odd must be set to GX_TEXCACHE_NONE.
planar, 32 bit RGB, non-CI Color element AR uses tmem_even:size_even. Must be in the low bank.
Color element GB uses tmem_odd:size_odd. Must be in the high bank.
planar, color index  Uses only tmem_even:size_even. Must be in the low bank.
(The corresponding TLUT will be accessed from the high bank.)
)
The argument tmem_odd must be set to 0, and size_odd must be set to GX_TEXCACHE_NONE.
mipmapped, non-32 bit RGB, non-CI Even-numbered LODs use tmem_even:size_even. Odd LODs use tmem_odd:size_odd.
Even LODs may be in the high or low bank. Odd LODs must be in the opposite bank.
mipmapped, 32 bit RGB, non-CI  Even (AR) + odd (GB) LODs use tmem_even:(size_even + size_odd).
Even (GB) + odd (AR) LODs use tmem_even:(size_even + size_odd).
Total texture cache memory usage = 2 * (size_even + size_odd).
mipmapped, color index Even-numbered LODs use tmem_even:size_even. Must be in the low bank.
Odd LODs use tmem_odd:size_odd. Must be in the low bank.
Be aware that trilinear filtering will not work for this texture type.

Be aware that mipmapped, 32 bit RGB textures use twice as much texture-cache memory compared to other types. The is_32b_mipmap argument must be set when the texture region will be used in this manner. This argument is used by the GXInvalidateTexRegion function to compute how much of the texture cache to invalidate.

See Also

GXInitTexPreLoadRegion, GXSetTexRegionCallBack, GXInitTlutRegion, GXSetTlutRegionCallBack, GXGetTexRegionAll, GX Default TMEM Configuration

Revision History

2006/03/01 Initial version.

CONFIDENTIAL