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>nngxTransferLinearImage</title>
8  </head>
9  <body>
10<h1><CODE>nngxTransferLinearImage</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14NNGX_APICALL void NNGX_APIENTRY nngxTransferLinearImage(
15     const GLvoid * srcaddr,
16     GLuint dstid,
17     GLenum target
18);
19</pre>
20    </div>
21<h2>Parameters</h2>
22    <div class="section">
23      <table class="arguments">
24        <thead>
25          <tr>
26            <td width="15" />
27<th>Name</th>
28<td>Description</td>
29          </tr>
30        </thead>
31        <tr>
32<td>in</td>
33<th>srcaddr</th>
34<td>Transfer source address.</td>
35        </tr>
36        <tr>
37<td>in</td>
38<th>dstid</th>
39<td>Transfer destination object ID.</td>
40        </tr>
41        <tr>
42<td>in</td>
43<th>target</th>
44<td>Transfer destination object type.</td>
45        </tr> </table>
46    </div>
47<h2>Return Values</h2>
48<div class="section">No values are returned. </div>
49<h2>Description</h2>
50    <div class="section">
51<p>Adds a command request to transfer an image to the specified render buffer or texture.</p><P>
52Adds a command to the current command list to transfer the data in the memory region specified in <SPAN class="argument">srcaddr</SPAN> to the render buffer or texture specified in <SPAN class="argument">dstid</SPAN>.
53            </P><P>
54The meaning of the value in <SPAN class="argument">dstid</SPAN> changes depending on the value specified in <SPAN class="argument">target</SPAN>.
55<TABLE><TR><TH>target</TH><TD>dstid</TD></TR><TR><TH>GL_RENDERBUFFER</TH><TD>If the render buffer object specifies <CODE>0</CODE>, it indicates the color buffer that is attached to the current framebuffer.</TD></TR><TR><TH><CODE>GL_TEXTURE_2D</CODE></TH><TD>2D texture object.</TD></TR><TR><TH>
56GL_TEXTURE_CUBE_MAP_POSITIVE_X<BR /> GL_TEXTURE_CUBE_MAP_NEGATIVE_X<BR /> GL_TEXTURE_CUBE_MAP_POSITIVE_Y<BR /> GL_TEXTURE_CUBE_MAP_NEGATIVE_Y<BR /> GL_TEXTURE_CUBE_MAP_POSITIVE_Z<BR /> GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</TH><TD>Cube map texture object.</TD></TR></TABLE></P><P>
57The memory region specified in <SPAN class="argument">srcaddr</SPAN> stores image data of the same format, width, and height as the render buffer or texture specified in <SPAN class="argument">dstid</SPAN>. The transfer source image data is converted to PICA native format block addressing and transferred to the target memory region. When the transfer destination object is a render buffer, the block addressing conversion is either to 8-block or 32-block addressing, depending on the block format settings when this function is called. When the transfer destination object is a texture, the conversion is to 8-block addressing.
58            </P><P>
59Data conversion via this function affects only addressing, and does not flip the image vertically or change the byte order. The render buffer and texture are based on the PICA native format image specifications. The source image data might need to be flipped vertically or have its byte order converted before calling this function.
60            </P><P>
61If unsplit commands have already been accumulated in the current 3D command list, the function adds a split command and then adds the transfer command request.
62            </P><P>
63If the transfer destination format is 24-bit, the source data must be in 32-bit format. The first byte of every four bytes of the source data is split and transferred. (The hardware does not support transferring 24-bit format to 24-bit format.)
64            </P><P>
65<CODE>srcaddr</CODE> must be stored in device memory or in VRAM.  If they are not stored in these regions, <CODE>Development</CODE> and <CODE>Debug</CODE> builds will stop on an assertion and <CODE>Release</CODE> builds will quit without adding a transfer command.<br /> If the <CODE>srcaddr</CODE> data is stored in device memory and will be directly referenced and edited by the CPU, then you will need to use the <CODE><a href="../nn_gx/nngxUpdateBuffer.html">nngxUpdateBuffer</a></CODE> function to flush the cache before executing the transfer command.
66            </P><P>
67This function generates the following errors.
68<TABLE><TR><TH>GL_ERROR_805B_DMP</TH><TD><CODE>0</CODE> is bound to the current command list.</TD></TR><TR><TH>GL_ERROR_805C_DMP</TH><TD>The current command list has already accumulated the maximum number of command requests.</TD></TR><TR><TH>GL_ERROR_805D_DMP</TH><TD>The current 3D command buffer is too small.</TD></TR><TR><TH>GL_ERROR_805E_DMP</TH><TD>The render buffer or texture specified in <SPAN class="argument">dstid</SPAN> does not exist, or the address is not allocated.</TD></TR><TR><TH>GL_ERROR_805F_DMP</TH><TD>Either the transfer destination render buffer width or height is less than 128, or the block format when this function was called is not a multiple of 8 for 8-bit block format, or a multiple of 32 for 32-bit block format.</TD></TR><TR><TH>GL_ERROR_8060_DMP</TH><TD>The <span class="argument">target</span> argument was set to an invalid value.</TD></TR><TR><TH>GL_ERROR_8067_DMP</TH><TD>The pixel size of the destination target buffer or texture is not 32-, 24-, or 16-bit.</TD></TR></TABLE></P></div>
69<h2>Revision History</h2>
70    <div class="section">
71      <dl class="history">
72        <dt>2011/06/21</dt>
73<dd>Added mention of a restriction on <CODE>srcaddr</CODE> and the use of the <CODE>nngxUpdateBuffer</CODE> function to flush the cache.<br />
74        </dd>
75        <dt>2010/07/07</dt>
76<dd>Initial version.<br />
77        </dd>
78      </dl>
79    </div>
80  <hr><p>CONFIDENTIAL</p></body>
81</html>