GXInitTexObjCI

C Specification

#include <revolution/gx.h>

void GXInitTexObjCI(
    GXTexObj*      obj,
    void*          image_ptr,
    u16            width,
    u16            height,
    GXCITexFmt     format,
    GXTexWrapMode  wrap_s,
    GXTexWrapMode  wrap_t,
    GXBool         mipmap,
    u32            tlut_name);

Arguments

obj pointer to a texture object

image_ptr pointer to the image data for a texture
32-byte aligned

width width of the texture or LOD 0 for mipmaps
The maximum value is 1024. Mipmaps must be a power of two. If GX_REPEAT/GX_MIRROR is set for wrap_s, the width must be a power of two.

height height of the texture or LOD 0 for mipmaps
The maximum value is 1024. Mipmaps must be a power of two. If GX_REPEAT/GX_MIRROR is set for wrap_t, the width must be a power of two.

format

the texel format
Accepted values are:

Name	Texture Format
`GX_TF_C4`	4-bit color index
`GX_TF_C8`	8-bit color index
`GX_TF_C14X2`	14-bit color index

wrap_s

describes how texture coordinates will be wrapped in the s direction
Accepted values are:

Name	Wrap Mode
`GX_CLAMP`	clamping within the bounds of the image
`GX_REPEAT`	simple repeating
`GX_MIRROR`	repeating with mirroring

wrap_t

describes how texture coordinates will be wrapped in the t direction
Accepted values are:

Name	Wrap Mode
`GX_CLAMP`	clamping within the bounds of the image
`GX_REPEAT`	simple repeating
`GX_MIRROR`	repeating with mirroring

mipmap If mipmap = GX_TRUE, this is a mipmap texture. Otherwise, this is a 2D texture.

tlut_name texture lookup table name used for this texture
The default texture setting takes a name found in GXTlut.

Return Values

None.

Description

This function is used to initialize or change texture objects when the texture is in the color index (CI) format. Texture objects are used to describe all parameters associated with a texture, including size, format, wrap modes, filter modes, etc. The application must provide memory for texture objects. Once initialized, a texture object can be associated with one of the eight active IDs using the GXLoadTexObj function.

If the mipmap flag is GX_TRUE, the texture is a mipmap and the texture will be filtered using the GX_LIN_MIP_NEAR filter mode (color index mipmaps cannot use the GX_LIN_MIP_LIN or GX_NEAR_MIP_LIN modes). If the mipmap flag is GX_FALSE, the texture is not a mipmap and the texture will be bilerped. See GXInitTexObjLOD for information on overriding the filter modes and other mipmap controls. Mipmaps have a width and height of powers of two, but mipmaps do not need to be square.

Non-mipmap (planar) textures do not have to be a power of two. However, to use the GX_REPEAT or GX_MIRROR modes for wrap_s and wrap_t the width and height must be powers of two.

tlut_name is used to indicate which texture lookup table (TLUT) to use.

The default texture pipeline as configured by GXInit uses the names in GXTlut. Default settings provide thirty-two 256-entry TLUTs. A default callback function is used to convert these names to texture memory addresses when the TLUT or color index texture object is loaded. To make new TLUTs or allocate TLUTs differently, you must:

Allocate the GXTlutRegions function using GXInitTlutRegion.
Register a callback function to convert the user TLUT name to TLUT addresses in texture memory using the GXSetTLUTRegionCallBack function.

Keep in mind that texture caches, pre-loaded textures and TLUTs share the texture memory. Changes in TLUT allocation should also be accompanied by changes in texture cache and pre-loaded texture allocation.

Revision History

2006/03/01 Initial version.