1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="Microsoft FrontPage 5.0"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<LINK rel="stylesheet" type="text/css" href="../../CSS/revolution.css"> 8<TITLE>GXBeginDisplayList</TITLE> 9</HEAD> 10<BODY> 11<H1 align="left">GXBeginDisplayList</H1> 12<H2>C Specification</H2> 13<DL> 14 <DD> 15<PRE><CODE>#include <revolution/gx.h></CODE></PRE> 16 <DD> 17<PRE><CODE>void GXBeginDisplayList( void* list, u32 size );</CODE></PRE> 18</DL> 19<H2>Arguments</H2> 20<TABLE border="1" cellpadding="3" cellspacing="0.1"> 21 <TBODY> 22 <TR> 23<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>list</CODE></STRONG></EM></TD> 24<TD width="520">pointer to a buffer used to store display list commands <BR>32-byte aligned</TD> 25 </TR> 26 <TR> 27<TD width="120" bgcolor="#ffffe8"><EM><STRONG><CODE>size</FONT></STRONG></EM></TD> 28<TD width="520">size of the display list buffer <BR>Must be a multiple of 32.</TD> 29 </TR> 30 </TBODY> 31</TABLE> 32<H2>Return Values</H2> 33<P>None.</P> 34<H2>Description</H2> 35<P><a href="GXBeginDisplayList.html"><code>GXBeginDisplayList</code></a> 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 <code>list</code> buffer instead of the FIFO until the <a href="GXEndDisplayList.html"><code>GXEndDisplayList</code></a> function is called.</P> 36<P>Writing to the CPU FIFO is re-enabled when the function <a href="GXEndDisplayList.html"><code>GXEndDisplayList</code></a> is executed.</P> 37<P>The application must allocate memory for the display list buffer. If the display list exceeds the <code>size</code> of the buffer, <a href="GXEndDisplayList.html"><code>GXEndDisplayList</code></a> will return an error. The address of the buffer must be 32-byte aligned. <a href="../../os/Alloc/OSAlloc.html"><code>OSAlloc</code></a> returns 32-byte-aligned pointers. The macro <code>ATTRIBUTE_ALIGN(32)</code> can be used to align statically allocated buffers.</P> 38<P>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 <a href="../../os/Cache/DCInvalidateRange.html"><code>DCInvalidateRange</code></a> 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. <a href="GXBeginDisplayList.html"><code>GXBeginDisplayList</code></a> calls the function <a href="../GfxFIFO/GXResetWriteGatherPipe.html"><code>GXResetWriteGatherPipe</code></a> 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.</P> 39<P>A display list cannot be nested. I.e., the functions <a href="GXBeginDisplayList.html"><code>GXBeginDisplayList</code></a>, <a href="GXCallDisplayList.html"><code>GXCallDisplayList</code></a> and <a href="GXEndDisplayList.html"><code>GXEndDisplayList</code></a> cannot be called between <a href="GXBeginDisplayList.html"><code>GXBeginDisplayList</code></a> and <a href="GXEndDisplayList.html"><code>GXEndDisplayList</code></a>.</P> 40<P>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 <a href="../Geometry/GXBegin.html"><code>GXBegin</code></a> and <code><a href="../Geometry/GXEnd.html">GXEnd</a></code>) that don't cause any state conflicts.</P> 41<P>Use <a href="GXCallDisplayList.html"><code>GXCallDisplayList</code></a> to execute a display list.</P> 42<H2>See Also</H2> 43<P><A href="../GfxFIFO/GXResetWriteGatherPipe.html"><CODE>GXResetWriteGatherPipe</CODE></A><BR> <A href="GXEndDisplayList.html"><CODE>GXEndDisplayList</CODE></A><BR> <CODE><A href="GXCallDisplayList.html">GXCallDisplayList</A></CODE></P> 44<H2>Revision History</H2> 45<P>03/01/2006 Initial version.</P> 46</BODY> 47</HTML> 48