upstream-doc/man3/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 allows elements of an image array to be read by shaders.
 125         </para>
 126         <para>
 127             <function>glCompressedTexSubImage2D</function> redefines a contiguous subregion of an existing two-dimensional
 128             texture image.  The texels referenced by <parameter>data</parameter> replace the portion of the
 129             existing texture array with x indices <parameter>xoffset</parameter> and
 130             <inlineequation><mml:math>
 131                 <!-- eqn: xoffset  +  width  -  1: -->
 132                 <mml:mrow>
 133                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 134                     <mml:mo>+</mml:mo>
 135                     <mml:mi mathvariant="italic">width</mml:mi>
 136                     <mml:mo>-</mml:mo>
 137                     <mml:mn>1</mml:mn>
 138                 </mml:mrow>
 139             </mml:math></inlineequation>,
 140             and the y indices <parameter>yoffset</parameter> and
 141             <inlineequation><mml:math>
 142                 <!-- eqn: yoffset  +  height  -  1: -->
 143                 <mml:mrow>
 144                     <mml:mi mathvariant="italic">yoffset</mml:mi>
 145                     <mml:mo>+</mml:mo>
 146                     <mml:mi mathvariant="italic">height</mml:mi>
 147                     <mml:mo>-</mml:mo>
 148                     <mml:mn>1</mml:mn>
 149                 </mml:mrow>
 150             </mml:math></inlineequation>,
 151             inclusive.
 152             This region may not include any texels
 153             outside the range of the texture array as it was originally specified.  It
 154             is not an error to specify a subtexture with width of 0, but such a
 155             specification has no effect.
 156         </para>
 157         <para>
 158             <parameter>internalformat</parameter> must be a known compressed image format (such as <constant>GL_RGTC</constant>)
 159             or an extension-specified compressed-texture format.
 160             The <parameter>format</parameter> of the compressed texture
 161             image is selected by the GL implementation that compressed it (see
 162             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>) and should be queried at the time the texture was
 163             compressed with <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
 164         </para>
 165         <para>
 166             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 167             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 168             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 169         </para>
 170     </refsect1>
 171     <refsect1 id="errors"><title>Errors</title>
 172         <para>
 173           <constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is of the generic compressed internal formats:
 174           <constant>GL_COMPRESSED_RED</constant>,
 175           <constant>GL_COMPRESSED_RG</constant>,
 176           <constant>GL_COMPRESSED_RGB</constant>,
 177           <constant>GL_COMPRESSED_RGBA</constant>.
 178           <constant>GL_COMPRESSED_SRGB</constant>, or
 179           <constant>GL_COMPRESSED_SRGB_ALPHA</constant>.
 180         </para>
 181         <para>
 182             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
 183             the format, dimensions, and contents of the specified compressed image
 184             data.
 185         </para>
 186         <para>
 187             <constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
 188             supported by the specific compressed internal format as specified in the
 189             specific texture compression extension.
 190         </para>
 191         <para>
 192             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 193             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 194         </para>
 195         <para>
 196             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 197             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 198             object such that the memory reads required would exceed the data store size.
 199         </para>
 200         <para>
 201             Undefined results, including abnormal program termination, are generated if
 202             <parameter>data</parameter> is not encoded in a manner consistent with the extension
 203             specification defining the internal compression format.
 204         </para>
 205     </refsect1>
 206     <refsect1 id="associatedgets"><title>Associated Gets</title>
 207         <para>
 208             <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
 209         </para>
 210         <para>
 211             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
 212         </para>
 213         <para>
 214             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 215         </para>
 216         <para>
 217             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
 218             and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
 219         </para>
 220     </refsect1>
 221     <refsect1 id="seealso"><title>See Also</title>
 222         <para>
 223             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 224             <citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
 225             <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
 226             <citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
 227             <citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
 228             <citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
 229             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 230             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 231             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 232             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 233             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 234             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 235             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 236             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 237             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 238             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 239             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 240             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 241         </para>
 242     </refsect1>
 243     <refsect1 id="Copyright"><title>Copyright</title>
 244         <para>
 245             Copyright <trademark class="copyright"></trademark> 1991-2006
 246             Silicon Graphics, Inc. This document is licensed under the SGI
 247             Free Software B License. For details, see
 248             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 249         </para>
 250     </refsect1>
 251 </refentry>