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