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