GXSetTexCoordGen

C Specification

#include <revolution/gx.h>

void GXSetTexCoordGen(
GXTexCoordID   dst_coord,
GXTexGenType   func, 
GXTexGenSrc    src_param,
u32            mtx );

Arguments

Return Values

None.

Description

This function is used to specify how texture coordinates are generated. Output texture coordinates are usually the result of some transform of an input attribute; either for position, normal, or texture coordinates. You can also generate texture coordinates from the output color channel for vertex lighting calculations. This function also supports the embossed style of bump-mapping. In C-language syntax the texture coordinate generation function would look like this:

dst_coord = func(src_param, mtx);

The current vertex descriptor as set by GXSetVtxDesc only describes the data input to the graphics processor. Using GXSetTexCoordGen, you can create new output texture coordinates from the input data. The dst_coord argument is used to give the output texture coordinate a name. This texture coordinate can be bound to a texture using GXSetTevOrder. The function GXSetNumTexGens specifies a consecutive number of texture coordinates, starting at GX_TEXCOORD0, that are available to the GXSetTevOrder function. 

Input texture coordinates must always go through the texture-coordinate generation hardware. GXInit initializes the hardware (by calling this function) so that all texture coordinates are transformed by the GX_IDENTITY matrix in order to appear as if input coordinates are passed unchanged through to the texture hardware.

There are eight output texture coordinates that can be referenced in any of the 16 Texture Environment (TEV) stages. There are a maximum of eight input texture coordinates.

The GXTexMtx enumeration defines a default set of texture matrix names that can be supplied as mtx. The matrix names are actually row addresses (four floating point digits per row) in the matrix memory that indicate the first row of a loaded matrix. Another memory map of matrix memory may be defined to suit user needs. Be aware, however, that modelview (see GXLoadPosMtxImm and GXPosNrmMtx) and texture matrices share matrix memory.

Generating Texture Coordinates by Transforming an Attribute

The simplest type (GX_TG_MTX2x4 and GX_TG_MTX3x4) of texture-coordinate generation transforms an input attribute (either position, normal, or texture coordinate) and assigns the result to an output-texture coordinate. GX_TG_MTX2x4 performs a 2x4 matrix multiply on the input attribute and generates S and T texture coordinates. GX_TG_MTX3x4 performs a 3x4 matrix multiply on the input attribute and generates S, T, and Q coordinates. S and T are then divided by Q to produce the actual 2D texture coordinates.

Example

// generate texture coord 0 (S/T/Q) from transform of position (x,y,z)
GXSetTexCoordGen(GX_TEXCOORD0, GX_TG_MTX3x4, GX_TG_POS, GX_TEXMTX0);

// generate tex coord 2 (S/T) from transform of position (x,y,z)
GXSetTexCoordGen(GX_TEXCOORD2, GX_TG_MTX2x4, GX_TG_POS, GX_TEXMTX5);

// generate tex coord 0 and tex coord 1 (S/T) from input coord 0
GXSetTexCoordGen(GX_TEXCOORD0, GX_TG_MTX2x4, GX_TG_TEX0, GX_IDENTITY);
GXSetTexCoordGen(GX_TEXCOORD1, GX_TG_MTX2x4, GX_TG_TEX0, GX_IDENTITY);

// generate tex coord 3 (S/T/Q) from transform of the normal
GXSetTexCoordGen(GX_TEXCOORD3, GX_TG_MTX3x4, GX_TG_NRM, GX_TEXMTX2);

// generate tex coord 0 (S/T) from translation/rotation of input coord 0
GXSetTexCoordGen(GX_TEXCOORD0, GX_TG_MTX2x4, GX_TG_TEX0, GX_TEXMTX1);

Generating Texture Coordinates from Vertex Lighting Results

This type of texture coordinate generation can be used to create cartoon lighting effects. One of the color channel results is converted into texture coordinates.

GX_TG_SRTG

