upstream-doc/man3/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>glReadPixels</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> or
 177             <emphasis>height</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             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> modes affect texture images.
 184         </para>
 185     </refsect1>
 186     <refsect1 id="errors"><title>Errors</title>
 187         <para>
 188             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>,
 189             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 190             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 191             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 192             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 193             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 194             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
 195             <constant>GL_TEXTURE_1D_ARRAY</constant>.
 196         </para>
 197         <para>
 198             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not been
 199             defined by a previous <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry> operation.
 200         </para>
 201         <para>
 202             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 203         </para>
 204         <para>
 205             <constant>GL_INVALID_VALUE</constant> may be generated if
 206             <inlineequation><mml:math>
 207                 <!-- eqn: level  >  log sub 2(max): -->
 208                 <mml:mrow>
 209                     <mml:mi mathvariant="italic">level</mml:mi>
 210                     <mml:mo>&gt;</mml:mo>
 211                     <mml:mrow>
 212                         <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 213                         <mml:mn>2</mml:mn>
 214                         </mml:msub>
 215                         <mml:mo>&af;</mml:mo>
 216                         <mml:mfenced open="(" close=")">
 217                             <mml:mi mathvariant="italic">max</mml:mi>
 218                         </mml:mfenced>
 219                     </mml:mrow>
 220                 </mml:mrow>
 221             </mml:math></inlineequation>,
 222             where
 223             <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
 224             is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 225         </para>
 226         <para>
 227             <constant>GL_INVALID_VALUE</constant> is generated if
 228             <inlineequation><mml:math>
 229                 <!-- eqn: xoffset  <  -b: -->
 230                 <mml:mrow>
 231                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 232                     <mml:mo>&lt;</mml:mo>
 233                     <mml:mn>0</mml:mn>
 234                 </mml:mrow>
 235             </mml:math></inlineequation>,
 236             <inlineequation><mml:math>
 237                 <!-- eqn: (xoffset  +  width)  >  (w  -  b): -->
 238                 <mml:mrow>
 239                     <mml:mfenced open="(" close=")">
 240                         <mml:mrow>
 241                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 242                             <mml:mo>+</mml:mo>
 243                             <mml:mi mathvariant="italic">width</mml:mi>
 244                         </mml:mrow>
 245                     </mml:mfenced>
 246                     <mml:mo>&gt;</mml:mo>
 247                     <mml:mrow>
 248                         <mml:mi mathvariant="italic">w</mml:mi>
 249                     </mml:mrow>
 250                 </mml:mrow>
 251             </mml:math></inlineequation>,
 252             <inlineequation><mml:math>
 253                 <!-- eqn: yoffset  <   -b: -->
 254                 <mml:mrow>
 255                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 256                     <mml:mo>&lt;</mml:mo>
 257                     <mml:mn>0</mml:mn>
 258                 </mml:mrow>
 259             </mml:math></inlineequation>,
 260             or
 261             <inlineequation><mml:math>
 262                 <!-- eqn: (yoffset  +  height)  >  (h  - b): -->
 263                 <mml:mrow>
 264                     <mml:mfenced open="(" close=")">
 265                         <mml:mrow>
 266                             <mml:mi mathvariant="italic">yoffset</mml:mi>
 267                             <mml:mo>+</mml:mo>
 268                             <mml:mi mathvariant="italic">height</mml:mi>
 269                         </mml:mrow>
 270                     </mml:mfenced>
 271                     <mml:mo>&gt;</mml:mo>
 272                     <mml:mi mathvariant="italic">h</mml:mi>
 273                 </mml:mrow>
 274             </mml:math></inlineequation>,
 275             where
 276             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 277             is the <constant>GL_TEXTURE_WIDTH</constant>, and
 278             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 279             is the <constant>GL_TEXTURE_HEIGHT</constant>
 280             of the texture image being modified.
 281         </para>
 282     </refsect1>
 283     <refsect1 id="associatedgets"><title>Associated Gets</title>
 284         <para>
 285             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 286         </para>
 287     </refsect1>
 288     <refsect1 id="seealso"><title>See Also</title>
 289         <para>
 290             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 291             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 292             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 293             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 294             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 295             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
 296             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 297             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 298             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 299             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 300             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 301             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 302             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
 303         </para>
 304     </refsect1>
 305     <refsect1 id="Copyright"><title>Copyright</title>
 306         <para>
 307             Copyright <trademark class="copyright"></trademark> 1991-2006
 308             Silicon Graphics, Inc. This document is licensed under the SGI
 309             Free Software B License. For details, see
 310             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 311         </para>
 312     </refsect1>
 313 </refentry>