upstream-man-pages/man4/glTexImage3D.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="glTexImage3D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glTexImage3D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glTexImage3D</refname>
  17         <refpurpose>specify a three-dimensional texture image</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glTexImage3D</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>level</parameter></paramdef>
  25                 <paramdef>GLint <parameter>internalFormat</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  27                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  28                 <paramdef>GLsizei <parameter>depth</parameter></paramdef>
  29                 <paramdef>GLint <parameter>border</parameter></paramdef>
  30                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  31                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  32                 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
  33             </funcprototype>
  34         </funcsynopsis>
  35     </refsynopsisdiv>
  36     <!-- eqn: ignoring delim $$ -->
  37     <para>
  38     </para>
  39     <refsect1 id="parameters"><title>Parameters</title>
  40         <variablelist>
  41         <varlistentry>
  42             <term><parameter>target</parameter></term>
  43             <listitem>
  44                 <para>
  45                     Specifies the target texture.
  46                     Must be one of <constant>GL_TEXTURE_3D</constant>, <constant>GL_PROXY_TEXTURE_3D</constant>,
  47                     <constant>GL_TEXTURE_2D_ARRAY</constant> or <constant>GL_PROXY_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
  58                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
  59                     is the
  60                     <inlineequation><mml:math>
  61                         <!-- eqn: n sup th: -->
  62                         <mml:msup><mml:mi mathvariant="italic">n</mml:mi>
  63                         <mml:mi mathvariant="italic">th</mml:mi>
  64                         </mml:msup>
  65                     </mml:math></inlineequation>
  66                     mipmap reduction image.
  67                 </para>
  68             </listitem>
  69         </varlistentry>
  70         <varlistentry>
  71             <term><parameter>internalFormat</parameter></term>
  72             <listitem>
  73                 <para>
  74                     Specifies the number of color components in the texture.
  75                     Must be one of base internal formats given in Table 1,
  76                     one of the sized internal formats given in Table 2, or one
  77                     of the compressed internal formats given in Table 3, below.
  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 image.
  86                     All implementations support 3D texture images that are at least 16 texels
  87                     wide.
  88                 </para>
  89             </listitem>
  90         </varlistentry>
  91         <varlistentry>
  92             <term><parameter>height</parameter></term>
  93             <listitem>
  94                 <para>
  95                     Specifies the height of the texture image.
  96                     All implementations support 3D texture images that are at least 256 texels
  97                     high.
  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 image, or the number of layers in a texture array.
 106                     All implementations support 3D texture images that are at least 256 texels
 107                     deep, and texture arrays that are at least 256 layers deep.
 108                 </para>
 109             </listitem>
 110         </varlistentry>
 111         <varlistentry>
 112             <term><parameter>border</parameter></term>
 113             <listitem>
 114                 <para>
 115                     This value must be 0.
 116                 </para>
 117             </listitem>
 118         </varlistentry>
 119         <varlistentry>
 120             <term><parameter>format</parameter></term>
 121             <listitem>
 122                 <para>
 123                     Specifies the format of the pixel data.
 124                     The following symbolic values are accepted:
 125                     <constant>GL_RED</constant>,
 126                     <constant>GL_RG</constant>,
 127                     <constant>GL_RGB</constant>,
 128                     <constant>GL_BGR</constant>,
 129                     <constant>GL_RGBA</constant>, and
 130                     <constant>GL_BGRA</constant>.
 131                 </para>
 132             </listitem>
 133         </varlistentry>
 134         <varlistentry>
 135             <term><parameter>type</parameter></term>
 136             <listitem>
 137                 <para>
 138                     Specifies the data type of the pixel data.
 139                     The following symbolic values are accepted:
 140                     <constant>GL_UNSIGNED_BYTE</constant>,
 141                     <constant>GL_BYTE</constant>,
 142                     <constant>GL_UNSIGNED_SHORT</constant>,
 143                     <constant>GL_SHORT</constant>,
 144                     <constant>GL_UNSIGNED_INT</constant>,
 145                     <constant>GL_INT</constant>,
 146                     <constant>GL_FLOAT</constant>,
 147                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 148                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 149                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 150                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 151                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 152                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 153                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 154                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 155                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 156                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 157                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 158                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
 159                 </para>
 160             </listitem>
 161         </varlistentry>
 162         <varlistentry>
 163             <term><parameter>data</parameter></term>
 164             <listitem>
 165                 <para>
 166                     Specifies a pointer to the image data in memory.
 167                 </para>
 168             </listitem>
 169         </varlistentry>
 170         </variablelist>
 171     </refsect1>
 172     <refsect1 id="description"><title>Description</title>
 173         <para>
 174             Texturing maps a portion of a specified texture image
 175             onto each graphical primitive for which texturing is enabled.
 176             To enable and disable three-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
 177             and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_3D</constant>.
 178         </para>
 179         <para>
 180             To define texture images, call <function>glTexImage3D</function>.
 181             The arguments describe the parameters of the texture image,
 182             such as height,
 183             width, depth,
 184             width of the border,
 185             level-of-detail number
 186             (see <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>),
 187             and number of color components provided.
 188             The last three arguments describe how the image is represented in memory.
 189         </para>
 190         <para>
 191             If <parameter>target</parameter> is <constant>GL_PROXY_TEXTURE_3D</constant>, no data is read from <parameter>data</parameter>, but
 192             all of the texture image state is recalculated, checked for
 193             consistency, and checked
 194             against the implementation's capabilities. If the implementation cannot
 195             handle a texture of the requested texture size, it sets
 196             all of the image state to 0,
 197             but does not generate an error (see <citerefentry><refentrytitle>glGetError</refentrytitle></citerefentry>). To query for an
 198             entire mipmap array, use an image array level greater than or equal to
 199             1.
 200         </para>
 201         <para>
 202             If <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant>,
 203             data is read from <parameter>data</parameter> as a sequence of signed or unsigned bytes,
 204             shorts,
 205             or longs,
 206             or single-precision floating-point values,
 207             depending on <parameter>type</parameter>.
 208             These values are grouped into sets of one,
 209             two,
 210             three,
 211             or four values,
 212             depending on <parameter>format</parameter>,
 213             to form elements.
 214             Each data byte is treated as eight 1-bit elements,
 215             with bit ordering determined by <constant>GL_UNPACK_LSB_FIRST</constant>
 216             (see <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>).
 217         </para>
 218         <para>
 219             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 220             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 221             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 222         </para>
 223         <para>
 224             The first element corresponds to the lower left corner of the texture
 225             image.
 226             Subsequent elements progress left-to-right through the remaining texels
 227             in the lowest row of the texture image, and then in successively higher
 228             rows of the texture image.
 229             The final element corresponds to the upper right corner of the texture
 230             image.
 231         </para>
 232         <para>
 233             <parameter>format</parameter> determines the composition of each element in <parameter>data</parameter>.
 234             It can assume one of these symbolic values:
 235         </para>
 236         <variablelist>
 237             <varlistentry>
 238                 <term><constant>GL_RED</constant></term>
 239                 <listitem>
 240                     <para>
 241                         Each element is a single red component.
 242                         The GL converts it to floating point and assembles it into an RGBA element
 243                         by attaching 0 for green and blue, and 1 for alpha.
 244                         Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
 245                         added to the signed bias <constant>GL_c_BIAS</constant>,
 246                         and clamped to the range [0,1].
 247                     </para>
 248                 </listitem>
 249             </varlistentry>
 250             <varlistentry>
 251                 <term><constant>GL_RG</constant></term>
 252                 <listitem>
 253                     <para>
 254                         Each element is a red and green pair.
 255                         The GL converts each to floating point and assembles it into an RGBA element
 256                         by attaching 0 for blue, and 1 for alpha.
 257                         Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
 258                         added to the signed bias <constant>GL_c_BIAS</constant>,
 259                         and clamped to the range [0,1].
 260                     </para>
 261                 </listitem>
 262             </varlistentry>
 263             <varlistentry>
 264                 <term><constant>GL_RGB</constant></term>
 265                 <listitem>
 266                 </listitem>
 267             </varlistentry>
 268             <varlistentry>
 269                 <term><constant>GL_BGR</constant></term>
 270                 <listitem>
 271                     <para>
 272                         Each element is an RGB triple.
 273                         The GL converts it to floating point and assembles it into an RGBA element
 274                         by attaching 1 for alpha.
 275                         Each component is then multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
 276                         added to the signed bias <constant>GL_c_BIAS</constant>,
 277                         and clamped to the range [0,1].
 278                     </para>
 279                 </listitem>
 280             </varlistentry>
 281             <varlistentry>
 282                 <term><constant>GL_RGBA</constant></term>
 283                 <listitem>
 284                 </listitem>
 285             </varlistentry>
 286             <varlistentry>
 287                 <term><constant>GL_BGRA</constant></term>
 288                 <listitem>
 289                     <para>
 290                         Each element contains all four components.
 291                         Each component is multiplied by the signed scale factor <constant>GL_c_SCALE</constant>,
 292                         added to the signed bias <constant>GL_c_BIAS</constant>,
 293                         and clamped to the range [0,1].
 294                     </para>
 295                 </listitem>
 296             </varlistentry>
 297         </variablelist>
 298         <para>
 299             If an application wants to store the texture at a certain
 300             resolution or in a certain format, it can request the resolution
 301             and format with <parameter>internalFormat</parameter>. The GL will choose an internal
 302             representation that closely approximates that requested by <parameter>internalFormat</parameter>, but
 303             it may not match exactly.
 304             (The representations specified by <constant>GL_RED</constant>, <constant>GL_RG</constant>, <constant>GL_RGB</constant>,
 305             and <constant>GL_RGBA</constant> must match exactly.)
 306         </para>
 307         <para>
 308             <parameter>internalFormat</parameter> may be one of the base internal formats shown in
 309             Table 1, below
 310         </para>
 311         <para>
 312             <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="baseformattable.xml" />
 313         </para>
 314         <para>
 315             <parameter>internalFormat</parameter> may also be one of the sized internal formats
 316             shown in Table 2, below
 317         </para>
 318         <para>
 319             <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="internalformattable.xml" />
 320         </para>
 321         <para>
 322             Finally, <parameter>internalFormat</parameter> may also be one of the generic or compressed
 323             compressed texture formats shown in Table 3 below
 324         </para>
 325         <para>
 326             <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="compressedformattable.xml" />
 327         </para>
 328         <para>
 329                 If the <parameter>internalFormat</parameter> parameter is one of the generic compressed formats,
 330                 <constant>GL_COMPRESSED_RED</constant>, <constant>GL_COMPRESSED_RG</constant>,
 331                 <constant>GL_COMPRESSED_RGB</constant>, or
 332                 <constant>GL_COMPRESSED_RGBA</constant>, the GL will replace the internal format with the symbolic constant for a specific internal format and compress the texture before storage.  If no corresponding internal format is available, or the GL can not compress that image for any reason, the internal format is instead replaced with a corresponding base internal format.
 333         </para>
 334         <para>
 335             If the <parameter>internalFormat</parameter> parameter is
 336             <constant>GL_SRGB</constant>,
 337                               <constant>GL_SRGB8</constant>,
 338                               <constant>GL_SRGB_ALPHA</constant>, or
 339                               <constant>GL_SRGB8_ALPHA8</constant>, the texture is treated as if the red, green, blue, or luminance components are encoded in the sRGB color space.    Any alpha component is left unchanged.  The conversion from the sRGB encoded component
 340                         <inlineequation><mml:math>
 341                     <mml:msub><mml:mi mathvariant="italic">c</mml:mi>
 342                     <mml:mi mathvariant="italic">s</mml:mi>
 343                     </mml:msub>
 344             </mml:math></inlineequation>
 345                         to a linear component
 346                         <inlineequation><mml:math>
 347                     <mml:msub><mml:mi mathvariant="italic">c</mml:mi>
 348                     <mml:mi mathvariant="italic">l</mml:mi>
 349                     </mml:msub>
 350             </mml:math></inlineequation>
 351             is:
 352                 </para>
 353                 <para>
 354                         <inlineequation><mml:math>
 355                         <mml:mrow>
 356                                 <mml:msub>
 357                                   <mml:mi mathvariant="italic">c</mml:mi>
 358                                   <mml:mi mathvariant="italic">l</mml:mi>
 359                                 </mml:msub>
 360                                 <mml:mo>=</mml:mo>
 361                                 <mml:mrow>
 362                                   <mml:mo>{</mml:mo>
 363
 364                                   <mml:mtable columnalign="left">
 365                                         <mml:mtr>
 366                                           <mml:mtd columnalign="left">
 367                                                 <mml:mfrac>
 368                                                   <mml:msub>
 369                                                         <mml:mi mathvariant="italic">c</mml:mi>
 370                                                         <mml:mi mathvariant="italic">s</mml:mi>
 371                                                   </mml:msub>
 372                                                   <mml:mn>12.92</mml:mn>
 373                                                 </mml:mfrac>
 374                                           </mml:mtd>
 375                                           <mml:mtd columnalign="left">
 376                                                 <mml:mrow>
 377                                                   <mml:mspace width="1ex"/>
 378                                                   <mml:mo>if</mml:mo>
 379                                                   <mml:mspace width="1ex"/>
 380                                                 </mml:mrow>
 381                                                 <mml:msub>
 382                                                   <mml:mi mathvariant="italic">c</mml:mi>
 383                                                   <mml:mi mathvariant="italic">s</mml:mi>
 384                                                 </mml:msub>
 385                                                 <mml:mo>&le;</mml:mo>
 386                                                 <mml:mn>0.04045</mml:mn>
 387                                           </mml:mtd>
 388                                         </mml:mtr>
 389                                         <mml:mtr>
 390                                         <mml:mtd columnalign="left">
 391                                         <mml:msup>
 392                                           <mml:mrow>
 393                                                 <mml:mo>(</mml:mo>
 394                                                 <mml:mfrac>
 395                                                   <mml:mrow>
 396                                                         <mml:msub>
 397                                                           <mml:mi>c</mml:mi>
 398                                                           <mml:mi>s</mml:mi>
 399                                                         </mml:msub>
 400                                                         <mml:mo>+</mml:mo>
 401                                                         <mml:mn>0.055</mml:mn>
 402                                                   </mml:mrow>
 403                                                   <mml:mn>1.055</mml:mn>
 404                                                 </mml:mfrac>
 405                                                 <mml:mo>)</mml:mo>
 406                                           </mml:mrow>
 407                                           <mml:mn>2.4</mml:mn>
 408                                         </mml:msup>
 409                                         </mml:mtd>
 410                                   <mml:mtd columnalign="left">
 411                                                 <mml:mrow>
 412                                                   <mml:mspace width="1ex"/>
 413                                                   <mml:mo>if</mml:mo>
 414                                                   <mml:mspace width="1ex"/>
 415                                                 </mml:mrow>
 416                                                 <mml:msub>
 417                                                   <mml:mi mathvariant="italic">c</mml:mi>
 418                                                   <mml:mi mathvariant="italic">s</mml:mi>
 419                                                 </mml:msub>
 420                                                 <mml:mo>&gt;</mml:mo>
 421                                                 <mml:mn>0.04045</mml:mn>
 422                                           </mml:mtd>
 423                                         </mml:mtr>
 424                                   </mml:mtable>
 425                                 </mml:mrow>
 426                                 </mml:mrow>
 427                         </mml:math>
 428                         </inlineequation>
 429                 </para>
 430                 <para>
 431                         Assume
 432                         <inlineequation><mml:math>
 433                                                                 <mml:msub><mml:mi mathvariant="italic">c</mml:mi>
 434                                                                 <mml:mi mathvariant="italic">s</mml:mi>
 435                                                                 </mml:msub>
 436                                                 </mml:math></inlineequation>
 437                         is the sRGB component in the range [0,1].
 438        </para>
 439         <para>
 440             Use the <constant>GL_PROXY_TEXTURE_3D</constant> target to try out a resolution and
 441             format. The implementation will
 442             update and recompute its best match for the requested storage resolution
 443             and format. To then query this state, call <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
 444             If the texture cannot be accommodated, texture state is set to 0.
 445         </para>
 446         <para>
 447             A one-component texture image uses only the red component of the RGBA
 448             color extracted from <parameter>data</parameter>.
 449             A two-component image uses the R and A values.
 450             A three-component image uses the R, G, and B values.
 451             A four-component image uses all of the RGBA components.
 452         </para>
 453     </refsect1>
 454     <refsect1 id="notes"><title>Notes</title>
 455         <para>
 456             The <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> mode affects texture images.
 457         </para>
 458         <para>
 459             <parameter>data</parameter> may be a null pointer.
 460             In this case texture memory is
 461             allocated to accommodate a texture of width <parameter>width</parameter>, height <parameter>height</parameter>,
 462             and depth <parameter>depth</parameter>.
 463             You can then download subtextures to initialize this
 464             texture memory.
 465             The image is undefined if the user tries to apply
 466             an uninitialized portion of the texture image to a primitive.
 467         </para>
 468         <para>
 469             <function>glTexImage3D</function> specifies the three-dimensional texture for the current texture unit,
 470             specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
 471         </para>
 472     </refsect1>
 473     <refsect1 id="errors"><title>Errors</title>
 474         <para>
 475             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_TEXTURE_3D</constant>
 476             or <constant>GL_PROXY_TEXTURE_3D</constant>.
 477         </para>
 478         <para>
 479             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not an accepted
 480             format constant.  Format constants other than <constant>GL_STENCIL_INDEX</constant> and <constant>GL_DEPTH_COMPONENT</constant>
 481             are accepted.
 482         </para>
 483         <para>
 484             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not a type constant.
 485         </para>
 486         <para>
 487             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 488         </para>
 489         <para>
 490             <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater than
 491             <inlineequation><mml:math>
 492                 <!-- eqn: log sub 2 (max): -->
 493                 <mml:mrow>
 494                     <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 495                     <mml:mn>2</mml:mn>
 496                     </mml:msub>
 497                     <mml:mo>&af;</mml:mo>
 498                     <mml:mfenced open="(" close=")">
 499                         <mml:mi mathvariant="italic">max</mml:mi>
 500                     </mml:mfenced>
 501                 </mml:mrow>
 502             </mml:math></inlineequation>,
 503             where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 504         </para>
 505         <para>
 506             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>internalFormat</parameter> is not one of the
 507             accepted resolution and format symbolic constants.
 508         </para>
 509         <para>
 510             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter>, <parameter>height</parameter>, or <parameter>depth</parameter> is less than 0 or greater than <constant>GL_MAX_TEXTURE_SIZE</constant>.
 511         </para>
 512         <para>
 513             <constant>GL_INVALID_VALUE</constant> is generated if non-power-of-two textures are not supported and the <parameter>width</parameter>, <parameter>height</parameter>, or <parameter>depth</parameter> cannot be represented as
 514             <inlineequation><mml:math>
 515                 <!-- eqn: 2 sup k  +  2( border ): -->
 516                 <mml:mrow>
 517                     <mml:msup><mml:mn>2</mml:mn>
 518                     <mml:mi mathvariant="italic">k</mml:mi>
 519                     </mml:msup>
 520                     <mml:mo>+</mml:mo>
 521                     <mml:mrow>
 522                         <mml:mn>2</mml:mn>
 523                         <mml:mo>&af;</mml:mo>
 524                         <mml:mfenced open="(" close=")">
 525                             <mml:mi mathvariant="italic">border</mml:mi>
 526                         </mml:mfenced>
 527                     </mml:mrow>
 528                 </mml:mrow>
 529             </mml:math></inlineequation>
 530             for some
 531             integer value of <emphasis>k</emphasis>.
 532         </para>
 533         <para>
 534             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0 or 1.
 535         </para>
 536         <para>
 537             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 538             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 539             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 540             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
 541             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
 542             and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 543         </para>
 544         <para>
 545             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 546             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 547             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 548             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 549             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 550             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 551             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 552             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 553             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 554             and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
 555         </para>
 556         <para>
 557             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>format</parameter> or <parameter>internalFormat</parameter> is
 558             <constant>GL_DEPTH_COMPONENT</constant>, <constant>GL_DEPTH_COMPONENT16</constant>,
 559             <constant>GL_DEPTH_COMPONENT24</constant>, or <constant>GL_DEPTH_COMPONENT32</constant>.
 560         </para>
 561         <para>
 562             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 563             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 564         </para>
 565         <para>
 566             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 567             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 568             object such that the memory reads required would exceed the data store size.
 569         </para>
 570         <para>
 571             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 572             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
 573             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 574         </para>
 575     </refsect1>
 576     <refsect1 id="associatedgets"><title>Associated Gets</title>
 577         <para>
 578             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 579         </para>
 580         <para>
 581             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 582         </para>
 583     </refsect1>
 584     <refsect1 id="seealso"><title>See Also</title>
 585         <para>
 586             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 587             <citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
 588             <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
 589             <citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
 590             <citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
 591             <citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
 592             <citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
 593             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 594             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 595             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 596             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 597             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 598             <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>,
 599             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 600             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 601             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 602             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 603             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 604             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 605             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 606         </para>
 607     </refsect1>
 608     <refsect1 id="Copyright"><title>Copyright</title>
 609         <para>
 610             Copyright <trademark class="copyright"></trademark> 1991-2006 Silicon Graphics, Inc.
 611             Copyright <trademark class="copyright"></trademark> 2011 Khronos Group.
 612             This document is licensed under the SGI
 613             Free Software B License. For details, see
 614             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 615         </para>
 616     </refsect1>
 617 </refentry>