upstream-man-pages/man2/xhtml/glGetCompressedTexImage.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glGetCompressedTexImage</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glGetCompressedTexImage"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glGetCompressedTexImage — return a compressed texture image</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glGetCompressedTexImage</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLint  </td><td><var class="pdparam">lod</var>, </td></tr><tr><td> </td><td>GLvoid *  </td><td><var class="pdparam">img</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
   4                     Specifies which texture is to be obtained.
   5                     <code class="constant">GL_TEXTURE_1D</code>, <code class="constant">GL_TEXTURE_2D</code>, and <code class="constant">GL_TEXTURE_3D</code>
   6                     <code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_X</code>,
   7                     <code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_X</code>,
   8                     <code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Y</code>,
   9                     <code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</code>,
  10                     <code class="constant">GL_TEXTURE_CUBE_MAP_POSITIVE_Z</code>, and
  11                     <code class="constant">GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</code>
  12                     are accepted.
  13                 </p></dd><dt><span class="term"><em class="parameter"><code>lod</code></em></span></dt><dd><p>
  14                     Specifies the level-of-detail number of the desired image.
  15                     Level 0 is the base image level.
  16                     Level
  17                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>
  18                     is the
  19                     <mml:math xmlns:mml="http://www.w3.org/1998/Math/MathML" overflow="scroll"><mml:mi mathvariant="italic">n</mml:mi></mml:math>th
  20                     mipmap reduction image.
  21                 </p></dd><dt><span class="term"><em class="parameter"><code>img</code></em></span></dt><dd><p>
  22                     Returns the compressed texture image.
  23                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  24             <code class="function">glGetCompressedTexImage</code> returns the compressed texture image associated with <em class="parameter"><code>target</code></em> and <em class="parameter"><code>lod</code></em>
  25             into <em class="parameter"><code>img</code></em>.  <em class="parameter"><code>img</code></em> should be an array of
  26             <code class="constant">GL_TEXTURE_COMPRESSED_IMAGE_SIZE</code> bytes.
  27             <em class="parameter"><code>target</code></em> specifies whether the desired texture image was one specified by
  28             <a class="citerefentry" href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a> (<code class="constant">GL_TEXTURE_1D</code>),
  29             <a class="citerefentry" href="glTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a> (<code class="constant">GL_TEXTURE_2D</code> or any of <code class="constant">GL_TEXTURE_CUBE_MAP_*</code>), or
  30             <a class="citerefentry" href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a> (<code class="constant">GL_TEXTURE_3D</code>).
  31             <em class="parameter"><code>lod</code></em> specifies the level-of-detail number of the desired image.
  32         </p><p>
  33             If a non-zero named buffer object is bound to the <code class="constant">GL_PIXEL_PACK_BUFFER</code> target
  34             (see <a class="citerefentry" href="glBindBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>) while a texture image is
  35             requested, <em class="parameter"><code>img</code></em> is treated as a byte offset into the buffer object's data store.
  36         </p><p>
  37             To minimize errors, first verify that the texture is compressed by calling
  38             <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a> with argument <code class="constant">GL_TEXTURE_COMPRESSED</code>.  If
  39             the texture is compressed, then determine the amount of memory required to
  40             store the compressed texture by calling <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a> with
  41             argument <code class="constant">GL_TEXTURE_COMPRESSED_IMAGE_SIZE</code>.  Finally, retrieve the
  42             internal format of the texture by calling <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a> with
  43             argument <code class="constant">GL_TEXTURE_INTERNAL_FORMAT</code>.
  44             To store the texture for later use, associate the internal format and size
  45             with the retrieved texture image.  These data can be used by the respective
  46             texture or subtexture loading routine used for loading <em class="parameter"><code>target</code></em> textures.
  47         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
  48             <code class="function">glGetCompressedTexImage</code> is available only if the GL version is 1.3 or greater.
  49         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
  50             <code class="constant">GL_INVALID_VALUE</code> is generated if <em class="parameter"><code>lod</code></em> is less than zero or greater
  51             than the maximum number of LODs permitted by the implementation.
  52         </p><p>
  53             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glGetCompressedTexImage</code> is used to retrieve a
  54             texture that is in an uncompressed internal format.
  55         </p><p>
  56             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
  57             <code class="constant">GL_PIXEL_PACK_BUFFER</code> target and the buffer object's data store is currently mapped.
  58         </p><p>
  59             <code class="constant">GL_INVALID_OPERATION</code> is generated if a non-zero buffer object name is bound to the
  60             <code class="constant">GL_PIXEL_PACK_BUFFER</code> target and the data would be packed to the buffer
  61             object such that the memory writes required would exceed the data store size.
  62         </p><p>
  63             <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glGetCompressedTexImage</code>
  64             is executed between the execution of <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
  65             and the corresponding execution of <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.
  66         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
  67             <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a> with argument <code class="constant">GL_TEXTURE_COMPRESSED</code>
  68         </p><p>
  69             <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a> with argument <code class="constant">GL_TEXTURE_COMPRESSED_IMAGE_SIZE</code>
  70         </p><p>
  71             <a class="citerefentry" href="glGetTexLevelParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetTexLevelParameter</span></span></a> with argument <code class="constant">GL_TEXTURE_INTERNAL_FORMAT</code>
  72         </p><p>
  73             <a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with argument <code class="constant">GL_PIXEL_PACK_BUFFER_BINDING</code>
  74         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
  75             <a class="citerefentry" href="glActiveTexture.xml"><span class="citerefentry"><span class="refentrytitle">glActiveTexture</span></span></a>,
  76             <a class="citerefentry" href="glCompressedTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glCompressedTexImage1D</span></span></a>,
  77             <a class="citerefentry" href="glCompressedTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glCompressedTexImage2D</span></span></a>,
  78             <a class="citerefentry" href="glCompressedTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glCompressedTexImage3D</span></span></a>,
  79             <a class="citerefentry" href="glCompressedTexSubImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glCompressedTexSubImage1D</span></span></a>,
  80             <a class="citerefentry" href="glCompressedTexSubImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glCompressedTexSubImage2D</span></span></a>,
  81             <a class="citerefentry" href="glCompressedTexSubImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glCompressedTexSubImage3D</span></span></a>,
  82             <a class="citerefentry" href="glDrawPixels.xml"><span class="citerefentry"><span class="refentrytitle">glDrawPixels</span></span></a>,
  83             <a class="citerefentry" href="glReadPixels.xml"><span class="citerefentry"><span class="refentrytitle">glReadPixels</span></span></a>,
  84             <a class="citerefentry" href="glTexEnv.xml"><span class="citerefentry"><span class="refentrytitle">glTexEnv</span></span></a>,
  85             <a class="citerefentry" href="glTexGen.xml"><span class="citerefentry"><span class="refentrytitle">glTexGen</span></span></a>,
  86             <a class="citerefentry" href="glTexImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>,
  87             <a class="citerefentry" href="glTexImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a>,
  88             <a class="citerefentry" href="glTexImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a>,
  89             <a class="citerefentry" href="glTexParameter.xml"><span class="citerefentry"><span class="refentrytitle">glTexParameter</span></span></a>,
  90             <a class="citerefentry" href="glTexSubImage1D.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage1D</span></span></a>,
  91             <a class="citerefentry" href="glTexSubImage2D.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage2D</span></span></a>,
  92             <a class="citerefentry" href="glTexSubImage3D.xml"><span class="citerefentry"><span class="refentrytitle">glTexSubImage3D</span></span></a>
  93
  94         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
  95             Copyright <span class="trademark"></span>© 1991-2006
  96             Silicon Graphics, Inc. This document is licensed under the SGI
  97             Free Software B License. For details, see
  98             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
  99         </p></div></div></body></html>