upstream-man-pages/man2/glGetCompressedTexImage.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="glGetCompressedTexImage">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetCompressedTexImage</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetCompressedTexImage</refname>
  17         <refpurpose>return a compressed texture image</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glGetCompressedTexImage</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>lod</parameter></paramdef>
  25                 <paramdef>GLvoid * <parameter>img</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28     </refsynopsisdiv>
  29     <!-- eqn: ignoring delim $$ -->
  30     <refsect1 id="parameters"><title>Parameters</title>
  31         <variablelist>
  32         <varlistentry>
  33             <term><parameter>target</parameter></term>
  34             <listitem>
  35                 <para>
  36                     Specifies which texture is to be obtained.
  37                     <constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_2D</constant>, and <constant>GL_TEXTURE_3D</constant>
  38                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
  39                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
  40                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
  41                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
  42                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, and
  43                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>
  44                     are accepted.
  45                 </para>
  46             </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49             <term><parameter>lod</parameter></term>
  50             <listitem>
  51                 <para>
  52                     Specifies the level-of-detail number of the desired image.
  53                     Level 0 is the base image level.
  54                     Level
  55                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
  56                     is the
  57                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
  58                     mipmap reduction image.
  59                 </para>
  60             </listitem>
  61         </varlistentry>
  62         <varlistentry>
  63             <term><parameter>img</parameter></term>
  64             <listitem>
  65                 <para>
  66                     Returns the compressed texture image.
  67                 </para>
  68             </listitem>
  69         </varlistentry>
  70         </variablelist>
  71     </refsect1>
  72     <refsect1 id="description"><title>Description</title>
  73         <para>
  74             <function>glGetCompressedTexImage</function> returns the compressed texture image associated with <parameter>target</parameter> and <parameter>lod</parameter>
  75             into <parameter>img</parameter>.  <parameter>img</parameter> should be an array of
  76             <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant> bytes.
  77             <parameter>target</parameter> specifies whether the desired texture image was one specified by
  78             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_1D</constant>),
  79             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_2D</constant> or any of <constant>GL_TEXTURE_CUBE_MAP_*</constant>), or
  80             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_3D</constant>).
  81             <parameter>lod</parameter> specifies the level-of-detail number of the desired image.
  82         </para>
  83         <para>
  84             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target
  85             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
  86             requested, <parameter>img</parameter> is treated as a byte offset into the buffer object's data store.
  87         </para>
  88         <para>
  89             To minimize errors, first verify that the texture is compressed by calling
  90             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>.  If
  91             the texture is compressed, then determine the amount of memory required to
  92             store the compressed texture by calling <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with
  93             argument <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>.  Finally, retrieve the
  94             internal format of the texture by calling <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with
  95             argument <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>.
  96             To store the texture for later use, associate the internal format and size
  97             with the retrieved texture image.  These data can be used by the respective
  98             texture or subtexture loading routine used for loading <parameter>target</parameter> textures.
  99         </para>
 100     </refsect1>
 101     <refsect1 id="notes"><title>Notes</title>
 102         <para>
 103             <function>glGetCompressedTexImage</function> is available only if the GL version is 1.3 or greater.
 104         </para>
 105     </refsect1>
 106     <refsect1 id="errors"><title>Errors</title>
 107         <para>
 108             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>lod</parameter> is less than zero or greater
 109             than the maximum number of LODs permitted by the implementation.
 110         </para>
 111         <para>
 112             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetCompressedTexImage</function> is used to retrieve a
 113             texture that is in an uncompressed internal format.
 114         </para>
 115         <para>
 116             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 117             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 118         </para>
 119         <para>
 120             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 121             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
 122             object such that the memory writes required would exceed the data store size.
 123         </para>
 124         <para>
 125             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetCompressedTexImage</function>
 126             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 127             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 128         </para>
 129     </refsect1>
 130     <refsect1 id="associatedgets"><title>Associated Gets</title>
 131         <para>
 132             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
 133         </para>
 134         <para>
 135             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
 136         </para>
 137         <para>
 138             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
 139         </para>
 140         <para>
 141             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
 142         </para>
 143     </refsect1>
 144     <refsect1 id="seealso"><title>See Also</title>
 145         <para>
 146             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 147             <citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
 148             <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
 149             <citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
 150             <citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
 151             <citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
 152             <citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
 153             <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>,
 154             <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
 155             <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
 156             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 157             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 158             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 159             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 160             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 161             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 162             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 163             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
 164
 165         </para>
 166     </refsect1>
 167     <refsect1 id="Copyright"><title>Copyright</title>
 168         <para>
 169             Copyright <trademark class="copyright"></trademark> 1991-2006
 170             Silicon Graphics, Inc. This document is licensed under the SGI
 171             Free Software B License. For details, see
 172             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 173         </para>
 174     </refsect1>
 175 </refentry>