upstream-doc/man2/glTexSubImage2D.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="glTexSubImage2D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glTexSubImage2D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glTexSubImage2D</refname>
  17         <refpurpose>specify a two-dimensional texture subimage</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glTexSubImage2D</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>GLsizei <parameter>width</parameter></paramdef>
  28                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  29                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  30                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  31                 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <!-- eqn: ignoring delim $$ -->
  36     <para>
  37     </para>
  38     <refsect1 id="parameters"><title>Parameters</title>
  39         <variablelist>
  40         <varlistentry>
  41             <term><parameter>target</parameter></term>
  42             <listitem>
  43                 <para>
  44                     Specifies the target texture.
  45                     Must be <constant>GL_TEXTURE_2D</constant>,
  46                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
  47                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
  48                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
  49                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
  50                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
  51                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
  52                 </para>
  53             </listitem>
  54         </varlistentry>
  55         <varlistentry>
  56             <term><parameter>level</parameter></term>
  57             <listitem>
  58                 <para>
  59                     Specifies the level-of-detail number.
  60                     Level 0 is the base image level.
  61                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  62                 </para>
  63             </listitem>
  64         </varlistentry>
  65         <varlistentry>
  66             <term><parameter>xoffset</parameter></term>
  67             <listitem>
  68                 <para>
  69                     Specifies a texel offset in the x direction within the texture array.
  70                 </para>
  71             </listitem>
  72         </varlistentry>
  73         <varlistentry>
  74             <term><parameter>yoffset</parameter></term>
  75             <listitem>
  76                 <para>
  77                     Specifies a texel offset in the y direction within the texture array.
  78                 </para>
  79             </listitem>
  80         </varlistentry>
  81         <varlistentry>
  82             <term><parameter>width</parameter></term>
  83             <listitem>
  84                 <para>
  85                     Specifies the width of the texture subimage.
  86                 </para>
  87             </listitem>
  88         </varlistentry>
  89         <varlistentry>
  90             <term><parameter>height</parameter></term>
  91             <listitem>
  92                 <para>
  93                     Specifies the height of the texture subimage.
  94                 </para>
  95             </listitem>
  96         </varlistentry>
  97         <varlistentry>
  98             <term><parameter>format</parameter></term>
  99             <listitem>
 100                 <para>
 101                     Specifies the format of the pixel data.
 102                     The following symbolic values are accepted:
 103                     <constant>GL_COLOR_INDEX</constant>,
 104                     <constant>GL_RED</constant>,
 105                     <constant>GL_GREEN</constant>,
 106                     <constant>GL_BLUE</constant>,
 107                     <constant>GL_ALPHA</constant>,
 108                     <constant>GL_RGB</constant>,
 109                     <constant>GL_BGR</constant>,
 110                     <constant>GL_RGBA</constant>,
 111                     <constant>GL_BGRA</constant>,
 112                     <constant>GL_LUMINANCE</constant>, and
 113                     <constant>GL_LUMINANCE_ALPHA</constant>.
 114                 </para>
 115             </listitem>
 116         </varlistentry>
 117         <varlistentry>
 118             <term><parameter>type</parameter></term>
 119             <listitem>
 120                 <para>
 121                     Specifies the data type of the pixel data.
 122                     The following symbolic values are accepted:
 123                     <constant>GL_UNSIGNED_BYTE</constant>,
 124                     <constant>GL_BYTE</constant>,
 125                     <constant>GL_BITMAP</constant>,
 126                     <constant>GL_UNSIGNED_SHORT</constant>,
 127                     <constant>GL_SHORT</constant>,
 128                     <constant>GL_UNSIGNED_INT</constant>,
 129                     <constant>GL_INT</constant>,
 130                     <constant>GL_FLOAT</constant>,
 131                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 132                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 133                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 134                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 135                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 136                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 137                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 138                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 139                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 140                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 141                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 142                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
 143                 </para>
 144             </listitem>
 145         </varlistentry>
 146         <varlistentry>
 147             <term><parameter>data</parameter></term>
 148             <listitem>
 149                 <para>
 150                     Specifies a pointer to the image data in memory.
 151                 </para>
 152             </listitem>
 153         </varlistentry>
 154         </variablelist>
 155     </refsect1>
 156     <refsect1 id="description"><title>Description</title>
 157         <para>
 158             Texturing maps a portion of a specified texture image
 159             onto each graphical primitive for which texturing is enabled.
 160             To enable and disable two-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
 161             and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant>.
 162         </para>
 163         <para>
 164             <function>glTexSubImage2D</function> redefines a contiguous subregion of an existing two-dimensional
 165             texture image.
 166             The texels referenced by <parameter>data</parameter> replace the portion of the
 167             existing texture array with x indices <parameter>xoffset</parameter> and
 168             <inlineequation><mml:math>
 169                 <!-- eqn: xoffset + width - 1:-->
 170                 <mml:mrow>
 171                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 172                     <mml:mo>+</mml:mo>
 173                     <mml:mi mathvariant="italic">width</mml:mi>
 174                     <mml:mo>-</mml:mo>
 175                     <mml:mn>1</mml:mn>
 176                 </mml:mrow>
 177             </mml:math></inlineequation>,
 178             inclusive,
 179             and y indices <parameter>yoffset</parameter> and
 180             <inlineequation><mml:math>
 181                 <!-- eqn: yoffset + height - 1:-->
 182                 <mml:mrow>
 183                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 184                     <mml:mo>+</mml:mo>
 185                     <mml:mi mathvariant="italic">height</mml:mi>
 186                     <mml:mo>-</mml:mo>
 187                     <mml:mn>1</mml:mn>
 188                 </mml:mrow>
 189             </mml:math></inlineequation>,
 190             inclusive.
 191             This region may not include any texels outside the range of the
 192             texture array as it was originally specified.
 193             It is not an error to specify a subtexture with zero width or height, but
 194             such a specification has no effect.
 195         </para>
 196         <para>
 197             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 198             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 199             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 200         </para>
 201     </refsect1>
 202     <refsect1 id="notes"><title>Notes</title>
 203         <para>
 204             <function>glTexSubImage2D</function> is available only if the GL version is 1.1 or greater.
 205         </para>
 206         <para>
 207             Texturing has no effect in color index mode.
 208         </para>
 209         <para>
 210             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
 211             in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
 212         </para>
 213         <para>
 214             Formats <constant>GL_BGR</constant>, and <constant>GL_BGRA</constant> and types
 215             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 216             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 217             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 218             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 219             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 220             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 221             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 222             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 223             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 224             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 225             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 226             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant> are available only if the GL version
 227             is 1.2 or greater.
 228         </para>
 229         <para>
 230             For OpenGL versions 1.3 and greater, or when the <code>ARB_multitexture</code> extension is supported, <function>glTexSubImage2D</function>
 231             specifies a two-dimensional subtexture for the current texture unit,
 232             specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
 233         </para>
 234         <para>
 235             When the <code>ARB_imaging</code> extension is supported, the RGBA components
 236             specified in <parameter>data</parameter> may be processed by the imaging pipeline.  See
 237             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
 238         </para>
 239     </refsect1>
 240     <refsect1 id="errors"><title>Errors</title>
 241         <para>
 242             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>,
 243             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 244             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 245             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 246             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 247             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
 248             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
 249         </para>
 250         <para>
 251             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not an accepted
 252             format constant.
 253         </para>
 254         <para>
 255             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not a type constant.
 256         </para>
 257         <para>
 258             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is <constant>GL_BITMAP</constant> and
 259             <parameter>format</parameter> is not <constant>GL_COLOR_INDEX</constant>.
 260         </para>
 261         <para>
 262             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 263         </para>
 264         <para>
 265             <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
 266             than
 267             <inlineequation><mml:math>
 268                 <!-- eqn: log sub 2:-->
 269                 <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 270                 <mml:mn>2</mml:mn>
 271                 </mml:msub>
 272             </mml:math></inlineequation>
 273             <emphasis>max</emphasis>,
 274             where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 275         </para>
 276         <para>
 277             <constant>GL_INVALID_VALUE</constant> is generated if
 278             <inlineequation><mml:math>
 279                 <!-- eqn: xoffset  <   -b:-->
 280                 <mml:mrow>
 281                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 282                     <mml:mo>&lt;</mml:mo>
 283                     <mml:mrow>
 284                         <mml:mo>-</mml:mo>
 285                         <mml:mi mathvariant="italic">b</mml:mi>
 286                     </mml:mrow>
 287                 </mml:mrow>
 288             </mml:math></inlineequation>,
 289             <inlineequation><mml:math>
 290                 <!-- eqn: (xoffset + width)  >  (w - b):-->
 291                 <mml:mrow>
 292                     <mml:mfenced open="(" close=")">
 293                         <mml:mrow>
 294                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 295                             <mml:mo>+</mml:mo>
 296                             <mml:mi mathvariant="italic">width</mml:mi>
 297                         </mml:mrow>
 298                     </mml:mfenced>
 299                     <mml:mo>&gt;</mml:mo>
 300                     <mml:mfenced open="(" close=")">
 301                         <mml:mrow>
 302                             <mml:mi mathvariant="italic">w</mml:mi>
 303                             <mml:mo>-</mml:mo>
 304                             <mml:mi mathvariant="italic">b</mml:mi>
 305                         </mml:mrow>
 306                     </mml:mfenced>
 307                 </mml:mrow>
 308             </mml:math></inlineequation>,
 309             <inlineequation><mml:math>
 310                 <!-- eqn: yoffset  <   -b:-->
 311                 <mml:mrow>
 312                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 313                     <mml:mo>&lt;</mml:mo>
 314                     <mml:mrow>
 315                         <mml:mo>-</mml:mo>
 316                         <mml:mi mathvariant="italic">b</mml:mi>
 317                     </mml:mrow>
 318                 </mml:mrow>
 319             </mml:math></inlineequation>,
 320             or
 321             <inlineequation><mml:math>
 322                 <!-- eqn: (yoffset  +  height)  >  (h - b):-->
 323                 <mml:mrow>
 324                     <mml:mfenced open="(" close=")">
 325                         <mml:mrow>
 326                             <mml:mi mathvariant="italic">yoffset</mml:mi>
 327                             <mml:mo>+</mml:mo>
 328                             <mml:mi mathvariant="italic">height</mml:mi>
 329                         </mml:mrow>
 330                     </mml:mfenced>
 331                     <mml:mo>&gt;</mml:mo>
 332                     <mml:mfenced open="(" close=")">
 333                         <mml:mrow>
 334                             <mml:mi mathvariant="italic">h</mml:mi>
 335                             <mml:mo>-</mml:mo>
 336                             <mml:mi mathvariant="italic">b</mml:mi>
 337                         </mml:mrow>
 338                     </mml:mfenced>
 339                 </mml:mrow>
 340             </mml:math></inlineequation>,
 341             where
 342             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 343             is the <constant>GL_TEXTURE_WIDTH</constant>,
 344             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 345             is the <constant>GL_TEXTURE_HEIGHT</constant>, and
 346             <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 347             is the border width
 348             of the texture image being modified.
 349             Note that
 350             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 351             and
 352             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 353             include twice the border width.
 354         </para>
 355         <para>
 356             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>height</parameter> is less than 0.
 357         </para>
 358         <para>
 359             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
 360             been defined by a previous <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> operation.
 361         </para>
 362         <para>
 363             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 364             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 365             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 366             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
 367             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
 368             and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 369         </para>
 370         <para>
 371             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 372             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 373             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 374             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 375             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 376             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 377             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 378             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 379             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 380             and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
 381         </para>
 382         <para>
 383             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 384             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 385         </para>
 386         <para>
 387             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 388             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 389             object such that the memory reads required would exceed the data store size.
 390         </para>
 391         <para>
 392             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 393             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
 394             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 395         </para>
 396         <para>
 397             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glTexSubImage2D</function> is executed
 398             between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
 399             execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 400         </para>
 401     </refsect1>
 402     <refsect1 id="associatedgets"><title>Associated Gets</title>
 403         <para>
 404             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 405         </para>
 406         <para>
 407             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant>
 408         </para>
 409         <para>
 410             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 411         </para>
 412     </refsect1>
 413     <refsect1 id="seealso"><title>See Also</title>
 414         <para>
 415             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 416             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 417             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 418             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 419             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 420             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 421             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 422             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 423             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
 424             <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
 425             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 426             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 427             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 428             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 429             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 430             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 431             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 432         </para>
 433     </refsect1>
 434     <refsect1 id="Copyright"><title>Copyright</title>
 435         <para>
 436             Copyright <trademark class="copyright"></trademark> 1991-2006
 437             Silicon Graphics, Inc. This document is licensed under the SGI
 438             Free Software B License. For details, see
 439             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 440         </para>
 441     </refsect1>
 442 </refentry>