Commit | Line | Data |
---|---|---|
7faf1d71 AW |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd"> | |
3 | <!-- saved from url=(0013)about:internet --> | |
4 | <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glCopyImageSubData - OpenGL 4 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glCopyImageSubData"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glCopyImageSubData — perform a raw data copy between two images</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glCopyImageSubData</b>(</code></td><td>GLuint </td><td><var class="pdparam">srcName</var>, </td></tr><tr><td> </td><td>GLenum </td><td><var class="pdparam">srcTarget</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">srcLevel</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">srcX</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">srcY</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">srcZ</var>, </td></tr><tr><td> </td><td>GLuint </td><td><var class="pdparam">dstName</var>, </td></tr><tr><td> </td><td>GLenum </td><td><var class="pdparam">dstTarget</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">dstLevel</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">dstX</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">dstY</var>, </td></tr><tr><td> </td><td>GLint </td><td><var class="pdparam">dstZ</var>, </td></tr><tr><td> </td><td>GLsizei </td><td><var class="pdparam">srcWidth</var>, </td></tr><tr><td> </td><td>GLsizei </td><td><var class="pdparam">srcHeight</var>, </td></tr><tr><td> </td><td>GLsizei </td><td><var class="pdparam">srcDepth</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>srcName</code></em></span></dt><dd><p> | |
5 | The name of a texture or renderbuffer object from which to copy. | |
6 | </p></dd><dt><span class="term"><em class="parameter"><code>srcTarget</code></em></span></dt><dd><p> | |
7 | The target representing the namespace of the source name <em class="parameter"><code>srcName</code></em>. | |
8 | </p></dd><dt><span class="term"><em class="parameter"><code>srcLevel</code></em></span></dt><dd><p> | |
9 | The mipmap level to read from the source. | |
10 | </p></dd><dt><span class="term"><em class="parameter"><code>srcX</code></em></span></dt><dd><p> | |
11 | The X coordinate of the left edge of the souce region to copy. | |
12 | </p></dd><dt><span class="term"><em class="parameter"><code>srcY</code></em></span></dt><dd><p> | |
13 | The Y coordinate of the top edge of the souce region to copy. | |
14 | </p></dd><dt><span class="term"><em class="parameter"><code>srcZ</code></em></span></dt><dd><p> | |
15 | The Z coordinate of the near edge of the souce region to copy. | |
16 | </p></dd><dt><span class="term"><em class="parameter"><code>dstName</code></em></span></dt><dd><p> | |
17 | The name of a texture or renderbuffer object to which to copy. | |
18 | </p></dd><dt><span class="term"><em class="parameter"><code>dstTarget</code></em></span></dt><dd><p> | |
19 | The target representing the namespace of the destination name <em class="parameter"><code>dstName</code></em>. | |
20 | </p></dd><dt><span class="term"><em class="parameter"><code>dstX</code></em></span></dt><dd><p> | |
21 | The X coordinate of the left edge of the destination region. | |
22 | </p></dd><dt><span class="term"><em class="parameter"><code>dstY</code></em></span></dt><dd><p> | |
23 | The Y coordinate of the top edge of the destination region. | |
24 | </p></dd><dt><span class="term"><em class="parameter"><code>dstZ</code></em></span></dt><dd><p> | |
25 | The Z coordinate of the near edge of the destination region. | |
26 | </p></dd><dt><span class="term"><em class="parameter"><code>srcWidth</code></em></span></dt><dd><p> | |
27 | The width of the region to be copied. | |
28 | </p></dd><dt><span class="term"><em class="parameter"><code>srcHeight</code></em></span></dt><dd><p> | |
29 | The height of the region to be copied. | |
30 | </p></dd><dt><span class="term"><em class="parameter"><code>srcDepth</code></em></span></dt><dd><p> | |
31 | The depth of the region to be copied. | |
32 | </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p> | |
33 | <code class="function">glCopyImageSubData</code> may be used to copy data from | |
34 | one image (i.e. texture or renderbuffer) to another. <code class="function">glCopyImageSubData</code> | |
35 | does not perform general-purpose conversions | |
36 | such as scaling, resizing, blending, color-space, or format | |
37 | conversions. It should be considered to operate in a manner | |
38 | similar to a CPU memcpy. CopyImageSubData can copy between | |
39 | images with different internal formats, provided | |
40 | the formats are compatible. | |
41 | </p><p> | |
42 | <code class="function">glCopyImageSubData</code> also allows copying between certain | |
43 | types of compressed and uncompressed internal formats. This copy does not perform on-the-fly compression | |
44 | or decompression. When copying from an uncompressed internal format | |
45 | to a compressed internal format, each texel of uncompressed data | |
46 | becomes a single block of compressed data. When copying from a | |
47 | compressed internal format to an uncompressed internal format, | |
48 | a block of compressed data becomes a single texel of uncompressed | |
49 | data. The texel size of the uncompressed format must be the same | |
50 | size the block size of the compressed formats. Thus it is permitted | |
51 | to copy between a 128-bit uncompressed format and a compressed | |
52 | format which uses 8-bit 4x4 blocks, or between a 64-bit uncompressed | |
53 | format and a compressed format which uses 4-bit 4x4 blocks. | |
54 | </p><p> | |
55 | The source object is identified by <em class="parameter"><code>srcName</code></em> and | |
56 | <em class="parameter"><code>srcTarget</code></em> and the destination object is identified | |
57 | by <em class="parameter"><code>dstName</code></em> and <em class="parameter"><code>dstTarget</code></em>. | |
58 | The interpretation of the name depends on the value | |
59 | of the corresponding <em class="parameter"><code>target</code></em> parameter. | |
60 | If <em class="parameter"><code>target</code></em> is | |
61 | <code class="constant">GL_RENDERBUFFER</code>, the name is interpreted as the name of a | |
62 | renderbuffer object. If the target parameter is a texture target, | |
63 | the name is interpreted as a texture object. All non-proxy | |
64 | texture targets are accepted, with the exception of <code class="constant">GL_TEXTURE_BUFFER</code> | |
65 | and the cubemap face selectors. | |
66 | </p><p> | |
67 | <em class="parameter"><code>srcLevel</code></em> and <em class="parameter"><code>dstLevel</code></em> identify the source and destination | |
68 | level of detail. For textures, this must be a valid level of | |
69 | detail in the texture object. For renderbuffers, this value must | |
70 | be zero. | |
71 | </p><p> | |
72 | <em class="parameter"><code>srcX</code></em>, <em class="parameter"><code>srcY</code></em>, and <em class="parameter"><code>srcZ</code></em> specify the lower left texel | |
73 | coordinates of a <em class="parameter"><code>srcWidth</code></em>-wide by <em class="parameter"><code>srcHeight</code></em>-high by | |
74 | <em class="parameter"><code>srcDepth</code></em>-deep rectangular subregion of the source texel array. | |
75 | Similarly, <em class="parameter"><code>dstX</code></em>, <em class="parameter"><code>dstY</code></em> and <em class="parameter"><code>dstZ</code></em> specify the coordinates of a subregion of the | |
76 | destination texel array. The source and destination subregions | |
77 | must be contained entirely within the specified level of the | |
78 | corresponding image objects. | |
79 | </p><p> | |
80 | The dimensions are always specified in texels, even for compressed | |
81 | texture formats. However, it should be noted that if only one of the | |
82 | source and destination textures is compressed then the number of | |
83 | texels touched in the compressed image will be a factor of the | |
84 | block size larger than in the uncompressed image. | |
85 | </p><p> | |
86 | Slices of a <code class="constant">GL_TEXTURE_1D_ARRAY</code>, <code class="constant">GL_TEXTURE_2D_ARRAY</code>, <code class="constant">GL_TEXTURE_CUBE_MAP_ARRAY</code> | |
87 | <code class="constant">GL_TEXTURE_3D</code> and faces of <code class="constant">GL_TEXTURE_CUBE_MAP</code> are all compatible provided | |
88 | they share a compatible internal format, and multiple slices or faces | |
89 | may be copied between these objects with a single call by specifying the | |
90 | starting slice with <em class="parameter"><code>srcZ</code></em> and <em class="parameter"><code>dstZ</code></em>, and the number of slices to | |
91 | be copied with <em class="parameter"><code>srcDepth</code></em>. Cubemap textures always have six faces | |
92 | which are selected by a zero-based face index. | |
93 | </p><p> | |
94 | For the purposes of CopyImageSubData, two internal formats | |
95 | are considered compatible if any of the following conditions are | |
96 | met: | |
97 | * the formats are the same, | |
98 | * the formats are considered compatible according to the | |
99 | compatibility rules used for texture views as defined in | |
100 | section 3.9.X. In particular, if both internal formats are listed | |
101 | in the same entry of Table 3.X.2, they are considered compatible, or | |
102 | * one format is compressed and the other is uncompressed and | |
103 | Table 4.X.1 lists the two formats in the same row. | |
104 | If the formats are not compatible INVALID_OPERATION is generated. | |
105 | </p><div class="table"><a id="id4818015"></a><p class="title"><b>Table 1. Sized Internal Formats</b></p><table summary="Sized Internal Formats" border="1"><colgroup><col align="left" /><col align="left" /><col align="left" /></colgroup><thead><tr><th align="left"><span class="bold"><strong> | |
106 | Texel / Block Size | |
107 | </strong></span></th><th align="left"><span class="bold"><strong> | |
108 | Uncompressed Internal Format | |
109 | </strong></span></th><th align="left"><span class="bold"><strong> | |
110 | Compressed Internal Format(s) | |
111 | </strong></span></th></tr></thead><tbody><tr><td align="left">64-bit</td><td align="left"><code class="constant">GL_RGBA32UI</code>, <code class="constant">GL_RGBA32I</code>, <code class="constant">GL_RGBA32F</code></td><td align="left"><code class="constant">GL_COMPRESSED_RGBA_S3TC_DXT3_EXT</code>, | |
112 | <code class="constant">GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT</code>, | |
113 | <code class="constant">GL_COMPRESSED_RGBA_S3TC_DXT5_EXT</code>, | |
114 | <code class="constant">GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT</code>, | |
115 | <code class="constant">GL_COMPRESSED_RG_RGTC2</code>, | |
116 | <code class="constant">GL_COMPRESSED_SIGNED_RG_RGTC2</code>, | |
117 | <code class="constant">GL_COMPRESSED_RGBA_BPTC_UNORM</code>, | |
118 | <code class="constant">GL_COMPRESSED_SRGB_ALPHA_BPTC_UNORM</code>, | |
119 | <code class="constant">GL_COMPRESSED_RGB_BPTC_SIGNED_FLOAT</code>, | |
120 | <code class="constant">GL_COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT</code></td></tr><tr><td align="left">128-bit</td><td align="left"><code class="constant">GL_RGBA16UI</code>, | |
121 | <code class="constant">GL_RGBA16I</code>, | |
122 | <code class="constant">GL_RGBA16F</code>, | |
123 | <code class="constant">GL_RG32F</code>, | |
124 | <code class="constant">GL_RG32UI</code>, | |
125 | <code class="constant">GL_RG32I</code>, | |
126 | <code class="constant">GL_RGBA16</code>, | |
127 | <code class="constant">GL_RGBA16_SNORM</code></td><td align="left"><code class="constant">GL_COMPRESSED_RGB_S3TC_DXT1_EXT</code>, | |
128 | <code class="constant">COMPRESSED_SRGB_S3TC_DXT1_EXT</code>, | |
129 | <code class="constant">COMPRESSED_RGBA_S3TC_DXT1_EXT</code>, | |
130 | <code class="constant">COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT</code>, | |
131 | <code class="constant">COMPRESSED_RED_RGTC1</code>, | |
132 | <code class="constant">COMPRESSED_SIGNED_RED_RGTC1</code></td></tr></tbody></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p> | |
133 | <code class="constant">GL_INVALID_OPERATION</code> is generated if the texel size of | |
134 | the uncompressed image is not equal to the block size of the | |
135 | compressed image. | |
136 | </p><p> | |
137 | <code class="constant">GL_INVALID_ENUM</code> is generated if either target parameter is not <code class="constant">GL_RENDERBUFFER</code>, | |
138 | a valid non-proxy texture target other than <code class="constant">GL_TEXTURE_BUFFER</code>, or is one | |
139 | of the cubemap face selectors. | |
140 | </p><p> | |
141 | <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> does not match the type of the object. | |
142 | </p><p> | |
143 | <code class="constant">GL_INVALID_OPERATION</code> is generated if either object is a texture and the texture is | |
144 | not complete. | |
145 | </p><p> | |
146 | <code class="constant">GL_INVALID_OPERATION</code> is generated if the source and | |
147 | destination internal formats are not compatible, or if the number of samples do not match. | |
148 | </p><p> | |
149 | <code class="constant">GL_INVALID_VALUE</code> is generated if either name does not correspond to a | |
150 | valid renderbuffer or texture object according to the corresponding | |
151 | target parameter. | |
152 | </p><p> | |
153 | <code class="constant">GL_INVALID_VALUE</code> is generated if the specified level of either the source or destination is not | |
154 | a valid level for the corresponding image. | |
155 | </p><p> | |
156 | <code class="constant">GL_INVALID_VALUE</code> is generated if the | |
157 | dimensions of the either subregion exceeds the boundaries of the | |
158 | corresponding image object, or if the image format is compressed | |
159 | and the dimensions of the subregion fail to meet the alignment | |
160 | constraints of the format. | |
161 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p> | |
162 | <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_MAX_COMPUTE_WORK_GROUP_COUNT</code> | |
163 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p> | |
164 | <a href="glDispatchComputeIndirect.xml"><span class="citerefentry"><span class="refentrytitle">glDispatchComputeIndirect</span></span></a>. | |
165 | </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p> | |
166 | Copyright <span class="trademark"></span>© 2012 Khronos Group. | |
167 | This material may be distributed subject to the terms and conditions set forth in | |
168 | the Open Publication License, v 1.0, 8 June 1999. | |
169 | <a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>. | |
170 | </p></div></div></body></html> |