[clinton/guile-figl.git] / upstream-doc / man3 / glGetCompressedTexImage.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glGetCompressedTexImage">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glGetCompressedTexImage</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glGetCompressedTexImage</refname>
        <refpurpose>return a compressed texture image</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glGetCompressedTexImage</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLint <parameter>lod</parameter></paramdef>
                <paramdef>GLvoid * <parameter>img</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies which texture is to be obtained.
                    <constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_3D</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
                    <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, and
                    <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>
                    are accepted.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>lod</parameter></term>
            <listitem>
                <para>
                    Specifies the level-of-detail number of the desired image.
                    Level 0 is the base image level.
                    Level 
                    <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
                    is the 
                    <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
                    mipmap reduction image.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>img</parameter></term>
            <listitem>
                <para>
                    Returns the compressed texture image.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glGetCompressedTexImage</function> returns the compressed texture image associated with <parameter>target</parameter> and <parameter>lod</parameter>
            into <parameter>img</parameter>.  <parameter>img</parameter> should be an array of
            <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant> bytes.
            <parameter>target</parameter> specifies whether the desired texture image was one specified by
            <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_1D</constant>),
            <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_2D</constant> or any of <constant>GL_TEXTURE_CUBE_MAP_*</constant>), or
            <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_3D</constant>).
            <parameter>lod</parameter> specifies the level-of-detail number of the desired image.
        </para>
        <para>
            If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target 
            (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
            requested, <parameter>img</parameter> is treated as a byte offset into the buffer object's data store.
        </para>
        <para>
            To minimize errors, first verify that the texture is compressed by calling
            <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>.  If
            the texture is compressed, then determine the amount of memory required to
            store the compressed texture by calling <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with
            argument <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>.  Finally, retrieve the
            internal format of the texture by calling <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with
            argument <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>.
            To store the texture for later use, associate the internal format and size
            with the retrieved texture image.  These data can be used by the respective
            texture or subtexture loading routine used for loading <parameter>target</parameter> textures.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>lod</parameter> is less than zero or greater
            than the maximum number of LODs permitted by the implementation.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetCompressedTexImage</function> is used to retrieve a
            texture that is in an uncompressed internal format.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
            <constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
            <constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer 
            object such that the memory writes required would exceed the data store size.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
        </para>
        <para>
            <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
        </para>
        <para>
            <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
        </para>
        <para>
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
        </para>
    </refsect1>
</refentry>
Commit	Line	Data
7faf1d71 AW	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>, <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="errors"><title>Errors</title>
102	<para>
103	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>lod</parameter> is less than zero or greater
104	than the maximum number of LODs permitted by the implementation.
105	</para>
106	<para>
107	<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetCompressedTexImage</function> is used to retrieve a
108	texture that is in an uncompressed internal format.
109	</para>
110	<para>
111	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
112	<constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
113	</para>
114	<para>
115	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
116	<constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
117	object such that the memory writes required would exceed the data store size.
118	</para>
119	</refsect1>
120	<refsect1 id="associatedgets"><title>Associated Gets</title>
121	<para>
122	<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
123	</para>
124	<para>
125	<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
126	</para>
127	<para>
128	<citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
129	</para>
130	<para>
131	<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
132	</para>
133	</refsect1>
134	<refsect1 id="seealso"><title>See Also</title>
135	<para>
136	<citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
137	<citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
138	<citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
139	<citerefentry><refentrytitle>glCompressedTexImage3D</refentrytitle></citerefentry>,
140	<citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
141	<citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
142	<citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
143	<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
144	<citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
145	<citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
146	<citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
147	<citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
148	<citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
149	<citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
150	<citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
151	</para>
152	</refsect1>
153	<refsect1 id="Copyright"><title>Copyright</title>
154	<para>
155	Copyright <trademark class="copyright"></trademark> 1991-2006
156	Silicon Graphics, Inc. This document is licensed under the SGI
157	Free Software B License. For details, see
158	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
159	</para>
160	</refsect1>
161	</refentry>