upstream-man-pages/man2/glCopyTexSubImage2D.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="glCopyTexSubImage2D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCopyTexSubImage2D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCopyTexSubImage2D</refname>
  17         <refpurpose>copy a two-dimensional texture subimage</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCopyTexSubImage2D</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>level</parameter></paramdef>
  25                 <paramdef>GLint <parameter>xoffset</parameter></paramdef>
  26                 <paramdef>GLint <parameter>yoffset</parameter></paramdef>
  27                 <paramdef>GLint <parameter>x</parameter></paramdef>
  28                 <paramdef>GLint <parameter>y</parameter></paramdef>
  29                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  30                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  31             </funcprototype>
  32         </funcsynopsis>
  33     </refsynopsisdiv>
  34     <!-- eqn: ignoring delim $$ -->
  35     <para>
  36     </para>
  37     <refsect1 id="parameters"><title>Parameters</title>
  38         <variablelist>
  39         <varlistentry>
  40             <term><parameter>target</parameter></term>
  41             <listitem>
  42                 <para>
  43                     Specifies the target texture.
  44                     Must be <constant>GL_TEXTURE_2D</constant>,
  45                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
  46                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
  47                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
  48                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
  49                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
  50                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
  51                 </para>
  52             </listitem>
  53         </varlistentry>
  54         <varlistentry>
  55             <term><parameter>level</parameter></term>
  56             <listitem>
  57                 <para>
  58                     Specifies the level-of-detail number.
  59                     Level 0 is the base image level.
  60                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  61                 </para>
  62             </listitem>
  63         </varlistentry>
  64         <varlistentry>
  65             <term><parameter>xoffset</parameter></term>
  66             <listitem>
  67                 <para>
  68                     Specifies a texel offset in the x direction within the texture array.
  69                 </para>
  70             </listitem>
  71         </varlistentry>
  72         <varlistentry>
  73             <term><parameter>yoffset</parameter></term>
  74             <listitem>
  75                 <para>
  76                     Specifies a texel offset in the y direction within the texture array.
  77                 </para>
  78             </listitem>
  79         </varlistentry>
  80         <varlistentry>
  81             <term><parameter>x</parameter></term>
  82             <term><parameter>y</parameter></term>
  83             <listitem>
  84                 <para>
  85                     Specify the window coordinates of the lower left corner
  86                     of the rectangular region of pixels to be copied.
  87                 </para>
  88             </listitem>
  89         </varlistentry>
  90         <varlistentry>
  91             <term><parameter>width</parameter></term>
  92             <listitem>
  93                 <para>
  94                     Specifies the width of the texture subimage.
  95                 </para>
  96             </listitem>
  97         </varlistentry>
  98         <varlistentry>
  99             <term><parameter>height</parameter></term>
 100             <listitem>
 101                 <para>
 102                     Specifies the height of the texture subimage.
 103                 </para>
 104             </listitem>
 105         </varlistentry>
 106         </variablelist>
 107     </refsect1>
 108     <refsect1 id="description"><title>Description</title>
 109         <para>
 110             <function>glCopyTexSubImage2D</function> replaces a rectangular portion of a two-dimensional texture image or
 111             cube-map texture image with pixels from the current <constant>GL_READ_BUFFER</constant>
 112             (rather than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>).
 113         </para>
 114         <para>
 115             The screen-aligned pixel rectangle with lower left corner at
 116             <inlineequation><mml:math>
 117                 <!-- eqn: (x, y):-->
 118                 <mml:mfenced open="(" close=")">
 119                     <mml:mi mathvariant="italic">x</mml:mi>
 120                     <mml:mi mathvariant="italic">y</mml:mi>
 121                 </mml:mfenced>
 122             </mml:math></inlineequation>
 123             and with
 124             width <parameter>width</parameter> and height <parameter>height</parameter> replaces the portion of the
 125             texture array with x indices <parameter>xoffset</parameter> through
 126             <inlineequation><mml:math>
 127                 <!-- eqn: xoffset  +  width  -  1:-->
 128                 <mml:mrow>
 129                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 130                     <mml:mo>+</mml:mo>
 131                     <mml:mi mathvariant="italic">width</mml:mi>
 132                     <mml:mo>-</mml:mo>
 133                     <mml:mn>1</mml:mn>
 134                 </mml:mrow>
 135             </mml:math></inlineequation>,
 136             inclusive, and y indices <parameter>yoffset</parameter> through
 137             <inlineequation><mml:math>
 138                 <!-- eqn: yoffset  +  height  -  1:-->
 139                 <mml:mrow>
 140                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 141                     <mml:mo>+</mml:mo>
 142                     <mml:mi mathvariant="italic">height</mml:mi>
 143                     <mml:mo>-</mml:mo>
 144                     <mml:mn>1</mml:mn>
 145                 </mml:mrow>
 146             </mml:math></inlineequation>,
 147             inclusive, at the mipmap level specified by <parameter>level</parameter>.
 148         </para>
 149         <para>
 150             The pixels in the rectangle are processed exactly as if
 151             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
 152             final conversion.
 153             At this point, all pixel component values are clamped to the range
 154             <inlineequation><mml:math>
 155                 <!-- eqn: [0,1]:-->
 156                 <mml:mfenced open="[" close="]">
 157                     <mml:mn>0</mml:mn>
 158                     <mml:mn>1</mml:mn>
 159                 </mml:mfenced>
 160             </mml:math></inlineequation>
 161             and then converted to the texture's internal format for storage in the texel
 162             array.
 163         </para>
 164         <para>
 165             The destination rectangle in the texture array may not include any texels
 166             outside the texture array as it was originally specified.
 167             It is not an error to specify a subtexture with zero width or height, but
 168             such a specification has no effect.
 169         </para>
 170         <para>
 171             If any of the pixels within the specified rectangle of the current
 172             <constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
 173             rendering context, then the values obtained for those pixels are undefined.
 174         </para>
 175         <para>
 176             No change is made to the <emphasis>internalformat</emphasis>, <emphasis>width</emphasis>,
 177             <emphasis>height</emphasis>, or <emphasis>border</emphasis> parameters of the specified texture
 178             array or to texel values outside the specified subregion.
 179         </para>
 180     </refsect1>
 181     <refsect1 id="notes"><title>Notes</title>
 182         <para>
 183             <function>glCopyTexSubImage2D</function> is available only if the GL version is 1.1 or greater.
 184         </para>
 185         <para>
 186             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 187             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 188             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 189             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 190             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 191             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
 192             <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant> are available only if the GL version is 1.3
 193             or greater.
 194         </para>
 195         <para>
 196             Texturing has no effect in color index mode.
 197         </para>
 198         <para>
 199             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
 200             in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
 201         </para>
 202         <para>
 203             When the <code>ARB_imaging</code> extension is supported, the RGBA components
 204             read from the framebuffer may be processed by the imaging pipeline.  See
 205             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
 206         </para>
 207     </refsect1>
 208     <refsect1 id="errors"><title>Errors</title>
 209         <para>
 210             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>,
 211             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 212             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 213             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 214             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 215             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
 216             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
 217         </para>
 218         <para>
 219             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not been
 220             defined by a previous <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry> operation.
 221         </para>
 222         <para>
 223             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 224         </para>
 225         <para>
 226             <constant>GL_INVALID_VALUE</constant> may be generated if
 227             <inlineequation><mml:math>
 228                 <!-- eqn: level  >  log sub 2(max):-->
 229                 <mml:mrow>
 230                     <mml:mi mathvariant="italic">level</mml:mi>
 231                     <mml:mo>&gt;</mml:mo>
 232                     <mml:mrow>
 233                         <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 234                         <mml:mn>2</mml:mn>
 235                         </mml:msub>
 236                         <mml:mo>&af;</mml:mo>
 237                         <mml:mfenced open="(" close=")">
 238                             <mml:mi mathvariant="italic">max</mml:mi>
 239                         </mml:mfenced>
 240                     </mml:mrow>
 241                 </mml:mrow>
 242             </mml:math></inlineequation>,
 243             where
 244             <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
 245             is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 246         </para>
 247         <para>
 248             <constant>GL_INVALID_VALUE</constant> is generated if
 249             <inlineequation><mml:math>
 250                 <!-- eqn: xoffset  <  -b:-->
 251                 <mml:mrow>
 252                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 253                     <mml:mo>&lt;</mml:mo>
 254                     <mml:mrow>
 255                         <mml:mo>-</mml:mo>
 256                         <mml:mi mathvariant="italic">b</mml:mi>
 257                     </mml:mrow>
 258                 </mml:mrow>
 259             </mml:math></inlineequation>,
 260             <inlineequation><mml:math>
 261                 <!-- eqn: (xoffset  +  width)  >  (w  -  b):-->
 262                 <mml:mrow>
 263                     <mml:mfenced open="(" close=")">
 264                         <mml:mrow>
 265                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 266                             <mml:mo>+</mml:mo>
 267                             <mml:mi mathvariant="italic">width</mml:mi>
 268                         </mml:mrow>
 269                     </mml:mfenced>
 270                     <mml:mo>&gt;</mml:mo>
 271                     <mml:mfenced open="(" close=")">
 272                         <mml:mrow>
 273                             <mml:mi mathvariant="italic">w</mml:mi>
 274                             <mml:mo>-</mml:mo>
 275                             <mml:mi mathvariant="italic">b</mml:mi>
 276                         </mml:mrow>
 277                     </mml:mfenced>
 278                 </mml:mrow>
 279             </mml:math></inlineequation>,
 280             <inlineequation><mml:math>
 281                 <!-- eqn: yoffset  <   -b:-->
 282                 <mml:mrow>
 283                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 284                     <mml:mo>&lt;</mml:mo>
 285                     <mml:mrow>
 286                         <mml:mo>-</mml:mo>
 287                         <mml:mi mathvariant="italic">b</mml:mi>
 288                     </mml:mrow>
 289                 </mml:mrow>
 290             </mml:math></inlineequation>,
 291             or
 292             <inlineequation><mml:math>
 293                 <!-- eqn: (yoffset  +  height)  >  (h  - b):-->
 294                 <mml:mrow>
 295                     <mml:mfenced open="(" close=")">
 296                         <mml:mrow>
 297                             <mml:mi mathvariant="italic">yoffset</mml:mi>
 298                             <mml:mo>+</mml:mo>
 299                             <mml:mi mathvariant="italic">height</mml:mi>
 300                         </mml:mrow>
 301                     </mml:mfenced>
 302                     <mml:mo>&gt;</mml:mo>
 303                     <mml:mfenced open="(" close=")">
 304                         <mml:mrow>
 305                             <mml:mi mathvariant="italic">h</mml:mi>
 306                             <mml:mo>-</mml:mo>
 307                             <mml:mi mathvariant="italic">b</mml:mi>
 308                         </mml:mrow>
 309                     </mml:mfenced>
 310                 </mml:mrow>
 311             </mml:math></inlineequation>,
 312             where
 313             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 314             is the <constant>GL_TEXTURE_WIDTH</constant>,
 315             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 316             is the <constant>GL_TEXTURE_HEIGHT</constant>,
 317             and
 318             <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 319             is the <constant>GL_TEXTURE_BORDER</constant>
 320             of the texture image being modified.
 321             Note that
 322             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 323             and
 324             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 325             include twice the border width.
 326         </para>
 327         <para>
 328             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glCopyTexSubImage2D</function> is executed
 329             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 330             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 331         </para>
 332     </refsect1>
 333     <refsect1 id="associatedgets"><title>Associated Gets</title>
 334         <para>
 335             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 336         </para>
 337         <para>
 338             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant>
 339         </para>
 340     </refsect1>
 341     <refsect1 id="seealso"><title>See Also</title>
 342         <para>
 343             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 344             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 345             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 346             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 347             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 348             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 349             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
 350             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
 351             <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
 352             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 353             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 354             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 355             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 356             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 357             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 358             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 359             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
 360         </para>
 361     </refsect1>
 362     <refsect1 id="Copyright"><title>Copyright</title>
 363         <para>
 364             Copyright <trademark class="copyright"></trademark> 1991-2006
 365             Silicon Graphics, Inc. This document is licensed under the SGI
 366             Free Software B License. For details, see
 367             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 368         </para>
 369     </refsect1>
 370 </refentry>