GXInitTexObjCI

Syntax

#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. Maximum value is 1024. Mipmaps must be a power of two. If GX_REPEAT or 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. Maximum value is 1024. Mipmaps must be a power of two. If GX_REPEAT or GX_MIRROR is set for wrap_t, the height 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 the 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 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 bilinear-interpolated. See the GXInitTexObjLOD function 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.

The width and height of non-mipmapped, 2D textures do not need to be a power of two. However, the dimension involved must be a power of two in order to use the GX_REPEAT or GX_MIRROR modes for wrap_s or wrap_t.

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

The default texture pipeline as configured by the GXInit function 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:

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.

See Also

GXLoadTexObj, GXLoadTlut, GXInitTexCacheRegion, GXSetTexRegionCallBack, GXTexObj Initialization Flow

Revision History

2008/05/23 Touched up the text.
2006/03/01 Initial version.

CONFIDENTIAL