upstream-man-pages/man4/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>,
  51                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>,
  52                     or <constant>GL_TEXTURE_1D_ARRAY</constant>.
  53                 </para>
  54             </listitem>
  55         </varlistentry>
  56         <varlistentry>
  57             <term><parameter>level</parameter></term>
  58             <listitem>
  59                 <para>
  60                     Specifies the level-of-detail number.
  61                     Level 0 is the base image level.
  62                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  63                 </para>
  64             </listitem>
  65         </varlistentry>
  66         <varlistentry>
  67             <term><parameter>xoffset</parameter></term>
  68             <listitem>
  69                 <para>
  70                     Specifies a texel offset in the x direction within the texture array.
  71                 </para>
  72             </listitem>
  73         </varlistentry>
  74         <varlistentry>
  75             <term><parameter>yoffset</parameter></term>
  76             <listitem>
  77                 <para>
  78                     Specifies a texel offset in the y direction within the texture array.
  79                 </para>
  80             </listitem>
  81         </varlistentry>
  82         <varlistentry>
  83             <term><parameter>width</parameter></term>
  84             <listitem>
  85                 <para>
  86                     Specifies the width of the texture subimage.
  87                 </para>
  88             </listitem>
  89         </varlistentry>
  90         <varlistentry>
  91             <term><parameter>height</parameter></term>
  92             <listitem>
  93                 <para>
  94                     Specifies the height of the texture subimage.
  95                 </para>
  96             </listitem>
  97         </varlistentry>
  98         <varlistentry>
  99             <term><parameter>format</parameter></term>
 100             <listitem>
 101                 <para>
 102                     Specifies the format of the pixel data.
 103                     The following symbolic values are accepted:
 104                     <constant>GL_RED</constant>,
 105                     <constant>GL_RG</constant>,
 106                     <constant>GL_RGB</constant>,
 107                     <constant>GL_BGR</constant>,
 108                     <constant>GL_RGBA</constant>, and
 109                     <constant>GL_BGRA</constant>.
 110                 </para>
 111             </listitem>
 112         </varlistentry>
 113         <varlistentry>
 114             <term><parameter>type</parameter></term>
 115             <listitem>
 116                 <para>
 117                     Specifies the data type of the pixel data.
 118                     The following symbolic values are accepted:
 119                     <constant>GL_UNSIGNED_BYTE</constant>,
 120                     <constant>GL_BYTE</constant>,
 121                     <constant>GL_UNSIGNED_SHORT</constant>,
 122                     <constant>GL_SHORT</constant>,
 123                     <constant>GL_UNSIGNED_INT</constant>,
 124                     <constant>GL_INT</constant>,
 125                     <constant>GL_FLOAT</constant>,
 126                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 127                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 128                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 129                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 130                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 131                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 132                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 133                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 134                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 135                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 136                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 137                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
 138                 </para>
 139             </listitem>
 140         </varlistentry>
 141         <varlistentry>
 142             <term><parameter>data</parameter></term>
 143             <listitem>
 144                 <para>
 145                     Specifies a pointer to the image data in memory.
 146                 </para>
 147             </listitem>
 148         </varlistentry>
 149         </variablelist>
 150     </refsect1>
 151     <refsect1 id="description"><title>Description</title>
 152         <para>
 153             Texturing maps a portion of a specified texture image
 154             onto each graphical primitive for which texturing is enabled.
 155         </para>
 156         <para>
 157             <function>glTexSubImage2D</function> redefines a contiguous subregion of an existing two-dimensional
 158             or one-dimensional arary texture image.
 159             The texels referenced by <parameter>data</parameter> replace the portion of the
 160             existing texture array with x indices <parameter>xoffset</parameter> and
 161             <inlineequation><mml:math>
 162                 <!-- eqn: xoffset + width - 1: -->
 163                 <mml:mrow>
 164                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 165                     <mml:mo>+</mml:mo>
 166                     <mml:mi mathvariant="italic">width</mml:mi>
 167                     <mml:mo>-</mml:mo>
 168                     <mml:mn>1</mml:mn>
 169                 </mml:mrow>
 170             </mml:math></inlineequation>,
 171             inclusive,
 172             and y indices <parameter>yoffset</parameter> and
 173             <inlineequation><mml:math>
 174                 <!-- eqn: yoffset + height - 1: -->
 175                 <mml:mrow>
 176                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 177                     <mml:mo>+</mml:mo>
 178                     <mml:mi mathvariant="italic">height</mml:mi>
 179                     <mml:mo>-</mml:mo>
 180                     <mml:mn>1</mml:mn>
 181                 </mml:mrow>
 182             </mml:math></inlineequation>,
 183             inclusive.
 184             This region may not include any texels outside the range of the
 185             texture array as it was originally specified.
 186             It is not an error to specify a subtexture with zero width or height, but
 187             such a specification has no effect.
 188         </para>
 189         <para>
 190             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 191             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 192             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 193         </para>
 194     </refsect1>
 195     <refsect1 id="notes"><title>Notes</title>
 196         <para>
 197             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> modes affect texture images.
 198         </para>
 199         <para>
 200             <function>glTexSubImage2D</function> specifies a two-dimensional subtexture for the current texture unit,
 201             specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
 202         </para>
 203     </refsect1>
 204     <refsect1 id="errors"><title>Errors</title>
 205         <para>
 206             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_2D</constant>,
 207             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 208             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 209             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 210             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 211             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 212             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
 213             <constant>GL_TEXTURE_1D_ARRAY</constant>.
 214         </para>
 215         <para>
 216             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not an accepted
 217             format constant.
 218         </para>
 219         <para>
 220             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not a type constant.
 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 <parameter>level</parameter> is greater
 227             than
 228             <inlineequation><mml:math>
 229                 <!-- eqn: log sub 2: -->
 230                 <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 231                 <mml:mn>2</mml:mn>
 232                 </mml:msub>
 233             </mml:math></inlineequation>
 234             <emphasis>max</emphasis>,
 235             where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 236         </para>
 237         <para>
 238             <constant>GL_INVALID_VALUE</constant> is generated if
 239             <inlineequation><mml:math>
 240                 <!-- eqn: xoffset  <   -b: -->
 241                 <mml:mrow>
 242                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 243                     <mml:mo>&lt;</mml:mo>
 244                     <mml:mrow>
 245                         <mml:mo>-</mml:mo>
 246                         <mml:mi mathvariant="italic">b</mml:mi>
 247                     </mml:mrow>
 248                 </mml:mrow>
 249             </mml:math></inlineequation>,
 250             <inlineequation><mml:math>
 251                 <!-- eqn: (xoffset + width)  >  (w - b): -->
 252                 <mml:mrow>
 253                     <mml:mfenced open="(" close=")">
 254                         <mml:mrow>
 255                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 256                             <mml:mo>+</mml:mo>
 257                             <mml:mi mathvariant="italic">width</mml:mi>
 258                         </mml:mrow>
 259                     </mml:mfenced>
 260                     <mml:mo>&gt;</mml:mo>
 261                     <mml:mfenced open="(" close=")">
 262                         <mml:mrow>
 263                             <mml:mi mathvariant="italic">w</mml:mi>
 264                             <mml:mo>-</mml:mo>
 265                             <mml:mi mathvariant="italic">b</mml:mi>
 266                         </mml:mrow>
 267                     </mml:mfenced>
 268                 </mml:mrow>
 269             </mml:math></inlineequation>,
 270             <inlineequation><mml:math>
 271                 <!-- eqn: yoffset  <   -b: -->
 272                 <mml:mrow>
 273                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 274                     <mml:mo>&lt;</mml:mo>
 275                     <mml:mrow>
 276                         <mml:mo>-</mml:mo>
 277                         <mml:mi mathvariant="italic">b</mml:mi>
 278                     </mml:mrow>
 279                 </mml:mrow>
 280             </mml:math></inlineequation>,
 281             or
 282             <inlineequation><mml:math>
 283                 <!-- eqn: (yoffset  +  height)  >  (h - b): -->
 284                 <mml:mrow>
 285                     <mml:mfenced open="(" close=")">
 286                         <mml:mrow>
 287                             <mml:mi mathvariant="italic">yoffset</mml:mi>
 288                             <mml:mo>+</mml:mo>
 289                             <mml:mi mathvariant="italic">height</mml:mi>
 290                         </mml:mrow>
 291                     </mml:mfenced>
 292                     <mml:mo>&gt;</mml:mo>
 293                     <mml:mfenced open="(" close=")">
 294                         <mml:mrow>
 295                             <mml:mi mathvariant="italic">h</mml:mi>
 296                             <mml:mo>-</mml:mo>
 297                             <mml:mi mathvariant="italic">b</mml:mi>
 298                         </mml:mrow>
 299                     </mml:mfenced>
 300                 </mml:mrow>
 301             </mml:math></inlineequation>,
 302             where
 303             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 304             is the <constant>GL_TEXTURE_WIDTH</constant>,
 305             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 306             is the <constant>GL_TEXTURE_HEIGHT</constant>, and
 307             <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 308             is the border width
 309             of the texture image being modified.
 310             Note that
 311             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 312             and
 313             <inlineequation><mml:math><mml:mi mathvariant="italic">h</mml:mi></mml:math></inlineequation>
 314             include twice the border width.
 315         </para>
 316         <para>
 317             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> or <parameter>height</parameter> is less than 0.
 318         </para>
 319         <para>
 320             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
 321             been defined by a previous <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> operation.
 322         </para>
 323         <para>
 324             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 325             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 326             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 327             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
 328             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
 329             and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 330         </para>
 331         <para>
 332             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 333             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 334             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 335             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 336             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 337             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 338             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 339             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 340             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 341             and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
 342         </para>
 343         <para>
 344             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 345             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 346         </para>
 347         <para>
 348             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 349             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 350             object such that the memory reads required would exceed the data store size.
 351         </para>
 352         <para>
 353             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 354             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
 355             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 356         </para>
 357     </refsect1>
 358     <refsect1 id="associatedgets"><title>Associated Gets</title>
 359         <para>
 360             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 361         </para>
 362         <para>
 363             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 364         </para>
 365     </refsect1>
 366     <refsect1 id="seealso"><title>See Also</title>
 367         <para>
 368             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 369             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 370             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 371             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 372             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 373             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 374             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 375             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 376             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 377             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 378             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 379             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 380             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 381         </para>
 382     </refsect1>
 383     <refsect1 id="Copyright"><title>Copyright</title>
 384         <para>
 385             Copyright <trademark class="copyright"></trademark> 1991-2006
 386             Silicon Graphics, Inc. This document is licensed under the SGI
 387             Free Software B License. For details, see
 388             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 389         </para>
 390     </refsect1>
 391 </refentry>