GXAttr.h File Reference

#include <platform.h>
#include <dolphin/gx/GXEnum.h>

Go to the source code of this file.

Macros
#define	GXSetTexCoordGen(dst_coord, func, src_param, mtx)

Functions
void	GXSetNumTexGens (u8 num)
	Sets the number of texture coordinates that are generated and available for use in the Texture Environment (TEV) stages.
void	GXSetTexCoordGen2 (GXTexCoordID, GXTexGenType, GXTexGenSrc, u32, GXBool, u32)
void	GXInvalidateVtxCache (void)
	Called by GXInit and invalidates the vertex cache tags.
void	GXSetArray (GXAttr attr, s32 base_ptr, u8 stride)
	Sets the array base pointer and stride for a single attribute.
void	GXSetVtxAttrFmt (size_t vtxfmt, GXAttr attr, enum_t count, GXCompType type, u8 frac)
	Sets the attribute format (attr) for a single attribute in the Vertex Attribute Format Table (VAT).
void	GXClearVtxDesc (void)
	__GXSetVCD
void	GXSetVtxDesc (GXAttr attr, s32 type)
	__GXXfVtxSpecs
void	__GXSetVCD (void)
void	__GXSetVAT (void)
void	__GXXfVtxSpecs (void)

Macro Definition Documentation

GXSetTexCoordGen

#define GXSetTexCoordGen	(		dst_coord,
			func,
			src_param,
			mtx
	)

Value:

    GXSetTexCoordGen2(dst_coord, func, src_param, mtx, GX_DISABLE,            \
                      GX_PTIDENTITY)

Function Documentation

GXSetNumTexGens()

void GXSetNumTexGens

(

u8

num

)

Sets the number of texture coordinates that are generated and available for use in the Texture Environment (TEV) stages.

Texture coordinates are generated from input data as described by GXSetTexCoordGen2. The generated texture coordinates are linked to specific textures and specific Texture Environment (TEV) stages using GXSetTevOrder.

A consecutive number of texture coordinates may be generated, starting at GX_TEXCOORD0. A maximum of 8 texture coordinates may be generated. If num is set to 0, no texture coordinates will be generated. In this case, at least one color channel must be output, see GXSetNumChans.

Parameters

num	Number of texture coordinates to generate. Minimum value is 0, maximum value is 8.

See also

GXSetNumChans

GXSetTexCoordGen2()

void GXSetTexCoordGen2	(	GXTexCoordID	arg0,
		GXTexGenType	arg1,
		GXTexGenSrc	arg2,
		u32	arg3,
		GXBool	arg4,
		u32	arg5
	)

GXInvalidateVtxCache()

void GXInvalidateVtxCache

(

void

)

Called by GXInit and invalidates the vertex cache tags.

This function should be used whenever you relocate or modify data that is read by, or may be cached by, the vertex cache. The invalidate is very fast, taking only two Graphics Processor (GP) clock cycles to complete.

The vertex cache is used to cache indexed attribute data. Any attribute that is set to GX_INDEX8 or GX_INDEX16 in the current vertex descriptor (see GXSetVtxDesc) is indexed. Direct data bypasses the vertex cache. Direct data is any attribute that is set to GX_DIRECT in the current vertex descriptor.

See also

GXInit

GXSetVtxDesc

GXSetArray()

void GXSetArray	(	GXAttr	attr,
		s32	base_ptr,
		u8	stride
	)

Sets the array base pointer and stride for a single attribute.

The array base and stride are used to compute the address of indexed attribute data using the equation:

attr_addr = base_ptr + attr_idx * stride

When drawing a graphics primitive that has been enabled to use indexed attributes (see GXSetVtxDesc), attr_idx is supplied in the vertex data. The format and size of the data in the array must also be described using GXSetVtxAttrFmt.

