[clinton/guile-figl.git] / upstream-doc / man2 / glGetColorTable.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="glGetColorTable">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glGetColorTable</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glGetColorTable</refname>
        <refpurpose>retrieve contents of a color lookup table</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glGetColorTable</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLenum <parameter>format</parameter></paramdef>
                <paramdef>GLenum <parameter>type</parameter></paramdef>
                <paramdef>GLvoid * <parameter>table</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Must be <constant>GL_COLOR_TABLE</constant>,
                    <constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>,
                    or
                    <constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>format</parameter></term>
            <listitem>
                <para>
                    The format of the pixel data in <parameter>table</parameter>.
                    The possible values are
                    <constant>GL_RED</constant>,
                    <constant>GL_GREEN</constant>,
                    <constant>GL_BLUE</constant>,
                    <constant>GL_ALPHA</constant>,
                    <constant>GL_LUMINANCE</constant>,
                    <constant>GL_LUMINANCE_ALPHA</constant>,
                    <constant>GL_RGB</constant>,
                    <constant>GL_BGR</constant>,
                    <constant>GL_RGBA</constant>, and
                    <constant>GL_BGRA</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>type</parameter></term>
            <listitem>
                <para>
                    The type of the pixel data in <parameter>table</parameter>.
                    Symbolic constants
                    <constant>GL_UNSIGNED_BYTE</constant>,
                    <constant>GL_BYTE</constant>,
                    <constant>GL_BITMAP</constant>,
                    <constant>GL_UNSIGNED_SHORT</constant>,
                    <constant>GL_SHORT</constant>,
                    <constant>GL_UNSIGNED_INT</constant>,
                    <constant>GL_INT</constant>,
                    <constant>GL_FLOAT</constant>,
                    <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
                    <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
                    <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
                    <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
                    <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
                    <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
                    <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
                    <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
                    <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
                    <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
                    <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
                    <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
                    are accepted.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>table</parameter></term>
            <listitem>
                <para>
                    Pointer to a one-dimensional array of pixel data containing the contents
                    of the color table.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glGetColorTable</function> returns in <parameter>table</parameter> the contents of the color table specified
            by <parameter>target</parameter>. No pixel transfer operations are performed, but pixel
            storage modes that are applicable to
            <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> are performed.
        </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 histogram table is
            requested, <parameter>table</parameter> is treated as a byte offset into the buffer object's data store.
        </para>
        <para>
            Color components that are requested in
            the specified <parameter>format</parameter>, but which are not included in the internal
            format of the color lookup table, are returned as zero.  The
            assignments of internal color components to the components
            requested by <parameter>format</parameter> are
        </para>
        <informaltable frame="topbot">
            <tgroup cols="2" align="left">
                <colspec/>
                <colspec/>
                <thead>
                    <row>
                        <entry rowsep="1" align="left"><emphasis role="bold">
                        Internal Component
                        </emphasis></entry>
                        <entry rowsep="1" align="left"><emphasis role="bold">
                        Resulting Component
                        </emphasis></entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry align="left">
                        Red
                        </entry>
                        <entry align="left">
                        Red
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        Green
                        </entry>
                        <entry align="left">
                        Green
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        Blue
                        </entry>
                        <entry align="left">
                        Blue
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        Alpha
                        </entry>
                        <entry align="left">
                        Alpha
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        Luminance
                        </entry>
                        <entry align="left">
                        Red
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        Intensity
                        </entry>
                        <entry align="left">
                        Red
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
        <para>
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glGetColorTable</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
            is called with an argument of <constant>GL_EXTENSIONS</constant>.
        </para>
        <para>
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
            values.
        </para>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
            values.
        </para>
        <para>
            <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
            values.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
            <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
            <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
            <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
            <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
            and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
            <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
            <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
            <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
            <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
            <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
            <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
            <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
            <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
            and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
        </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>
        <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 <parameter>table</parameter> is not evenly divisible 
            into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetColorTable</function> is executed
            between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
            execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
        </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>glColorTable</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glColorTableParameter</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="glGetColorTable">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glGetColorTable</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glGetColorTable</refname>
	17	<refpurpose>retrieve contents of a color lookup table</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glGetColorTable</function></funcdef>
	23	<paramdef>GLenum <parameter>target</parameter></paramdef>
	24	<paramdef>GLenum <parameter>format</parameter></paramdef>
	25	<paramdef>GLenum <parameter>type</parameter></paramdef>
	26	<paramdef>GLvoid * <parameter>table</parameter></paramdef>
	27	</funcprototype>
	28	</funcsynopsis>
	29	</refsynopsisdiv>
	30	<refsect1 id="parameters"><title>Parameters</title>
	31	<variablelist>
	32	<varlistentry>
	33	<term><parameter>target</parameter></term>
	34	<listitem>
	35	<para>
	36	Must be <constant>GL_COLOR_TABLE</constant>,
	37	<constant>GL_POST_CONVOLUTION_COLOR_TABLE</constant>,
	38	or
	39	<constant>GL_POST_COLOR_MATRIX_COLOR_TABLE</constant>.
	40	</para>
	41	</listitem>
	42	</varlistentry>
	43	<varlistentry>
	44	<term><parameter>format</parameter></term>
	45	<listitem>
	46	<para>
	47	The format of the pixel data in <parameter>table</parameter>.
	48	The possible values are
	49	<constant>GL_RED</constant>,
	50	<constant>GL_GREEN</constant>,
	51	<constant>GL_BLUE</constant>,
	52	<constant>GL_ALPHA</constant>,
	53	<constant>GL_LUMINANCE</constant>,
	54	<constant>GL_LUMINANCE_ALPHA</constant>,
	55	<constant>GL_RGB</constant>,
	56	<constant>GL_BGR</constant>,
	57	<constant>GL_RGBA</constant>, and
	58	<constant>GL_BGRA</constant>.
	59	</para>
	60	</listitem>
	61	</varlistentry>
	62	<varlistentry>
	63	<term><parameter>type</parameter></term>
	64	<listitem>
