upstream-doc/man2/glCompressedTexSubImage2D.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="glCompressedTexSubImage2D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCompressedTexSubImage2D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCompressedTexSubImage2D</refname>
  17         <refpurpose>specify a two-dimensional texture subimage in a compressed format</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCompressedTexSubImage2D</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>level</parameter></paramdef>
  25                 <paramdef>GLint <parameter>xoffset</parameter></paramdef>
  26                 <paramdef>GLint <parameter>yoffset</parameter></paramdef>
  27                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  28                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  29                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  30                 <paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
  31                 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <!-- eqn: ignoring delim $$ -->
  36     <refsect1 id="parameters"><title>Parameters</title>
  37         <variablelist>
  38         <varlistentry>
  39             <term><parameter>target</parameter></term>
  40             <listitem>
  41                 <para>
  42                     Specifies the target texture.
  43                     Must be <constant>GL_TEXTURE_2D</constant>,
  44                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
  45                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
  46                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
  47                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
  48                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, or
  49                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>.
  50                 </para>
  51             </listitem>
  52         </varlistentry>
  53         <varlistentry>
  54             <term><parameter>level</parameter></term>
  55             <listitem>
  56                 <para>
  57                     Specifies the level-of-detail number.
  58                     Level 0 is the base image level.
  59                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  60                 </para>
  61             </listitem>
  62         </varlistentry>
  63         <varlistentry>
  64             <term><parameter>xoffset</parameter></term>
  65             <listitem>
  66                 <para>
  67                     Specifies a texel offset in the x direction within the texture array.
  68                 </para>
  69             </listitem>
  70         </varlistentry>
  71         <varlistentry>
  72             <term><parameter>yoffset</parameter></term>
  73             <listitem>
  74                 <para>
  75                     Specifies a texel offset in the y direction within the texture array.
  76                 </para>
  77             </listitem>
  78         </varlistentry>
  79         <varlistentry>
  80             <term><parameter>width</parameter></term>
  81             <listitem>
  82                 <para>
  83                     Specifies the width of the texture subimage.
  84                 </para>
  85             </listitem>
  86         </varlistentry>
  87         <varlistentry>
  88             <term><parameter>height</parameter></term>
  89             <listitem>
  90                 <para>
  91                     Specifies the height of the texture subimage.
  92                 </para>
  93             </listitem>
  94         </varlistentry>
  95         <varlistentry>
  96             <term><parameter>format</parameter></term>
  97             <listitem>
  98                 <para>
  99                     Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
 100                 </para>
 101             </listitem>
 102         </varlistentry>
 103         <varlistentry>
 104             <term><parameter>imageSize</parameter></term>
 105             <listitem>
 106                 <para>
 107                     Specifies the number of unsigned bytes of image data starting at the
 108                     address specified by <parameter>data</parameter>.
 109                 </para>
 110             </listitem>
 111         </varlistentry>
 112         <varlistentry>
 113             <term><parameter>data</parameter></term>
 114             <listitem>
 115                 <para>
 116                     Specifies a pointer to the compressed image data in memory.
 117                 </para>
 118             </listitem>
 119         </varlistentry>
 120         </variablelist>
 121     </refsect1>
 122     <refsect1 id="description"><title>Description</title>
 123         <para>
 124             Texturing maps a portion of a specified texture image onto each graphical
 125             primitive for which texturing is enabled.  To enable and disable
 126             two-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
 127             <constant>GL_TEXTURE_2D</constant>.   To enable and disable texturing using
 128             cube-mapped texture, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument
 129             <constant>GL_TEXTURE_CUBE_MAP</constant>.
 130         </para>
 131         <para>
 132             <function>glCompressedTexSubImage2D</function> redefines a contiguous subregion of an existing two-dimensional
 133             texture image.  The texels referenced by <parameter>data</parameter> replace the portion of the
 134             existing texture array with x indices <parameter>xoffset</parameter> and
 135             <inlineequation><mml:math>
 136                 <!-- eqn: xoffset  +  width  -  1:-->
 137                 <mml:mrow>
 138                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 139                     <mml:mo>+</mml:mo>
 140                     <mml:mi mathvariant="italic">width</mml:mi>
 141                     <mml:mo>-</mml:mo>
 142                     <mml:mn>1</mml:mn>
 143                 </mml:mrow>
 144             </mml:math></inlineequation>,
 145             and the y indices <parameter>yoffset</parameter> and
 146             <inlineequation><mml:math>
 147                 <!-- eqn: yoffset  +  height  -  1:-->
 148                 <mml:mrow>
 149                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 150                     <mml:mo>+</mml:mo>
 151                     <mml:mi mathvariant="italic">height</mml:mi>
 152                     <mml:mo>-</mml:mo>
 153                     <mml:mn>1</mml:mn>
 154                 </mml:mrow>
 155             </mml:math></inlineequation>,
 156             inclusive.
 157             This region may not include any texels
 158             outside the range of the texture array as it was originally specified.  It
 159             is not an error to specify a subtexture with width of 0, but such a
 160             specification has no effect.
 161         </para>
 162         <para>
 163             <parameter>format</parameter> must be an extension-specified
 164             compressed-texture format.  The <parameter>format</parameter> of the compressed texture
 165             image is selected by the GL implementation that compressed it (see
 166             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>) and should be queried at the time the texture was
 167             compressed with <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
 168         </para>
 169         <para>
 170             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 171             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 172             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 173         </para>
 174     </refsect1>
 175     <refsect1 id="notes"><title>Notes</title>
 176         <para>
 177             <function>glCompressedTexSubImage2D</function> is available only if the GL version is 1.3 or greater.
 178         </para>
 179         <para>
 180             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
 181             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
 182             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
 183             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
 184             <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>,
 185             <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>, or
 186             <constant>GL_PROXY_TEXTURE_CUBE_MAP</constant> are available only if the GL version is 1.3
 187             or greater.
 188         </para>
 189     </refsect1>
 190     <refsect1 id="errors"><title>Errors</title>
 191         <para>
 192             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is one of these generic compressed internal formats:
 193             <constant>GL_COMPRESSED_ALPHA</constant>,
 194             <constant>GL_COMPRESSED_LUMINANCE</constant>,
 195             <constant>GL_COMPRESSED_LUMINANCE_ALPHA</constant>,
 196             <constant>GL_COMPRESSED_INTENSITY</constant>,
 197             <constant>GL_COMPRESSED_RGB</constant>,
 198             <constant>GL_COMPRESSED_RGBA</constant>,
 199                         <constant>GL_COMPRESSED_SLUMINANCE</constant>,
 200                         <constant>GL_COMPRESSED_SLUMINANCE_ALPHA</constant>,
 201                         <constant>GL_COMPRESSED_SRGB</constant>,
 202                         <constant>GL_COMPRESSED_SRGBA</constant>, or
 203                         <constant>GL_COMPRESSED_SRGB_ALPHA</constant>.
 204         </para>
 205         <para>
 206             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
 207             the format, dimensions, and contents of the specified compressed image
 208             data.
 209         </para>
 210         <para>
 211             <constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
 212             supported by the specific compressed internal format as specified in the
 213             specific texture compression extension.
 214         </para>
 215         <para>
 216             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 217             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 218         </para>
 219         <para>
 220             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 221             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 222             object such that the memory reads required would exceed the data store size.
 223         </para>
 224         <para>
 225             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glCompressedTexSubImage2D</function>
 226             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 227             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 228         </para>
 229         <para>
 230             Undefined results, including abnormal program termination, are generated if
 231             <parameter>data</parameter> is not encoded in a manner consistent with the extension
 232             specification defining the internal compression format.
 233         </para>
 234     </refsect1>
 235     <refsect1 id="associatedgets"><title>Associated Gets</title>
 236         <para>
 237             <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
 238         </para>
 239         <para>
 240             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
 241         </para>
 242         <para>
 243             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 244         </para>
 245         <para>
 246             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
 247             and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
 248         </para>
 249         <para>
 250             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_2D</constant> or <constant>GL_TEXTURE_CUBE_MAP</constant>
 251         </para>
 252     </refsect1>
 253     <refsect1 id="seealso"><title>See Also</title>
 254         <para>
 255             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 256             <citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
 257             <citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
 258             <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
 259             <citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
 260             <citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
 261             <citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
 262             <citerefentry><refentrytitle>glConvolutionFilter1D</refentrytitle></citerefentry>,
 263             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 264             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 265             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 266             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 267             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 268             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 269             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 270             <citerefentry><refentrytitle>glMatrixMode</refentrytitle></citerefentry>,
 271             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 272             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
 273             <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
 274             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 275             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 276             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 277             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 278             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 279             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 280             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 281         </para>
 282     </refsect1>
 283     <refsect1 id="Copyright"><title>Copyright</title>
 284         <para>
 285             Copyright <trademark class="copyright"></trademark> 1991-2006
 286             Silicon Graphics, Inc. This document is licensed under the SGI
 287             Free Software B License. For details, see
 288             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 289         </para>
 290     </refsect1>
 291 </refentry>