You can also index other data, such as matrices (see #GXLoadPosMtxIndx, #GXLoadNrmMtxIndx3x3, and #GXLoadTexMtxIndx), and light objects (see #GXLoadLightObjIndx). In the case of matrices and light objects, the size and format of the data to be loaded is implied by the function call.

There is a base pointer, base_ptr, for each type of attribute as well as for light data and matrices. Each attribute can be stored in its own array for maximum data compression (i.e., removal of redundant attribute data). The stride is in byte units and is the distance between attributes in the array.

Indexed data is loaded into a vertex cache in the graphics processor. The vertex cache fetches 32 bytes of data for each cache miss; therefore, there is a small performance benefit to aligning attribute arrays to 32 bytes, and possibly for arranging vertex data so that it doesn't span 32-byte boundaries. Conveniently enough, OSAlloc returns 32-byte aligned pointers. For static data arrays, you can use the ATTRIBUTE_ALIGN macro (specific to the MetroWerks compiler) to align the base_ptr to 32 bytes, as in:

u32 mydata[] ATTRIBUTE_ALIGN(32) = {
    // initialize data
};

Parameters

attr	The attribute array name.
base_ptr	Pointer to first element in attribute data array.
stride	Stride in bytes between attribute data elements.

GXSetVtxAttrFmt()

void GXSetVtxAttrFmt	(	size_t	vtxfmt,
		GXAttr	attr,
		enum_t	count,
		GXCompType	type,
		u8	frac
	)

Sets the attribute format (attr) for a single attribute in the Vertex Attribute Format Table (VAT).

Each attribute format describes the data type, number of elements (count), and fixed point format (frac), if required. The are eight vertex formats available in the VAT. The vertex format describes the format of all attributes in a vertex. The application can pre-program all eight vertex formats, and then select one of them during the actual drawing of geometry (see GXBegin). Note that all vertices used to draw a particular graphics primitive will have the same format. The vertex format set using GXSetVtxAttrFmt, along with the current vertex descriptor set using GXSetVtxDesc, completely define the vertex data format.

The vertex format allows data to be sent to the graphics processor in its most quantized format. The graphics hardware will inverse-quantize the data (into floating point format) before it is used. The vertex attribute format is used to communicate the data quantization format to the hardware.

Note that GX_VA_NRM and GX_VA_NBT attributes share the same type. Also, the frac for these attributes is fixed according to the type. The component count (count) for GX_VA_NRM must be set to GX_NRM_XYZ. The component count for GX_VA_NBT must be set to GX_NRM_NBT (see exception for HW2 below).

Note also that a HW1 bug means that for a component type of u8 or s8, the fixed-point fraction is ignored and assumed to be zero.

Parameters

vtxfmt	The vertex format number.
attr	The attribute name.
count	May be one of several different enumerations, depending on the attribute name; one of GXCompCnt, #GXPosCompCnt, #GXNrmCompCnt, #GXClrCompCnt, or #GXTexCompCnt. Ultimately aids in determining the number of dimensions for this attribute. For example, 4 for an RGBA color, or 3 for vertex position data.
type	May be one of several different enumerations, depending on the attribute name. Specifies the data format for a single value in a dimension, such as u8, s16, or f32.
frac	Specifies the number of fractional bits in a fixed point number, where 0 <= frac <= 31. frac is ignored for floating-point types and color types.

See also

GXBegin

GXSetVtxAttrFmt

GXSetVtxDesc

GXClearVtxDesc()

void GXClearVtxDesc

(

void

)

__GXSetVCD

GXSetVtxDesc()

void GXSetVtxDesc	(	GXAttr	attr,
		s32	type
	)

__GXXfVtxSpecs

Sets the type of a single attribute (attr) in the current vertex descriptor.

The current vertex descriptor defines which attributes are present in a vertex and how each attribute is referenced. It is used by the Graphics Processor (GP) to interpret the graphics command stream produced by the GX API. In particular, the current vertex descriptor is used to parse the vertex data that is present in the command stream.

Parameters

attr	The name of the attribute. Enabled attribute data must be sent in ascending order.
type	The reference type of the attribute. Accepted values are GX_NONE, GX_DIRECT, GX_INDEX8, and GX_INDEX16.

__GXSetVCD()

void __GXSetVCD

(

void

)

__GXSetVAT()

void __GXSetVAT

(

void

)

__GXXfVtxSpecs()

void __GXXfVtxSpecs

(

void

)