GXInitTexCacheRegion

C Specification

#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`	when this flag is true, the argument is interpreted according to the 32-bit mipmap format
`tmem_even`	the base pointer in texture memory for even-numbered LODs (see table below) Must be in 2KB multiples.
`size_even`	the size of the even-numbered cache Applicable settings are `GX_TEXCACHE_32K`, `GX_TEXCACHE_128K` or `GX_TEXCACHE_512K`.
`tmem_odd`	the base pointer in texture memory for odd-numbered LODs (see table below) Must be in 2KB multiples.
`size_odd`	the size of the odd-numbered cache Applicable settings are `GX_TEXCACHE_32K`, `GX_TEXCACHE_128K` or `GX_TEXCACHE_512K`.

Return Values

None.

Description

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

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

GXInit generates 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 using GXSetTexRegionCallBack.

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

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

Texture Memory Region Allocation Rules

Texture memory is divided into high and low banks. The first 512 KB is the low bank, the next 512 KB is the high bank. Textures will have their components stored in the banks according to the rules below. Be aware that no component may span the boundary between the two banks. The notation m:n refers to the address (m) and size (n) for a given range of 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 arguments `tmem_odd:size_odd` must be set to `0:GX_TEXCACHE_NONE`.
planar, 32 bit RGB, non-CI	The AR color components use `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 `tmem_odd:size_odd` arguments should be set to `0:GX_TEXCACHE_NONE`
mipmapped, non-32 bit RGB, non-CI	Even 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) and odd (GB) LODs use `tmem_even:`(`size_even` + `size_odd`). Even (GB) and odd (AR) LODs use `tmem_odd:`(`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 GXInvalidateTexRegion function to compute how much of the texture cache to invalidate.

Revision History

03/01/2006 Initial version.