[clinton/guile-figl.git] / upstream-doc / man2 / glGetMinmax.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="glGetMinmax">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glGetMinmax</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glGetMinmax</refname>
        <refpurpose>get minimum and maximum pixel values</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glGetMinmax</function></funcdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLboolean <parameter>reset</parameter></paramdef>
                <paramdef>GLenum <parameter>format</parameter></paramdef>
                <paramdef>GLenum <parameter>types</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_MINMAX</constant>.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>reset</parameter></term>
            <listitem>
                <para>
                    If <constant>GL_TRUE</constant>, all entries in the minmax table that are actually
                    returned are reset to their initial values.  (Other entries are unaltered.)
                    If <constant>GL_FALSE</constant>, the minmax table is unaltered.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>format</parameter></term>
            <listitem>
                <para>
                    The format of the data 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>types</parameter></term>
            <listitem>
                <para>
                    The type of the data 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 values.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glGetMinmax</function> returns the accumulated minimum and maximum pixel values (computed on a
            per-component basis) in a one-dimensional image of width 2.  The first set
            of return values are the minima, and the second set of return values
            are the maxima.
            The format of the return values is determined by <parameter>format</parameter>, and their type is
            determined by <parameter>types</parameter>.
        </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 minimum and maximum pixel values are
            requested, <parameter>values</parameter> is treated as a byte offset into the buffer object's data store.
        </para>
        <para>
            No pixel transfer operations are performed on the return values, but pixel
            storage modes that are applicable to one-dimensional images are performed.
            Color components that are requested in the specified <parameter>format</parameter>, but that
            are not included in the internal format of the minmax table, are
            returned as zero.  The assignment of internal color components to the
            components requested by <parameter>format</parameter> are as follows:
        </para>
        <para>
        </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>
            If <parameter>reset</parameter> is <constant>GL_TRUE</constant>, the minmax table entries corresponding
            to the return values are reset to their initial
            values.  Minimum and maximum values that are not returned are not
            modified, even if <parameter>reset</parameter> is <constant>GL_TRUE</constant>.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glGetMinmax</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_MINMAX</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>types</parameter> is not one of the allowable
            values.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>types</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>types</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>glGetMinmax</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>glGetMinmaxParameter</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>glMinmax</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glResetMinmax</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="glGetMinmax">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glGetMinmax</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glGetMinmax</refname>
	17	<refpurpose>get minimum and maximum pixel values</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>void <function>glGetMinmax</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>types</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_MINMAX</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>, all entries in the minmax table that are actually
	47	returned are reset to their initial values. (Other entries are unaltered.)
	48	If <constant>GL_FALSE</constant>, the minmax table is unaltered.
	49	</para>
	50	</listitem>
	51	</varlistentry>
	52	<varlistentry>
	53	<term><parameter>format</parameter></term>
	54	<listitem>
	55	<para>
	56	The format of the data 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>types</parameter></term>