65	<para>
66	The type of the pixel data in <parameter>table</parameter>.
67	Symbolic constants
68	<constant>GL_UNSIGNED_BYTE</constant>,
69	<constant>GL_BYTE</constant>,
70	<constant>GL_BITMAP</constant>,
71	<constant>GL_UNSIGNED_SHORT</constant>,
72	<constant>GL_SHORT</constant>,
73	<constant>GL_UNSIGNED_INT</constant>,
74	<constant>GL_INT</constant>,
75	<constant>GL_FLOAT</constant>,
76	<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
77	<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
78	<constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
79	<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
80	<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
81	<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
82	<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
83	<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
84	<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
85	<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
86	<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
87	<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
88	are accepted.
89	</para>
90	</listitem>
91	</varlistentry>
92	<varlistentry>
93	<term><parameter>table</parameter></term>
94	<listitem>
95	<para>
96	Pointer to a one-dimensional array of pixel data containing the contents
97	of the color table.
98	</para>
99	</listitem>
100	</varlistentry>
101	</variablelist>
102	</refsect1>
103	<refsect1 id="description"><title>Description</title>
104	<para>
105	<function>glGetColorTable</function> returns in <parameter>table</parameter> the contents of the color table specified
106	by <parameter>target</parameter>. No pixel transfer operations are performed, but pixel
107	storage modes that are applicable to
108	<citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry> are performed.
109	</para>
110	<para>
111	If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target
112	(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a histogram table is
113	requested, <parameter>table</parameter> is treated as a byte offset into the buffer object's data store.
114	</para>
115	<para>
116	Color components that are requested in
117	the specified <parameter>format</parameter>, but which are not included in the internal
118	format of the color lookup table, are returned as zero. The
119	assignments of internal color components to the components
120	requested by <parameter>format</parameter> are
121	</para>
122	<informaltable frame="topbot">
123	<tgroup cols="2" align="left">
124	<colspec/>
125	<colspec/>
126	<thead>
127	<row>
128	<entry rowsep="1" align="left"><emphasis role="bold">
129	Internal Component
130	</emphasis></entry>
131	<entry rowsep="1" align="left"><emphasis role="bold">
132	Resulting Component
133	</emphasis></entry>
134	</row>
135	</thead>
136	<tbody>
137	<row>
138	<entry align="left">
139	Red
140	</entry>
141	<entry align="left">
142	Red
143	</entry>
144	</row>
145	<row>
146	<entry align="left">
147	Green
148	</entry>
149	<entry align="left">
150	Green
151	</entry>
152	</row>
153	<row>
154	<entry align="left">
155	Blue
156	</entry>
157	<entry align="left">
158	Blue
159	</entry>
160	</row>
161	<row>
162	<entry align="left">
163	Alpha
164	</entry>
165	<entry align="left">
166	Alpha
167	</entry>
168	</row>
169	<row>
170	<entry align="left">
171	Luminance
172	</entry>
173	<entry align="left">
174	Red
175	</entry>
176	</row>
177	<row>
178	<entry align="left">
179	Intensity
180	</entry>
181	<entry align="left">
182	Red
183	</entry>
184	</row>
185	</tbody>
186	</tgroup>
187	</informaltable>
188	<para>
189	</para>
190	</refsect1>
191	<refsect1 id="notes"><title>Notes</title>
192	<para>
193	<function>glGetColorTable</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
194	is called with an argument of <constant>GL_EXTENSIONS</constant>.
195	</para>
196	<para>
197	</para>
198	</refsect1>
199	<refsect1 id="errors"><title>Errors</title>
200	<para>
201	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the allowable
202	values.
203	</para>
204	<para>
205	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
206	values.
207	</para>
208	<para>
209	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not one of the allowable
210	values.
211	</para>
212	<para>
213	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
214	<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
215	<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
216	<constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
217	<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
218	and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
219	</para>
220	<para>
221	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
222	<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
223	<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
224	<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
225	<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
226	<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
227	<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
228	<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
229	<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
230	and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
231	</para>
232	<para>
233	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
234	<constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
235	</para>
236	<para>
237	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
238	<constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
239	object such that the memory writes required would exceed the data store size.
240	</para>
241	<para>
242	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
243	<constant>GL_PIXEL_PACK_BUFFER</constant> target and <parameter>table</parameter> is not evenly divisible
244	into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
245	</para>
246	<para>
247	<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetColorTable</function> is executed
248	between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
249	execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
250	</para>
251	</refsect1>
252	<refsect1 id="associatedgets"><title>Associated Gets</title>
253	<para>
254	<citerefentry><refentrytitle>glGetColorTableParameter</refentrytitle></citerefentry>
255	</para>
256	<para>
257	<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
258	</para>
259	</refsect1>
260	<refsect1 id="seealso"><title>See Also</title>
261	<para>
262	<citerefentry><refentrytitle>glColorTable</refentrytitle></citerefentry>,
263	<citerefentry><refentrytitle>glColorTableParameter</refentrytitle></citerefentry>
264	</para>
265	</refsect1>
266	<refsect1 id="Copyright"><title>Copyright</title>
267	<para>
268	Copyright <trademark class="copyright"></trademark> 1991-2006
269	Silicon Graphics, Inc. This document is licensed under the SGI
270	Free Software B License. For details, see
271	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
272	</para>
273	</refsect1>
274	</refentry>