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