The S coordinate is set equal to the 8-bit R (red) component of the channel. The T coordinate is set equal to the 8-bit G (green) component of the color channel. For cartoon lighting, the S coordinate will represent the light intensity and is input to an arbitrary 1D texture look-up to convert intensity to color. The T coordinate is used to represent material color, and is used to select a 1D table from a 2D texture. Texture coordinates generated using the GX_TG_SRTG function should be generated after any coordinates. (See the Functional Ordering Requirements section below.)

The texture which represents the array of 1D intensity-to-color tables must be constructed carefully. Each table (row) should be duplicated. Since the S and T coordinates are generated from 8-bit colors, a maximum texture of 256 x 256 can be used. For this texture size, there are 127 tables available. This is equal to ((256-1)/2).

The rule for generating the G channel color which will create a T coordinate centered properly in the two-row table is:

n = 1-D intensity lookup table index (0-126 for a 256x256 texture)
rows = number of rows in the texture, multiple of 2
if ((2*n +1) < ((rows-1)/2))
    green = 2*n + 1
else
    green = 2*n

Example

// convert color0 to s,t for 2-D texture lookup, matrix not used
GXSetTexCoodGen(GX_TEXCOORD2, GX_TG_SRTG, GX_TG_COLOR0, GX_IDENTITY);

Embossed-style Bump-mapping

This type (GX_TG_BUMP0-7) of bump-mapping perturbs input texture coordinates based on normal and light direction information. Use the original and offset texture coordinates to look up texels from the height field bump map. You can subtract these values in the TEV to find the bump height, and then add this value to the final color of the pixel. In bump map calculations, GX_BUMP0 indicates that light 0 will be used, GX_BUMP1 indicates that light 1 will be used, etc.

The src_param for bump maps is a texture coordinate whose number is smaller than the target texture coordinate. For example; source texture coordinate = GX_TEXCOORD0, and bump offset texture coordinate = GX_TEXCOORD1. Since the source coordinate should be one of transformed texture coordinates (GX_TG_MTX2x4 or GX_TG_MTX3x4), you can't use a bump map texture coordinate as source for another bump map texture coordinate. Bump map texture coordinates should be generated after coordinates generated from transforms (GX_TG_MTX2x4 and GX_TG_MTX3x4). For more details, see the Functional Ordering Requirements section below.

Example

// source for a bump mapped coordinate, transformed by a matrix
GXSetTexCoordGen(GX_TEXCOORD0, GX_TG_MTX2x4, GX_TG_TEX0, GX_TEXMTX3);
// perturbed coordinate, offset from TEXCOORD0 above,
// light 0. Matrix is not used.
GXSetTexCoordGen(GX_TEXCOORD1, GX_TG_BUMP0, GX_TG_TEXCOORD0, GX_IDENTITY);

Functional Ordering Requirements

Texture coordinates must be generated in functional order: All transforms are first (GX_TG_MTX2x4 or GX_TG_MTX3x4), followed by bump maps (GX_TG_BUMP0-7), followed by texture coordinate generation from lighting (GX_TG_SRTG).

Texture coordinates must be generated using sequential texture coordinate numbers starting at GX_TEXCOORD0.

The number of bump map texture coordinates should be equal to or less than three.

Texture coordinate generation from lighting (GX_TG_SRTG) is slightly complicated in its ordering restrictions:

• Texture coordinates which use GX_TG_COLOR0 should come first, followed by those with GX_TG_COLOR1.
• Texture coordinates using only GX_TG_COLOR1 cannot be used. Coordinates using GX_TG_COLOR0 should be included.
• You can't use the same source (either for GX_TG_COLOR0 or GX_TG_COLOR1) for more than one texture coordinate.

Indexed Texture Matrices

When generating texture coordinates using GX_MTX3x4 or GX_MTX2x4, you may provide the matrix index per vertex, rather than using GXSetTexCoordGen. This feature is most often used with skinned (stitching) models. When the matrix index is provided per vertex, as indicated by the current vertex descriptor, the value specified by GXSetTexCoordGen is overwritten. In other words, GXSetTexCoordGen sets a current matrix index that will be replaced by the per-vertex index.

See Also

GXSetNumTexGens
GXSetTexCoordGen2
GXSetVtxDesc
GXSetTevOrder

Revision History

03/01/2006 Initial version.