#include <revolution/gx.h>void GXBeginDisplayList( void* list, u32 size );list |
pointer to a buffer used to store display list commands 32-byte aligned |
size |
size of the display list buffer Must be a multiple of 32. |
None.
GXBeginDisplayList begins a display list and disables writing to the FIFO currently attached to the CPU. After this function is called, the GX API functions that would normally send commands or data into the CPU will be sent to the display list's list buffer instead of the FIFO until the GXEndDisplayList function is called.
Writing to the CPU FIFO is re-enabled when the function GXEndDisplayList is executed.
The application must allocate memory for the display list buffer. If the display list exceeds the size of the buffer, GXEndDisplayList will return an error. The address of the buffer must be 32-byte aligned. OSAlloc returns 32-byte-aligned pointers. The macro ATTRIBUTE_ALIGN(32) can be used to align statically allocated buffers.
The CPU's write-gather pipe is used to write graphics commands to the display list. Therefore, the display list buffer must be forced out of the CPU cache prior to being filled. The command DCInvalidateRange may be used for this purpose. In addition, due to the mechanics of flushing the write-gather pipe, the display list buffer should be at least 32 bytes larger than the maximum expected amount of data stored. GXBeginDisplayList calls the function GXResetWriteGatherPipe internally to let the pointer to the write-gather pipe be 32-byte-aligned and to always pack graphics commands from the top of display list buffer.
A display list cannot be nested. I.e., the functions GXBeginDisplayList, GXCallDisplayList and GXEndDisplayList cannot be called between GXBeginDisplayList and GXEndDisplayList.
In general most GX API commands can be used in a display list. However, since the use of the display list can bypass all state coherences controlled by the GX API in run-time, it sometimes results in state conflicts that can lead to unexpected behavior or even hangs. The most recommended procedure is to use only primitives (enclosed by GXBegin and GXEnd) that don't cause any state conflicts.
Use GXCallDisplayList to execute a display list.
GXResetWriteGatherPipe
GXEndDisplayList
GXCallDisplayList
2006/03/01 Initial version.
CONFIDENTIAL