#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.
The GXBeginDisplayList function begins a display list and disables writing to the FIFO currently attached to the CPU. After this function is called, until the GXEndDisplayList function is called, the GX API functions that would normally send commands or data into the CPU FIFO will be sent to the display list buffer (list) instead of the FIFO.
Writing to the CPU FIFO is enabled again when the GXEndDisplayList function is executed.
The application must allocate memory for the display list buffer. If the display list exceeds the maximum size (size) of the buffer, the GXEndDisplayList function will return an error. The address of the buffer must be 32-byte aligned. The OSAlloc function returns 32-byte-aligned pointers. The macro ATTRIBUTE_ALIGN(32) can be used for static allocation buffers.
The CPU's write-gather pipe is used to write graphics commands to the display list. Therefore, the CPU cache contents must be written back before the write-gather pipe can begin writing to the display list. 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. The GXBeginDisplayList function internally calls the GXResetWriteGatherPipe function to make the pointer to the write-gather pipe 32-byte-aligned and to always pack graphics commands from the top of display list buffer.
A display list cannot be nested. In other words, you cannot call the GXBeginDisplayList, GXCallDisplayList, or GXEndDisplayList function in the interval between GXBeginDisplayList and GXEndDisplayList. The GXBeginDisplayList function calls GXFlush. Therefore, there is no need to explicitly call GXFlush after you have executed GXBeginDisplayList.
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 and safe procedure is to send only primitives (enclosed by the GXBegin and GXEnd functions) that don't cause any state conflicts.
Use the GXCallDisplayList function to execute a display list.
GXResetWriteGatherPipe, GXEndDisplayList, GXCallDisplayList
2008/05/12 Added mention of how GXFlush is included when calling other functions.
2006/03/01 Initial version.
CONFIDENTIAL