1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../css/manpage.css" type="text/css" />
7<title>nngxFlush3DCommandPartially</title>
8  </head>
9  <body>
10<h1><CODE>nngxFlush3DCommandPartially</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14NNGX_APICALL void NNGX_APIENTRY nngxFlush3DCommandPartially(
15     GLsizei buffersize
16);
17</pre>
18    </div>
19<h2>Arguments</h2>
20    <div class="section">
21      <table class="arguments">
22        <thead>
23          <tr>
24            <td width="15" />
25<th>Name</th>
26<td>Description</td>
27          </tr>
28        </thead>
29        <tr>
30<td>in</td>
31<th><CODE>buffersize</CODE></th>
32<td>Size (in bytes) of the command buffer to execute</td>
33        </tr> </table>
34    </div>
35<h2>Return Values</h2>
36<div class="section">No values are returned. </div>
37<h2>Description</h2>
38    <div class="section">
39<p>Issues a render command request and flushes the accumulated 3D command buffer. However, 3D commands are only executed for the specified size.</p><P>
40A command to complete the loading of 3D commands is added to the 3D command buffer of the bound command list object, and a render command request is queued to the command requests.
41            </P><P>
42This function is an extended version of the <CODE><a href="../nn_gx/nngxFlush3DCommand.html">nngxFlush3DCommand</a></CODE> function. It provides nearly the same functionality, but differs on the following points.
43<UL><LI>The size of the command buffer to execute is specified in the <SPAN class="argument">buffersize</SPAN> parameter. It is not the total size of the commands accumulated between the last command flush and this function call.</LI><LI>The cache is not flushed for commands in the 3D command buffer accumulated between the last command flush and this function call.</LI><LI>This cannot be used on an executing command list object (causes an error).</LI></UL></P><P>
44Use this function when you want the application to freely create command-buffer execution register commands (such as using the <CODE>GR</CODE> library), without using the <CODE><a href="../nn_gx/nngxAddJumpCommand.html">nngxAddJumpCommand</a></CODE> or <CODE><a href="../nn_gx/nngxAddSubroutineCommand.html">nngxAddSubroutineCommand</a></CODE> functions.<FONT color="red">There is no need to use this function if you implement command-buffer jumps using the <CODE>nngx</CODE> API.</FONT></P><P>
45The standard <CODE>nngxFlush3DCommand</CODE> function attempts to execute the entire contents of the 3D command buffer at the time it is called. However, if the accumulated commands include a command-buffer execution register kick command, then it must kick the GPU using the buffer up to the kick command (the first one stored in the command buffer) as the size, rather than executing all accumulated commands.
46            </P><P>
47If you have added a kick command using the <CODE>nngxAddJumpCommand</CODE> or <CODE>nngxAddSubroutineCommand</CODE> function, then the driver will adjust the execution size to that of the buffer up to the first kick command. However, if you use the <CODE><a href="../nn_gx/nngxAdd3DCommand.html">nngxAdd3DCommand</a></CODE> function to add data provided by the application as a command, then the driver will not be able to tell whether there is a kick command among these commands. That is why there is a need for the functionality provided by this function to specify the execution size and flush the command buffer.
48            </P><P>
49Set <SPAN class="argument">buffersize</SPAN> to the size of the command buffer to execute in bytes. Must be a multiple of 16.
50            </P><P>
51If you accumulate a kick command in the command buffer without using the <CODE>nngxAddJumpCommand</CODE> or <CODE>nngxAddSubroutineCommand</CODE> functions, for <SPAN class="argument">buffersize</SPAN> specify the address of the last command flush until the first kick command (inclusive).
52</P><H3>Usage Notes</H3><DIV class="section"><P>
53You must set <SPAN class="argument">buffersize</SPAN> correctly to the size from the address after the last command flush until the first kick command (inclusive). Setting this to an incorrect value could cause such behavior as commands executing out of their intended sequence, or 3D executions being unable to terminate correctly.
54            </P><P>
55Contents in the 3D command buffer accumulated after the last command flush until this function call are not flushed from the cache. The application is responsible for flushing the cache for the command buffer. Ensure that the application does so. Wait until after calling this function before flushing the entire cache, because this function also generates several commands itself, including commands that raise interrupts. (There is a restriction against calling this function on executing command lists. This is to prevent execution before a cache flush, because the cache must be flushed after calling this function.)
56</P><P>The <CODE><a href="../nn_gx/nngxTransferRenderImage.html">nngxTransferRenderImage</a></CODE>, <CODE><a href="../gl/glClear.html">glClear</a></CODE>, <CODE><a href="../gl/glCopyTexImage2D.html">glCopyTexImage2D</a></CODE> and other functions also flush the command cache. These commands flush the cache using the same method as the <CODE>nngxFlush3DCommand</CODE> function. Always use this function to flush the cache.
57</P><P>If you have added a kick command using the <CODE><a href="../nn_gx/nngxAddSubroutineCommand.html">nngxAddSubroutineCommand</a></CODE> function, then the driver will adjust the execution size to that of the buffer up to the first kick command. For this reason, there is no need for the application to specify the command execution size or to even use this function if the <CODE><a href="../nn_gx/nngxAddSubroutineCommand.html">nngxAddSubroutineCommand</a></CODE> function has been used. If this function is used to flush a command buffer to which a kick command has been added using the <CODE><a href="../nn_gx/nngxAddSubroutineCommand.html">nngxAddSubroutineCommand</a></CODE> function, the execution size specified by this function is used rather than the size calculated by the driver.
58            </P></DIV><P>
59This function generates the following errors.
60<TABLE><TR><TH><CODE>GL_ERROR_80A9_DMP</CODE></TH><TD><CODE>0</CODE> is bound to the current command list.</TD></TR><TR><TH><CODE>GL_ERROR_80AA_DMP</CODE></TH><TD>The number of accumulated command requests has reached the maximum number of command requests.</TD></TR><TR><TH><CODE>GL_ERROR_80AB_DMP</CODE></TH><TD>The accumulated 3D command buffer exceeds its maximum size when the command to complete the loading of 3D commands is added to the buffer.</TD></TR><TR><TH><CODE>GL_ERROR_80AC_DMP</CODE></TH><TD><SPAN class="argument">buffersize</SPAN> is 0 or less, or is not a multiple of 16.</TD></TR><TR><TH><CODE>GL_ERROR_80AD_DMP</CODE></TH><TD>The current command list is running.</TD></TR></TABLE></P></div>
61<h2>See Also</h2>
62    <div class="section">
63<p class="reference"><a href="../nn_gx/nngxFlush3DCommand.html"><CODE>nngxFlush3DCommand</CODE></a><br /> </p>
64    </div>
65<h2>Revision History</h2>
66    <div class="section">
67      <dl class="history">
68        <dt>2011/12/12</dt>
69<dd>Added information to note about operations when using the nngxAddSubroutineCommand function<br />
70        </dd>
71        <dt>2011/10/04</dt>
72<dd>Added <B>See Also</B> section.<br />
73        </dd>
74        <dt>2011/09/22</dt>
75<dd>Initial version.<br />
76        </dd>
77      </dl>
78    </div>
79  <hr><p>CONFIDENTIAL</p></body>
80</html>
81