73	<listitem>
74	<para>
75	The type of the data 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 values.
106	</para>
107	</listitem>
108	</varlistentry>
109	</variablelist>
110	</refsect1>
111	<refsect1 id="description"><title>Description</title>
112	<para>
113	<function>glGetMinmax</function> returns the accumulated minimum and maximum pixel values (computed on a
114	per-component basis) in a one-dimensional image of width 2. The first set
115	of return values are the minima, and the second set of return values
116	are the maxima.
117	The format of the return values is determined by <parameter>format</parameter>, and their type is
118	determined by <parameter>types</parameter>.
119	</para>
120	<para>
121	If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target
122	(see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while minimum and maximum pixel values are
123	requested, <parameter>values</parameter> is treated as a byte offset into the buffer object's data store.
124	</para>
125	<para>
126	No pixel transfer operations are performed on the return values, but pixel
127	storage modes that are applicable to one-dimensional images are performed.
128	Color components that are requested in the specified <parameter>format</parameter>, but that
129	are not included in the internal format of the minmax table, are
130	returned as zero. The assignment of internal color components to the
131	components requested by <parameter>format</parameter> are as follows:
132	</para>
133	<para>
134	</para>
135	<informaltable frame="topbot">
136	<tgroup cols="2" align="left">
137	<colspec/>
138	<colspec/>
139	<thead>
140	<row>
141	<entry rowsep="1" align="left"><emphasis role="bold">
142	Internal Component
143	</emphasis></entry>
144	<entry rowsep="1" align="left"><emphasis role="bold">
145	Resulting Component
146	</emphasis></entry>
147	</row>
148	</thead>
149	<tbody>
150	<row>
151	<entry align="left">
152	Red
153	</entry>
154	<entry align="left">
155	Red
156	</entry>
157	</row>
158	<row>
159	<entry align="left">
160	Green
161	</entry>
162	<entry align="left">
163	Green
164	</entry>
165	</row>
166	<row>
167	<entry align="left">
168	Blue
169	</entry>
170	<entry align="left">
171	Blue
172	</entry>
173	</row>
174	<row>
175	<entry align="left">
176	Alpha
177	</entry>
178	<entry align="left">
179	Alpha
180	</entry>
181	</row>
182	<row>
183	<entry align="left">
184	Luminance
185	</entry>
186	<entry align="left">
187	Red
188	</entry>
189	</row>
190	</tbody>
191	</tgroup>
192	</informaltable>
193	<para>
194	If <parameter>reset</parameter> is <constant>GL_TRUE</constant>, the minmax table entries corresponding
195	to the return values are reset to their initial
196	values. Minimum and maximum values that are not returned are not
197	modified, even if <parameter>reset</parameter> is <constant>GL_TRUE</constant>.
198	</para>
199	</refsect1>
200	<refsect1 id="notes"><title>Notes</title>
201	<para>
202	<function>glGetMinmax</function> is present only if <code>ARB_imaging</code> is returned when <citerefentry><refentrytitle>glGetString</refentrytitle></citerefentry>
203	is called with an argument of <constant>GL_EXTENSIONS</constant>.
204	</para>
205	</refsect1>
206	<refsect1 id="errors"><title>Errors</title>
207	<para>
208	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not <constant>GL_MINMAX</constant>.
209	</para>
210	<para>
211	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not one of the allowable
212	values.
213	</para>
214	<para>
215	<constant>GL_INVALID_ENUM</constant> is generated if <parameter>types</parameter> is not one of the allowable
216	values.
217	</para>
218	<para>
219	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>types</parameter> is one of
220	<constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
221	<constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
222	<constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
223	<constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
224	and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
225	</para>
226	<para>
227	<constant>GL_INVALID_OPERATION</constant> is generated if <parameter>types</parameter> is one of
228	<constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
229	<constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
230	<constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
231	<constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
232	<constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
233	<constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
234	<constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
235	<constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
236	and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
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 the buffer object's data store is currently mapped.
241	</para>
242	<para>
243	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
244	<constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
245	object such that the memory writes required would exceed the data store size.
246	</para>
247	<para>
248	<constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
249	<constant>GL_PIXEL_PACK_BUFFER</constant> target and <parameter>values</parameter> is not evenly divisible
250	into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
251	</para>
252	<para>
253	<constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetMinmax</function> is executed
254	between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry> and the corresponding
255	execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
256	</para>
257	</refsect1>
258	<refsect1 id="associatedgets"><title>Associated Gets</title>
259	<para>
260	<citerefentry><refentrytitle>glGetMinmaxParameter</refentrytitle></citerefentry>
261	</para>
262	<para>
263	<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
264	</para>
265	</refsect1>
266	<refsect1 id="seealso"><title>See Also</title>
267	<para>
268	<citerefentry><refentrytitle>glMinmax</refentrytitle></citerefentry>,
269	<citerefentry><refentrytitle>glResetMinmax</refentrytitle></citerefentry>,
270	</para>
271	</refsect1>
272	<refsect1 id="Copyright"><title>Copyright</title>
273	<para>
274	Copyright <trademark class="copyright"></trademark> 1991-2006
275	Silicon Graphics, Inc. This document is licensed under the SGI
276	Free Software B License. For details, see
277	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
278	</para>
279	</refsect1>
280	</refentry>