GDSetArray, etc.

C Specification

#include <revolution/gd.h>

void GDSetArray( GXAttr attr, const void* base_ptr, u8 stride );
void GDSetArrayRaw( GXAttr attr, u32 base_ptr_raw, u8 stride );
void GDPatchArrayBase( const void* base_ptr );

Arguments

`attr`	Specifies the attribute array name. Values that can be specified are: `GX_VA_POSMTXARRAY, GX_VA_NRMMTXARRAY, GX_VA_TEXMTXARRAY, GX_VA_LIGHTARRAY, GX_VA_POS, GX_VA_NRM, GX_VA_CLR0, GX_VA_CLR1, GX_VA_TEX0, GX_VA_TEX1, GX_VA_TEX2, GX_VA_TEX3, GX_VA_TEX4, GX_VA_TEX5, GX_VA_TEX6, GX_VA_TEX7`.
`base_ptr`	Pointer to first element in attribute data array.
`base_ptr_raw`	A type U32 value to insert in place of the actual *`base_ptr`*.
`stride`	Stride between attribute data elements in bytes.

Return Values

None.

Description

GDSetArray sets the array base pointer and stride for a single attribute. The array base pointer and stride are used to compute the address of the indexed attribute data using the following equation:

attr_addr = base_ptr + attr_idx * stride

This function corresponds exactly to GXSetArray. Because the array base pointer is unknown when the display list is created, being able to write a dummy base pointer value now and patch in the real pointer later is necessary. GDSetArrayRaw and GDPatchArrayBase are provided for this purpose.

GDSetArrayRaw allows a raw (U32) data value to be written in place of the array base pointer. GXSetArray converts the logical address into a physical address. The raw version of this function omits this process.

GDPatchArrayBase only writes out a converted address. To properly use this function, you must first save the correct patch location (when the display list was created), and then reset the current offset to this patch location before calling GDPatchArrayBase. Finally, the newly written data is flushed back into main memory. The following code illustrates the correct operation sequence.

Display list creation:

savedOffset[0] = GDGetCurrOffset() + CP_DATA_OFFSET;  // save the necessary offset
GDSetArrayRaw( GX_VA_POS, 0, 12 );

Display list patching:

GDSetCurrOffset(savedOffset[0]);  // set the offset
cp = GDGetCurrPointer();          // save ptr for flushing later
GDPatchArrayBase(tp);             // patch in the base address ptr
DCStoreRange(cp, CP_DATA_LENGTH); // flush to main memory

Because GDSetArray issues CP commands, we use CP_DATA_OFFSET and CP_DATA_LENGTH in the above code segments.

Revision History