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>glCopyTexImage2D</title> 8 </head> 9 <body> 10<h1><CODE>glCopyTexImage2D</CODE> Function</h1> 11<h2>Syntax</h2> 12 <div class="section"> 13 <pre class="definition"> 14GL_APICALL void GL_APIENTRY glCopyTexImage2D( 15 GLenum target, 16 GLint level, 17 GLenum internalformat, 18 GLint x, 19 GLint y, 20 GLsizei width, 21 GLsizei height, 22 GLint border 23); 24</pre> 25 </div> 26<h2>Arguments</h2> 27 <div class="section"> 28 <table class="arguments"> 29 <thead> 30 <tr> 31 <td width="15" /> 32<th>Name</th> 33<td>Description</td> 34 </tr> 35 </thead> 36 <tr> 37<td>in</td> 38<th>target</th> 39<td>Target texture.</td> 40 </tr> 41 <tr> 42<td>in</td> 43<th>level</th> 44<td>Mipmap level of the data to load.</td> 45 </tr> 46 <tr> 47<td>in</td> 48<th>internalformat</th> 49<td>Texture format.</td> 50 </tr> 51 <tr> 52<td>in</td> 53<th>x</th> 54<td>X coordinate at the lower-left corner of the color buffer's copy region.</td> 55 </tr> 56 <tr> 57<td>in</td> 58<th>y</th> 59<td>Y coordinate at the lower-left corner of the color buffer's copy region.</td> 60 </tr> 61 <tr> 62<td>in</td> 63<th>width</th> 64<td>Width of the region read from the color buffer.</td> 65 </tr> 66 <tr> 67<td>in</td> 68<th>height</th> 69<td>Height of the region read from the color buffer.</td> 70 </tr> 71 <tr> 72<td>in</td> 73<th>border</th> 74<td>Border width (<CODE>0</CODE> is the only valid value).</td> 75 </tr> </table> 76 </div> 77<h2>Return Values</h2> 78<div class="section">There is no return value. </div> 79<h2>Description</h2> 80 <div class="section"> 81<p>Copies the content of the current color buffer into texture data.</p><P> 82You can set <SPAN class="argument">target</SPAN> to one of the following values. 83<TABLE><TR><TH><CODE>GL_TEXTURE_2D</CODE></TH><TD> 2D texture.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</CODE></TH><TD> Face of a cube-map texture in the negative x direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_X</CODE></TH><TD> Face of a cube-map texture in the positive x direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</CODE></TH><TD> Face of a cube-map texture in the negative y direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</CODE></TH><TD> Face of a cube-map texture in the positive y direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</CODE></TH><TD> Face of a cube-map texture in the negative z direction.</TD></TR><TR><TH><CODE>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</CODE></TH><TD> Face of a cube-map texture in the positive z direction. </TD></TR></TABLE></P><P> 84To specify the region that is accessed by the GPU, set <SPAN class="argument">target</SPAN> to a bitwise OR of the aforementioned and the following values. 85<TABLE><TR><TH>NN_GX_MEM_FCRAM</TH><TD>The GPU accesses FCRAM.</TD></TR><TR><TH><CODE>NN_GX_MEM_VRAMA</CODE></TH><TD>The GPU accesses VRAMA.</TD></TR><TR><TH><CODE>NN_GX_MEM_VRAMB</CODE></TH><TD>The GPU accesses VRAMB.</TD></TR></TABLE></P><P> 86If you have not specified which region is accessed by the GPU, <code>NN_GX_MEM_FCRAM</code> is used. (These settings cannot be specified for POD.) 87 </P><P> 88When you specify <CODE>-2</CODE> or less for the <SPAN class="argument">level</SPAN> argument, all textures other than for the lowest mipmap level are automatically generated. Automatic mipmap generation is only supported for some texture formats. Also, the minimum generatable texture widths and heights (LOD upper limit) are different for each texture format. The following table shows the supported values for <SPAN class="argument">format</SPAN> and <SPAN class="argument">type</SPAN> and the minimum generatable sizes. 89<TABLE><THEAD><TR><TD>format</TD><TD>type</TD><TD>Minimum automatically generatable size (in texels)</TD></TR></THEAD><TR><TD><CODE>GL_RGBA</CODE></TD><TD><CODE>GL_UNSIGNED_SHORT_4_4_4_4</CODE></TD><TD>64</TD></TR><TR><TD><CODE>GL_RGBA</CODE></TD><TD><CODE>GL_UNSIGNED_SHORT_5_5_5_1</CODE></TD><TD>64</TD></TR><TR><TD><CODE>GL_RGBA</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD><TD>32</TD></TR><TR><TD><CODE>GL_RGB</CODE></TD><TD><CODE>GL_UNSIGNED_SHORT_5_6_5</CODE></TD><TD>64</TD></TR><TR><TD><CODE>GL_RGB</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD><TD>32</TD></TR><TR><TD><CODE>GL_RGBA_NATIVE_DMP</CODE></TD><TD><CODE>GL_UNSIGNED_SHORT_4_4_4_4</CODE></TD><TD>64</TD></TR><TR><TD><CODE>GL_RGBA_NATIVE_DMP</CODE></TD><TD><CODE>GL_UNSIGNED_SHORT_5_5_5_1</CODE></TD><TD>64</TD></TR><TR><TD><CODE>GL_RGBA_NATIVE_DMP</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD><TD>32</TD></TR><TR><TD><CODE>GL_RGB_NATIVE_DMP</CODE></TD><TD><CODE>GL_UNSIGNED_SHORT_5_6_5</CODE></TD><TD>64</TD></TR><TR><TD><CODE>GL_RGB_NATIVE_DMP</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD><TD>32</TD></TR></TABLE> 90Specifying a value for <SPAN class="argument">level</SPAN> that does not conform to the minimum sizes of the generated mipmaps listed above causes a <CODE>GL_INVALID_OPERATION</CODE> error. 91 </P><P> 92Set <span class="argument">internalformat</span> to <code>GL_RGBA</code>, <code>GL_RGB</code>, or <code>GL_GAS_DMP</code>. 93 </P><P> 94Set <span class="argument">x</span> and <span class="argument">y</span> to the coordinates at the lower-left corner of the color buffer region to copy. The <span class="argument">x</span> and <span class="argument">y</span> arguments must be multiples of 8. 95 </P><P> 96Specify the width and height of the region read from the color buffer in the <SPAN class="argument">width</SPAN> and <SPAN class="argument">height</SPAN> arguments. Since this specifies the size of a texture, the values must be a power of 2 from 8 to 1024. 97 </P><P> 98You must set <SPAN class="argument">border</SPAN> equal to <CODE>0</CODE>. 99 </P><P> 100You cannot properly render a color buffer that was rendered with 32-block mode set by <code>glRenderBlockMode</code>, even if you use this function to copy the buffer to a texture. 101 </P><P> 102You can copy the current depth buffer to a texture and use that. Call the <CODE>glEnable</CODE> function and specify <CODE>GL_DEPTH_STENCIL_COPY_DMP</CODE> to enable the depth stencil copy feature. Call the <CODE>glDisable</CODE> function to disable this feature. Call the <CODE>glIsEnabled</CODE> function and specify <CODE>GL_DEPTH_STENCIL_COPY_DMP</CODE> to find if the depth stencil copy feature is enabled. 103 </P><P> 104The format of the target texture for copying is determined by the format of the current depth buffer. Format conversion when copying is not supported. The format of the current depth buffer corresponds to the format of the target texture for copying as follows. 105<TABLE><TR><TH>Depth Buffer Format</TH><TH>Depth Buffer Content</TH><TH>Corresponding Texture Format (Texture Type)</TH></TR><TR><TD><CODE>GL_DEPTH24_STENCIL8_EXT</CODE></TD><TD>R: 8-bit stencil value<BR />G: 24-bit depth value, bits [23:16]<BR />B: 24-bit depth value, bits [15:8]<BR />A: 24-bit depth value, bits [7:0]</TD><TD><CODE>GL_RGBA</CODE> (<CODE>GL_UNSIGNED_BYTE</CODE>), <CODE>GL_RGBA_NATIVE_DMP</CODE> (<CODE>GL_UNSIGNED_BYTE</CODE>)</TD></TR><TR><TD><CODE>GL_DEPTH_COMPONENT24_OES</CODE></TD><TD>R: 24-bit depth value, bits [23:16]<BR />G: 24-bit depth value, bits [15:8]<BR />B: 24-bit depth value, bits [7:0]</TD><TD><CODE>GL_RGB</CODE> (<CODE>GL_UNSIGNED_BYTE</CODE>), <CODE>GL_RGB_NATIVE_DMP</CODE> (<CODE>GL_UNSIGNED_BYTE</CODE>)</TD></TR><TR><TD><CODE>GL_DEPTH_COMPONENT16</CODE></TD><TD>R: 16-bit depth value, bits [15:8]<BR />G: 16-bit depth value, bits [7:0]</TD><TD><CODE>GL_HILO8_DMP</CODE> (<CODE>GL_UNSIGNED_BYTE</CODE>), <CODE>GL_HILO8_NATIVE_DMP</CODE> (<CODE>GL_UNSIGNED_BYTE</CODE>)</TD></TR></TABLE> 106For example, if the current depth buffer format is <CODE>GL_DEPTH24_STENCIL8_EXT</CODE>, the <SPAN class="argument">internalformat</SPAN> argument to <CODE>glCopyTexImage2D</CODE> must be either <CODE>GL_RGBA</CODE> or <CODE>GL_RGBA_NATIVE_DMP</CODE>. (Both have the same effect.) 107 </P><P> 108The following errors occur in this function. 109<TABLE><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>The <span class="argument">target</span> argument was set to an invalid GPU access region.</TD></TR><TR><TH><CODE>GL_INVALID_VALUE</CODE></TH><TD>The <span class="argument">width</span>, <span class="argument">height</span>, <span class="argument">border</span>, or <span class="argument">level</span> argument was set to an invalid value.</TD></TR><TR><TH><CODE>GL_INVALID_ENUM</CODE></TH><TD>The <span class="argument">internalformat</span> argument was set to a different format than the current color buffer.</TD></TR><TR><TH><CODE>GL_INVALID_ENUM</CODE></TH><TD>The texture format specified for <SPAN class="argument">internalformat</SPAN> does not correspond to the current depth buffer format.</TD></TR><TR><TH><CODE>GL_OUT_OF_MEMORY</CODE></TH><TD>Failed to allocate a texture data region.</TD></TR><TR><TH><CODE>GL_INVALID_FRAMEBUFFER_OPERATION</CODE></TH><TD>A color buffer has not been configured correctly for the current framebuffer.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>This function was called without any command-list objects bound.</TD></TR></TABLE></P></div> 110<h2>Revision History</h2> 111 <div class="section"> 112 <dl class="history"> 113 <dt>2010/09/15</dt> 114<dd>Added explanation of automatic mipmap generation to the <SPAN class="argument">level</SPAN> argument description. 115 </dd> 116 <dt>2010/08/12</dt> 117<dd>Explained the depth stencil copy feature.<br /> 118 </dd> 119 <dt>2010/07/07</dt> 120<dd>Changed description of <SPAN class="argument">width</SPAN> and <SPAN class="argument">height</SPAN> arguments. 121 </dd> 122 <dt>2010/01/07</dt> 123<dd>Initial version.<br /> 124 </dd> 125 </dl> 126 </div> 127 <hr><p>CONFIDENTIAL</p></body> 128</html>