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