upstream-man-pages/man4/glCopyImageSubData.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glCopyImageSubData">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCopyImageSubData</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCopyImageSubData</refname>
  17         <refpurpose>perform a raw data copy between two images</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCopyImageSubData</function></funcdef>
  23                 <paramdef>GLuint <parameter>srcName</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>srcTarget</parameter></paramdef>
  25                 <paramdef>GLint <parameter>srcLevel</parameter></paramdef>
  26                 <paramdef>GLint <parameter>srcX</parameter></paramdef>
  27                 <paramdef>GLint <parameter>srcY</parameter></paramdef>
  28                 <paramdef>GLint <parameter>srcZ</parameter></paramdef>
  29                 <paramdef>GLuint <parameter>dstName</parameter></paramdef>
  30                 <paramdef>GLenum <parameter>dstTarget</parameter></paramdef>
  31                 <paramdef>GLint <parameter>dstLevel</parameter></paramdef>
  32                 <paramdef>GLint <parameter>dstX</parameter></paramdef>
  33                 <paramdef>GLint <parameter>dstY</parameter></paramdef>
  34                 <paramdef>GLint <parameter>dstZ</parameter></paramdef>
  35                 <paramdef>GLsizei <parameter>srcWidth</parameter></paramdef>
  36                 <paramdef>GLsizei <parameter>srcHeight</parameter></paramdef>
  37                 <paramdef>GLsizei <parameter>srcDepth</parameter></paramdef>
  38             </funcprototype>
  39         </funcsynopsis>
  40     </refsynopsisdiv>
  41     <refsect1 id="parameters"><title>Parameters</title>
  42         <variablelist>
  43         <varlistentry>
  44             <term><parameter>srcName</parameter></term>
  45             <listitem>
  46                 <para>
  47                     The name of a texture or renderbuffer object from which to copy.
  48                 </para>
  49             </listitem>
  50         </varlistentry>
  51         <varlistentry>
  52             <term><parameter>srcTarget</parameter></term>
  53             <listitem>
  54                 <para>
  55                     The target representing the namespace of the source name <parameter>srcName</parameter>.
  56                 </para>
  57             </listitem>
  58         </varlistentry>
  59         <varlistentry>
  60             <term><parameter>srcLevel</parameter></term>
  61             <listitem>
  62                 <para>
  63                     The mipmap level to read from the source.
  64                 </para>
  65             </listitem>
  66         </varlistentry>
  67         <varlistentry>
  68             <term><parameter>srcX</parameter></term>
  69             <listitem>
  70                 <para>
  71                     The X coordinate of the left edge of the souce region to copy.
  72                 </para>
  73             </listitem>
  74         </varlistentry>
  75         <varlistentry>
  76             <term><parameter>srcY</parameter></term>
  77             <listitem>
  78                 <para>
  79                     The Y coordinate of the top edge of the souce region to copy.
  80                 </para>
  81             </listitem>
  82         </varlistentry>
  83         <varlistentry>
  84             <term><parameter>srcZ</parameter></term>
  85             <listitem>
  86                 <para>
  87                     The Z coordinate of the near edge of the souce region to copy.
  88                 </para>
  89             </listitem>
  90         </varlistentry>
  91         <varlistentry>
  92             <term><parameter>dstName</parameter></term>
  93             <listitem>
  94                 <para>
  95                     The name of a texture or renderbuffer object to which to copy.
  96                 </para>
  97             </listitem>
  98         </varlistentry>
  99         <varlistentry>
 100             <term><parameter>dstTarget</parameter></term>
 101             <listitem>
 102                 <para>
 103                     The target representing the namespace of the destination name <parameter>dstName</parameter>.
 104                 </para>
 105             </listitem>
 106         </varlistentry>
 107         <varlistentry>
 108             <term><parameter>dstX</parameter></term>
 109             <listitem>
 110                 <para>
 111                     The X coordinate of the left edge of the destination region.
 112                 </para>
 113             </listitem>
 114         </varlistentry>
 115         <varlistentry>
 116             <term><parameter>dstY</parameter></term>
 117             <listitem>
 118                 <para>
 119                     The Y coordinate of the top edge of the destination region.
 120                 </para>
 121             </listitem>
 122         </varlistentry>
 123         <varlistentry>
 124             <term><parameter>dstZ</parameter></term>
 125             <listitem>
 126                 <para>
 127                     The Z coordinate of the near edge of the destination region.
 128                 </para>
 129             </listitem>
 130         </varlistentry>
 131         <varlistentry>
 132             <term><parameter>srcWidth</parameter></term>
 133             <listitem>
 134                 <para>
 135                     The width of the region to be copied.
 136                 </para>
 137             </listitem>
 138         </varlistentry>
 139         <varlistentry>
 140             <term><parameter>srcHeight</parameter></term>
 141             <listitem>
 142                 <para>
 143                     The height of the region to be copied.
 144                 </para>
 145             </listitem>
 146         </varlistentry>
 147         <varlistentry>
 148             <term><parameter>srcDepth</parameter></term>
 149             <listitem>
 150                 <para>
 151                     The depth of the region to be copied.
 152                 </para>
 153             </listitem>
 154         </varlistentry>
 155         </variablelist>
 156     </refsect1>
 157     <refsect1 id="description"><title>Description</title>
 158         <para>
 159             <function>glCopyImageSubData</function> may be used to copy data from
 160             one image (i.e. texture or renderbuffer) to another. <function>glCopyImageSubData</function>
 161             does not perform general-purpose conversions
 162             such as scaling, resizing, blending, color-space, or format
 163             conversions. It should be considered to operate in a manner
 164             similar to a CPU memcpy. CopyImageSubData can copy between
 165             images with different internal formats, provided
 166             the formats are compatible.
 167         </para>
 168         <para>
 169             <function>glCopyImageSubData</function> also allows copying between certain
 170             types of compressed and uncompressed internal formats. This copy does not perform on-the-fly compression
 171             or decompression. When copying from an uncompressed internal format
 172             to a compressed internal format, each texel of uncompressed data
 173             becomes a single block of compressed data. When copying from a
 174             compressed internal format to an uncompressed internal format,
 175             a block of compressed data becomes a single texel of uncompressed
 176             data. The texel size of the uncompressed format must be the same
 177             size the block size of the compressed formats. Thus it is permitted
 178             to copy between a 128-bit uncompressed format and a compressed
 179             format which uses 8-bit 4x4 blocks, or between a 64-bit uncompressed
 180             format and a compressed format which uses 4-bit 4x4 blocks.
 181         </para>
 182         <para>
 183             The source object is identified by <parameter>srcName</parameter> and
 184             <parameter>srcTarget</parameter> and the destination object is identified
 185             by <parameter>dstName</parameter> and <parameter>dstTarget</parameter>.
 186             The interpretation of the name depends on the value
 187             of the corresponding <parameter>target</parameter> parameter.
 188             If <parameter>target</parameter> is
 189             <constant>GL_RENDERBUFFER</constant>, the name is interpreted as the name of a
 190             renderbuffer object.  If the target parameter is a texture target,
 191             the name is interpreted as a texture object.  All non-proxy
 192             texture targets are accepted, with the exception of <constant>GL_TEXTURE_BUFFER</constant>
 193             and the cubemap face selectors.
 194         </para>
 195         <para>
 196             <parameter>srcLevel</parameter> and <parameter>dstLevel</parameter> identify the source and destination
 197             level of detail.  For textures, this must be a valid level of
 198             detail in the texture object.  For renderbuffers, this value must
 199             be zero.
 200         </para>
 201         <para>
 202             <parameter>srcX</parameter>, <parameter>srcY</parameter>, and <parameter>srcZ</parameter> specify the lower left texel
 203             coordinates of a <parameter>srcWidth</parameter>-wide by <parameter>srcHeight</parameter>-high by
 204             <parameter>srcDepth</parameter>-deep rectangular subregion of the source texel array.
 205             Similarly, <parameter>dstX</parameter>, <parameter>dstY</parameter> and <parameter>dstZ</parameter> specify the coordinates of a subregion of the
 206             destination texel array.  The source and destination subregions
 207             must be contained entirely within the specified level of the
 208             corresponding image objects.
 209         </para>
 210         <para>
 211             The dimensions are always specified in texels, even for compressed
 212             texture formats. However, it should be noted that if only one of the
 213             source and destination textures is compressed then the number of
 214             texels touched in the compressed image will be a factor of the
 215             block size larger than in the uncompressed image.
 216         </para>
 217         <para>
 218             Slices of a <constant>GL_TEXTURE_1D_ARRAY</constant>, <constant>GL_TEXTURE_2D_ARRAY</constant>, <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>
 219             <constant>GL_TEXTURE_3D</constant> and faces of <constant>GL_TEXTURE_CUBE_MAP</constant> are all compatible provided
 220             they share a compatible internal format, and multiple slices or faces
 221             may be copied between these objects with a single call by specifying the
 222             starting slice with <parameter>srcZ</parameter> and <parameter>dstZ</parameter>, and the number of slices to
 223             be copied with <parameter>srcDepth</parameter>.  Cubemap textures always have six faces
 224             which are selected by a zero-based face index.
 225         </para>
 226         <para>
 227             For the purposes of CopyImageSubData, two internal formats
 228     are considered compatible if any of the following conditions are
 229     met:
 230      * the formats are the same,
 231      * the formats are considered compatible according to the
 232        compatibility rules used for texture views as defined in
 233        section 3.9.X. In particular, if both internal formats are listed
 234        in the same entry of Table 3.X.2, they are considered compatible, or
 235      * one format is compressed and the other is uncompressed and
 236        Table 4.X.1 lists the two formats in the same row.
 237     If the formats are not compatible INVALID_OPERATION is generated.
 238         </para>
 239 <table frame="topbot"><title>Sized Internal Formats</title>
 240 <tgroup cols="3" align="left">
 241     <colspec align="left"/>
 242     <colspec align="left"/>
 243     <colspec align="left"/>
 244     <thead>
 245         <row>
 246             <entry rowsep="1" align="left"><emphasis role="bold">
 247             Texel / Block Size
 248             </emphasis></entry>
 249             <entry rowsep="1" align="left"><emphasis role="bold">
 250             Uncompressed Internal Format
 251             </emphasis></entry>
 252             <entry rowsep="1" align="left"><emphasis role="bold">
 253             Compressed Internal Format(s)
 254             </emphasis></entry>
 255         </row>
 256     </thead>
 257     <tbody>
 258         <row>
 259             <entry>64-bit</entry>
 260             <entry><constant>GL_RGBA32UI</constant>, <constant>GL_RGBA32I</constant>, <constant>GL_RGBA32F</constant></entry>
 261             <entry><constant>GL_COMPRESSED_RGBA_S3TC_DXT3_EXT</constant>,
 262                    <constant>GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT3_EXT</constant>,
 263                    <constant>GL_COMPRESSED_RGBA_S3TC_DXT5_EXT</constant>,
 264                    <constant>GL_COMPRESSED_SRGB_ALPHA_S3TC_DXT5_EXT</constant>,
 265                    <constant>GL_COMPRESSED_RG_RGTC2</constant>,
 266                    <constant>GL_COMPRESSED_SIGNED_RG_RGTC2</constant>,
 267                    <constant>GL_COMPRESSED_RGBA_BPTC_UNORM</constant>,
 268                    <constant>GL_COMPRESSED_SRGB_ALPHA_BPTC_UNORM</constant>,
 269                    <constant>GL_COMPRESSED_RGB_BPTC_SIGNED_FLOAT</constant>,
 270                    <constant>GL_COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT</constant></entry>
 271         </row>
 272         <row>
 273             <entry>128-bit</entry>
 274             <entry><constant>GL_RGBA16UI</constant>,
 275                    <constant>GL_RGBA16I</constant>,
 276                    <constant>GL_RGBA16F</constant>,
 277                    <constant>GL_RG32F</constant>,
 278                    <constant>GL_RG32UI</constant>,
 279                    <constant>GL_RG32I</constant>,
 280                    <constant>GL_RGBA16</constant>,
 281                    <constant>GL_RGBA16_SNORM</constant></entry>
 282             <entry><constant>GL_COMPRESSED_RGB_S3TC_DXT1_EXT</constant>,
 283                    <constant>COMPRESSED_SRGB_S3TC_DXT1_EXT</constant>,
 284                    <constant>COMPRESSED_RGBA_S3TC_DXT1_EXT</constant>,
 285                    <constant>COMPRESSED_SRGB_ALPHA_S3TC_DXT1_EXT</constant>,
 286                    <constant>COMPRESSED_RED_RGTC1</constant>,
 287                    <constant>COMPRESSED_SIGNED_RED_RGTC1</constant></entry>
 288         </row>
 289     </tbody>
 290 </tgroup>
 291 </table>
 292     </refsect1>
 293     <refsect1 id="errors"><title>Errors</title>
 294         <para>
 295             <constant>GL_INVALID_OPERATION</constant> is generated if the texel size of
 296             the uncompressed image is not equal to the block size of the
 297             compressed image.
 298         </para>
 299         <para>
 300             <constant>GL_INVALID_ENUM</constant> is generated if either target parameter is not <constant>GL_RENDERBUFFER</constant>,
 301             a valid non-proxy texture target other than <constant>GL_TEXTURE_BUFFER</constant>, or is one
 302             of the cubemap face selectors.
 303         </para>
 304         <para>
 305             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> does not match the type of the object.
 306         </para>
 307         <para>
 308             <constant>GL_INVALID_OPERATION</constant> is generated if either object is a texture and the texture is
 309             not complete.
 310         </para>
 311         <para>
 312             <constant>GL_INVALID_OPERATION</constant> is generated if the source and
 313             destination internal formats are not compatible, or if the number of samples do not match.
 314         </para>
 315         <para>
 316             <constant>GL_INVALID_VALUE</constant> is generated if either name does not correspond to a
 317             valid renderbuffer or texture object according to the corresponding
 318             target parameter.
 319         </para>
 320         <para>
 321             <constant>GL_INVALID_VALUE</constant> is generated if the specified level of either the source or destination is not
 322             a valid level for the corresponding image.
 323         </para>
 324         <para>
 325             <constant>GL_INVALID_VALUE</constant> is generated if the
 326             dimensions of the either subregion exceeds the boundaries of the
 327             corresponding image object, or if the image format is compressed
 328             and the dimensions of the subregion fail to meet the alignment
 329             constraints of the format.
 330         </para>
 331     </refsect1>
 332     <refsect1 id="associatedgets"><title>Associated Gets</title>
 333         <para>
 334             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_COMPUTE_WORK_GROUP_COUNT</constant>
 335         </para>
 336     </refsect1>
 337     <refsect1 id="seealso"><title>See Also</title>
 338         <para>
 339             <citerefentry><refentrytitle>glDispatchComputeIndirect</refentrytitle></citerefentry>.
 340         </para>
 341     </refsect1>
 342     <refsect1 id="Copyright"><title>Copyright</title>
 343         <para>
 344             Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
 345             This material may be distributed subject to the terms and conditions set forth in
 346             the Open Publication License, v 1.0, 8 June 1999.
 347             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 348         </para>
 349     </refsect1>
 350 </refentry>