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 13<H2>Syntax</H2> 14<dl><dd><pre class="construction"> 15#include <revolution/gx.h> 16 17void GXBeginDisplayList( void* list, u32 size ); 18</pre></dd></dl> 19 20<H2>Arguments</H2> 21<TABLE class="arguments" border="1" > 22 <TBODY> 23 <TR> 24<TH>list</TH> 25<TD>Pointer to a buffer used to store display list commands. 32-byte aligned.</TD> 26 </TR> 27 <TR> 28<TH>size</TH> 29<TD>Size of the display list buffer. <BR>Must be a multiple of 32.</TD> 30 </TR> 31 </TBODY> 32</TABLE> 33 34<H2>Return Values</H2> 35<P>None.</P> 36 37<H2>Description</H2> 38<P>The <CODE>GXBeginDisplayList</CODE> function begins a display list and disables writing to the FIFO currently attached to the CPU. After this function is called, until the <A href="GXEndDisplayList.html"><CODE>GXEndDisplayList</CODE></A> 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 (<SPAN class="argument">list</SPAN>) instead of the FIFO.</P> 39<P>Writing to the CPU FIFO is enabled again when the <A href="GXEndDisplayList.html"><CODE>GXEndDisplayList</CODE></A> function is executed.</P> 40<P>The application must allocate memory for the display list buffer. If the display list exceeds the maximum size (<SPAN class="argument">size</SPAN>) of the buffer, the <A href="GXEndDisplayList.html"><CODE>GXEndDisplayList</CODE></A> function will return an error. The address of the buffer must be 32-byte aligned. The <A href="../../os/Alloc/OSAlloc.html"><CODE>OSAlloc</CODE></A> function returns 32-byte-aligned pointers. The macro <CODE>ATTRIBUTE_ALIGN(32)</CODE> can be used for static allocation buffers.</P> 41<P>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 <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. The <code>GXBeginDisplayList</code> function internally calls the <A href="../GfxFIFO/GXResetWriteGatherPipe.html"><code>GXResetWriteGatherPipe</code></A> 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.</P> 42<P>A display list cannot be nested. In other words, you cannot call the <CODE>GXBeginDisplayList</CODE>, <A href="GXCallDisplayList.html"><CODE>GXCallDisplayList</CODE></A>, or <A href="GXEndDisplayList.html"><CODE>GXEndDisplayList</CODE></A> function in the interval between <CODE>GXBeginDisplayList</CODE> and <A href="GXEndDisplayList.html"><CODE>GXEndDisplayList</CODE></A>. The <CODE>GXBeginDisplayList</CODE> function calls <A href="../Management/GXFlush.html"><CODE>GXFlush</CODE></A>. Therefore, there is no need to explicitly call <A href="../Management/GXFlush.html"><CODE>GXFlush</CODE></A> after you have executed <CODE>GXBeginDisplayList</CODE>.</P> 43<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 and safe procedure is to send only primitives (enclosed by the <A href="../Geometry/GXBegin.html"><CODE>GXBegin</CODE></A> and <A href="../Geometry/GXEnd.html"><CODE>GXEnd</CODE></A> functions) that don't cause any state conflicts.</P> 44<P>Use the <A href="GXCallDisplayList.html"><CODE>GXCallDisplayList</CODE></A> function to execute a display list.</P> 45 46<H2>See Also</H2> 47<P class="reference"> 48<A href="../GfxFIFO/GXResetWriteGatherPipe.html">GXResetWriteGatherPipe</A>, 49<A href="GXEndDisplayList.html">GXEndDisplayList</A>, 50<A href="GXCallDisplayList.html">GXCallDisplayList</A> 51</P> 52 53<H2>Revision History</H2> 54<P> 552008/05/12 Added mention of how <CODE>GXFlush</CODE> is included when calling other functions.<br>2006/03/01 Initial version.<br> 56</P> 57 58<hr><p>CONFIDENTIAL</p></body> 59</HTML>