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>glCopyTexSubImage2D</title>
8  </head>
9  <body>
10<h1><CODE>glCopyTexSubImage2D</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14GL_APICALL void GL_APIENTRY glCopyTexSubImage2D(
15     GLenum target,
16     GLint level,
17     GLint xoffset,
18     GLint yoffset,
19     GLint x,
20     GLint y,
21     GLsizei width,
22     GLsizei height
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>xoffset</th>
49<td>X coordinate at the lower-left corner of the partial texture region to copy to.</td>
50        </tr>
51        <tr>
52<td>in</td>
53<th>yoffset</th>
54<td>Y coordinate at the lower-left corner of the partial texture region to copy to.</td>
55        </tr>
56        <tr>
57<td>in</td>
58<th>x</th>
59<td>X coordinate at the lower-left corner of the color buffer's copy region.</td>
60        </tr>
61        <tr>
62<td>in</td>
63<th>y</th>
64<td>Y coordinate at the lower-left corner of the color buffer's copy region.</td>
65        </tr>
66        <tr>
67<td>in</td>
68<th>width</th>
69<td>Width of the region read from the color buffer.</td>
70        </tr>
71        <tr>
72<td>in</td>
73<th>height</th>
74<td>Height of the region read from the color buffer.</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>Partially copies the content of the current color buffer into texture data.</p><P>
82Use this function to copy only a portion of the image processed by the <CODE>glCopyTexImage2D</CODE> function. The texture image must be created using the <CODE>glTexImage2D</CODE> function before you can call this function.
83            </P><P>
84You can set <SPAN class="argument">target</SPAN> to one of the following values.
85<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><!-- source                      targetにはGL_TEXTURE_2DまたはGL_TEXTURE_CUBE_MAP_NEGATIVE_X、GL_TEXTURE_CUBE_MAP_POSITIVE_X、 GL_TEXTURE_CUBE_MAP_NEGATIVE_Y、GL_TEXTURE_CUBE_MAP_POSITIVE_Y、GL_TEXTURE_CUBE_MAP_NEGATIVE_Z、GL_TEXTURE_CUBE_MAP_POSITIVE_Zが指定できます。                 --></P><P>
86When 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.
87<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>
88Specifying 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. When <CODE>GL_GENERATE_MIPMAP</CODE> is <CODE>TRUE</CODE>, you must specify the same value for <SPAN class="argument">level</SPAN> as was specified in the previous call to <CODE>TexImage2D</CODE> or <CODE>CopyTexImage2D</CODE>. Specifying a different value for <SPAN class="argument">level</SPAN> causes an error. When <CODE>GL_GENERATE_MIPMAP</CODE> is <CODE>FALSE</CODE>, you must specify <CODE>0</CODE> for <SPAN class="argument">level</SPAN>. Any other value causes an error.
89            </P><P>
90You must set <span class="argument">xoffset</span>, <span class="argument">yoffset</span>, <span class="argument">x</span>, <span class="argument">y</span>, <span class="argument">width</span>, and <span class="argument">height</span> to multiples of 8.
91            </P><P>
92You 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.
93            </P><P>
94The 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.
95<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></P><P>
96The following errors occur in this function.
97<TABLE><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_VALUE</CODE></TH><TD>The <span class="argument">xoffset</span>, <span class="argument">yoffset</span>, <span class="argument">x</span>, <span class="argument">y</span>, <span class="argument">width</span>, or <span class="argument">height</span> argument was set to an invalid value; the sum of <span class="argument">xoffset</span> and <span class="argument">width</span> exceeds the width (in pixels) of the color buffer; or the sum of <span class="argument">yoffset</span> and <span class="argument">height</span> exceeds the height (in pixels) of the color buffer.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>The <span class="argument">level</span> argument was set to an invalid value.</TD></TR><TR><TH><CODE>GL_INVALID_ENUM</CODE></TH><TD><SPAN class="argument">target</SPAN> was set to an invalid value.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>This function was called without any command-list objects bound.</TD></TR><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>This function was called on a texture object with a texture format that does not correspond to the current depth buffer format.</TD></TR></TABLE><!-- source                      カレントのフレームバッファにカラーバッファが正しく設定されていない場合エラーGL_INVALID_FRAMEBUFFER_OPERATIONを生成します。 xoffset、yoffset、x、y、width、heightに不正な値を指定した場合、および xoffset＋widthがカラーバッファの横幅のピクセル数を超える場合、および yoffset＋heightがカラーバッファの縦幅のピクセル数を超える場合エラーGL_INVALID_VALUEを生成します。 levelに不正な値を指定した場合エラーGL_INVALID_OPERATIONを生成します。 targetに不正な値を指定した場合エラーGL_INVALID_ENUMを生成します。 コマンドリストオブジェクトをバインドしていない状態で呼び出すとエラーGL_INVALID_OPERATIONを生成します。                 --></P></div>
98<h2>Revision History</h2>
99    <div class="section">
100      <dl class="history">
101        <dt>2010/09/18</dt>
102<dd>Explained that a texture must first be generated using the <CODE>glTexImage2D</CODE> function.
103        </dd>
104        <dt>2010/09/15</dt>
105<dd>Added explanation of automatic mipmap generation to the <SPAN class="argument">level</SPAN> argument description.
106        </dd>
107        <dt>2010/08/12</dt>
108<dd>Explained the depth stencil copy feature.<br />
109        </dd>
110        <dt>2010/01/07</dt>
111<dd>Initial version.<br />
112        </dd>
113      </dl>
114    </div>
115  <hr><p>CONFIDENTIAL</p></body>
116</html>