2009-03-08 00:46:58 +00:00
<?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= "glReadPixels" >
<refmeta >
2014-03-28 19:06:55 +00:00
<refmetainfo >
<copyright >
<year > 1991-2006</year>
<holder > Silicon Graphics, Inc.</holder>
</copyright>
</refmetainfo>
2009-03-08 00:46:58 +00:00
<refentrytitle > glReadPixels</refentrytitle>
<manvolnum > 3G</manvolnum>
</refmeta>
<refnamediv >
<refname > glReadPixels</refname>
<refpurpose > read a block of pixels from the frame buffer</refpurpose>
</refnamediv>
<refsynopsisdiv > <title > C Specification</title>
<funcsynopsis >
<funcprototype >
<funcdef > void <function > glReadPixels</function> </funcdef>
<paramdef > GLint <parameter > x</parameter> </paramdef>
<paramdef > GLint <parameter > y</parameter> </paramdef>
<paramdef > GLsizei <parameter > width</parameter> </paramdef>
<paramdef > GLsizei <parameter > height</parameter> </paramdef>
<paramdef > GLenum <parameter > format</parameter> </paramdef>
<paramdef > GLenum <parameter > type</parameter> </paramdef>
<paramdef > GLvoid * <parameter > data</parameter> </paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
2014-03-28 19:06:55 +00:00
<!-- eqn: ignoring delim $$ -->
2009-03-08 00:46:58 +00:00
<refsect1 id= "parameters" > <title > Parameters</title>
<variablelist >
<varlistentry >
<term > <parameter > x</parameter> </term>
<term > <parameter > y</parameter> </term>
<listitem >
<para >
Specify the window coordinates of the first pixel
that is read from the frame buffer.
This location is the lower left corner of a rectangular block of pixels.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > width</parameter> </term>
<term > <parameter > height</parameter> </term>
<listitem >
<para >
Specify the dimensions of the pixel rectangle.
<parameter > width</parameter> and <parameter > height</parameter> of one correspond to a single pixel.
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > format</parameter> </term>
<listitem >
<para >
Specifies the format of the pixel data.
The following symbolic values are accepted:
2014-03-28 19:06:55 +00:00
<constant > GL_COLOR_INDEX</constant> ,
2009-03-08 00:46:58 +00:00
<constant > GL_STENCIL_INDEX</constant> ,
<constant > GL_DEPTH_COMPONENT</constant> ,
<constant > GL_RED</constant> ,
<constant > GL_GREEN</constant> ,
<constant > GL_BLUE</constant> ,
2014-03-28 19:06:55 +00:00
<constant > GL_ALPHA</constant> ,
2009-03-08 00:46:58 +00:00
<constant > GL_RGB</constant> ,
<constant > GL_BGR</constant> ,
2014-03-28 19:06:55 +00:00
<constant > GL_RGBA</constant> ,
<constant > GL_BGRA</constant> ,
<constant > GL_LUMINANCE</constant> , and
<constant > GL_LUMINANCE_ALPHA</constant> .
2009-03-08 00:46:58 +00:00
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > type</parameter> </term>
<listitem >
<para >
Specifies the data type of the pixel data.
Must be one of
<constant > GL_UNSIGNED_BYTE</constant> ,
<constant > GL_BYTE</constant> ,
2014-03-28 19:06:55 +00:00
<constant > GL_BITMAP</constant> ,
2009-03-08 00:46:58 +00:00
<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> ,
2014-03-28 19:06:55 +00:00
<constant > GL_UNSIGNED_INT_10_10_10_2</constant> , or
<constant > GL_UNSIGNED_INT_2_10_10_10_REV</constant> .
2009-03-08 00:46:58 +00:00
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <parameter > data</parameter> </term>
<listitem >
<para >
Returns the pixel data.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id= "description" > <title > Description</title>
<para >
<function > glReadPixels</function> returns pixel data from the frame buffer,
starting with the pixel whose lower left corner
is at location (<parameter > x</parameter> , <parameter > y</parameter> ),
into client memory starting at location <parameter > data</parameter> .
Several parameters control the processing of the pixel data before
it is placed into client memory.
2014-03-28 19:06:55 +00:00
These parameters are set with three commands:
<citerefentry > <refentrytitle > glPixelStore</refentrytitle> </citerefentry> ,
<citerefentry > <refentrytitle > glPixelTransfer</refentrytitle> </citerefentry> , and
<citerefentry > <refentrytitle > glPixelMap</refentrytitle> </citerefentry> .
2009-03-08 00:46:58 +00:00
This reference page describes the effects on <function > glReadPixels</function> of most,
but not all of the parameters specified by these three commands.
</para>
<para >
2014-03-28 19:06:55 +00:00
If a non-zero named buffer object is bound to the <constant > GL_PIXEL_PACK_BUFFER</constant> target
2009-03-08 00:46:58 +00:00
(see <citerefentry > <refentrytitle > glBindBuffer</refentrytitle> </citerefentry> ) while a block of pixels is
requested, <parameter > data</parameter> is treated as a byte offset into the buffer object's data store
rather than a pointer to client memory.
</para>
2014-03-28 19:06:55 +00:00
<para >
When the <code > ARB_imaging</code> extension is supported, the pixel data may
be processed by additional operations including color table lookup,
color matrix transformations, convolutions, histograms, and minimum and
maximum pixel value computations.
</para>
2009-03-08 00:46:58 +00:00
<para >
<function > glReadPixels</function> returns values from each pixel with lower left corner at
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: (x + i, y + j): -->
2009-03-08 00:46:58 +00:00
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:mi mathvariant= "italic" > x</mml:mi>
<mml:mo > +</mml:mo>
<mml:mi mathvariant= "italic" > i</mml:mi>
</mml:mrow>
<mml:mrow >
<mml:mi mathvariant= "italic" > y</mml:mi>
<mml:mo > +</mml:mo>
<mml:mi mathvariant= "italic" > j</mml:mi>
</mml:mrow>
</mml:mfenced>
</mml:math> </inlineequation>
2014-03-28 19:06:55 +00:00
for
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 0 <= i < width: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:mn > 0</mml:mn>
<mml:mo > < =</mml:mo>
<mml:mi mathvariant= "italic" > i</mml:mi>
<mml:mo > < </mml:mo>
<mml:mi mathvariant= "italic" > width</mml:mi>
</mml:mrow>
</mml:math> </inlineequation>
and
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 0 <= j < height: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:mn > 0</mml:mn>
<mml:mo > < =</mml:mo>
<mml:mi mathvariant= "italic" > j</mml:mi>
<mml:mo > < </mml:mo>
<mml:mi mathvariant= "italic" > height</mml:mi>
</mml:mrow>
</mml:math> </inlineequation> .
2014-03-28 19:06:55 +00:00
This pixel is said to be the
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > i</mml:mi> </mml:math> </inlineequation> th
2014-03-28 19:06:55 +00:00
pixel in the
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > j</mml:mi> </mml:math> </inlineequation> th
row.
Pixels are returned in row order from the lowest to the highest row,
left to right in each row.
</para>
<para >
<parameter > format</parameter> specifies the format for the returned pixel values;
accepted values are:
</para>
<variablelist >
2014-03-28 19:06:55 +00:00
<varlistentry >
<term > <constant > GL_COLOR_INDEX</constant> </term>
<listitem >
<para >
Color indices are read from the color buffer
selected by <citerefentry > <refentrytitle > glReadBuffer</refentrytitle> </citerefentry> .
Each index is converted to fixed point,
shifted left or right depending on the value and sign of <constant > GL_INDEX_SHIFT</constant> ,
and added to <constant > GL_INDEX_OFFSET</constant> .
If <constant > GL_MAP_COLOR</constant> is <constant > GL_TRUE</constant> ,
indices are replaced by their mappings in the table <constant > GL_PIXEL_MAP_I_TO_I</constant> .
</para>
</listitem>
</varlistentry>
2009-03-08 00:46:58 +00:00
<varlistentry >
<term > <constant > GL_STENCIL_INDEX</constant> </term>
<listitem >
<para >
Stencil values are read from the stencil buffer.
2014-03-28 19:06:55 +00:00
Each index is converted to fixed point,
shifted left or right depending on the value and sign of <constant > GL_INDEX_SHIFT</constant> ,
and added to <constant > GL_INDEX_OFFSET</constant> .
If <constant > GL_MAP_STENCIL</constant> is <constant > GL_TRUE</constant> ,
indices are replaced by their mappings in the table <constant > GL_PIXEL_MAP_S_TO_S</constant> .
2009-03-08 00:46:58 +00:00
</para>
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_DEPTH_COMPONENT</constant> </term>
<listitem >
<para >
Depth values are read from the depth buffer.
Each component is converted to floating point such that the minimum depth
value maps to 0 and the maximum value maps to 1.
2014-03-28 19:06:55 +00:00
Each component is then multiplied by <constant > GL_DEPTH_SCALE</constant> ,
added to <constant > GL_DEPTH_BIAS</constant> ,
and finally clamped to the range
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: [0,1]: -->
2009-03-08 00:46:58 +00:00
<mml:mfenced open= "[" close= "]" >
<mml:mn > 0</mml:mn>
<mml:mn > 1</mml:mn>
</mml:mfenced>
</mml:math> </inlineequation> .
</para>
</listitem>
</varlistentry>
<varlistentry >
2014-03-28 19:06:55 +00:00
<term > <constant > GL_RED</constant> </term>
<listitem >
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_GREEN</constant> </term>
<listitem >
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_BLUE</constant> </term>
<listitem >
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_ALPHA</constant> </term>
<listitem >
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_RGB</constant> </term>
<listitem >
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_BGR</constant> </term>
<listitem >
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_RGBA</constant> </term>
2009-03-08 00:46:58 +00:00
<listitem >
</listitem>
</varlistentry>
<varlistentry >
2014-03-28 19:06:55 +00:00
<term > <constant > GL_BGRA</constant> </term>
2009-03-08 00:46:58 +00:00
<listitem >
2014-03-28 19:06:55 +00:00
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_LUMINANCE</constant> </term>
<listitem >
</listitem>
</varlistentry>
<varlistentry >
<term > <constant > GL_LUMINANCE_ALPHA</constant> </term>
<listitem >
<para >
Processing differs depending on whether color buffers store color indices
or RGBA color components.
If color indices are stored,
they are read from the color buffer selected by <citerefentry > <refentrytitle > glReadBuffer</refentrytitle> </citerefentry> .
Each index is converted to fixed point,
shifted left or right depending on the value and sign of <constant > GL_INDEX_SHIFT</constant> ,
and added to <constant > GL_INDEX_OFFSET</constant> .
Indices are then replaced by the red,
green,
blue,
and alpha values obtained by indexing the tables
<constant > GL_PIXEL_MAP_I_TO_R</constant> ,
<constant > GL_PIXEL_MAP_I_TO_G</constant> ,
<constant > GL_PIXEL_MAP_I_TO_B</constant> , and
<constant > GL_PIXEL_MAP_I_TO_A</constant> .
Each table must be of size
<inlineequation > <mml:math >
<!-- eqn: 2 sup n: -->
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mi mathvariant= "italic" > n</mml:mi>
</mml:msup>
</mml:math> </inlineequation> ,
but
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > n</mml:mi> </mml:math> </inlineequation>
may be different for
different tables.
Before an index is used to look up a value in a table of
size
<inlineequation > <mml:math >
<!-- eqn: 2 sup n: -->
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mi mathvariant= "italic" > n</mml:mi>
</mml:msup>
</mml:math> </inlineequation> ,
it must be masked against
<inlineequation > <mml:math >
<!-- eqn: 2 sup n - 1: -->
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mi mathvariant= "italic" > n</mml:mi>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:math> </inlineequation> .
</para>
<para >
If RGBA color components are stored in the color buffers,
they are read from the color buffer selected by <citerefentry > <refentrytitle > glReadBuffer</refentrytitle> </citerefentry> .
Each color component is converted to floating point such that zero intensity
maps to 0.0 and full intensity maps to 1.0.
Each component is then multiplied by <constant > GL_c_SCALE</constant> and
added to <constant > GL_c_BIAS</constant> ,
where <emphasis > c</emphasis> is RED, GREEN, BLUE, or ALPHA.
Finally,
if <constant > GL_MAP_COLOR</constant> is <constant > GL_TRUE</constant> ,
each component is clamped to the range
<inlineequation > <mml:math >
<!-- eqn: [0,1]: -->
<mml:mfenced open= "[" close= "]" >
<mml:mn > 0</mml:mn>
<mml:mn > 1</mml:mn>
</mml:mfenced>
</mml:math> </inlineequation> ,
scaled to the size of its corresponding table, and is then
replaced by its mapping in the table
<constant > GL_PIXEL_MAP_c_TO_c</constant> ,
where <emphasis > c</emphasis> is R, G, B, or A.
</para>
<para >
Unneeded data is then discarded.
For example,
<constant > GL_RED</constant> discards the green, blue, and alpha components,
while <constant > GL_RGB</constant> discards only the alpha component.
<constant > GL_LUMINANCE</constant> computes a single-component value as the sum of
the red,
green,
and blue components,
and <constant > GL_LUMINANCE_ALPHA</constant> does the same,
while keeping alpha as a second value.
The final values are clamped to the range
<inlineequation > <mml:math >
<!-- eqn: [0,1]: -->
<mml:mfenced open= "[" close= "]" >
<mml:mn > 0</mml:mn>
<mml:mn > 1</mml:mn>
</mml:mfenced>
</mml:math> </inlineequation> .
</para>
2009-03-08 00:46:58 +00:00
</listitem>
</varlistentry>
</variablelist>
2014-03-28 19:06:55 +00:00
<para >
The shift,
scale,
bias,
and lookup factors just described are all specified by
<citerefentry > <refentrytitle > glPixelTransfer</refentrytitle> </citerefentry> .
The lookup table contents themselves are specified by <citerefentry > <refentrytitle > glPixelMap</refentrytitle> </citerefentry> .
</para>
2009-03-08 00:46:58 +00:00
<para >
Finally, the indices or components
are converted to the proper format,
as specified by <parameter > type</parameter> .
2014-03-28 19:06:55 +00:00
If <parameter > format</parameter> is <constant > GL_COLOR_INDEX</constant> or <constant > GL_STENCIL_INDEX</constant>
2009-03-08 00:46:58 +00:00
and <parameter > type</parameter> is not <constant > GL_FLOAT</constant> ,
each index is masked with the mask value given in the following table.
If <parameter > type</parameter> is <constant > GL_FLOAT</constant> , then each integer index is converted to
single-precision floating-point format.
</para>
<para >
If <parameter > format</parameter> is
<constant > GL_RED</constant> ,
<constant > GL_GREEN</constant> ,
<constant > GL_BLUE</constant> ,
2014-03-28 19:06:55 +00:00
<constant > GL_ALPHA</constant> ,
2009-03-08 00:46:58 +00:00
<constant > GL_RGB</constant> ,
<constant > GL_BGR</constant> ,
2014-03-28 19:06:55 +00:00
<constant > GL_RGBA</constant> ,
<constant > GL_BGRA</constant> ,
<constant > GL_LUMINANCE</constant> , or
<constant > GL_LUMINANCE_ALPHA</constant> and <parameter > type</parameter> is not <constant > GL_FLOAT</constant> ,
2009-03-08 00:46:58 +00:00
each component is multiplied by the multiplier shown in the following table.
If type is <constant > GL_FLOAT</constant> , then each component is passed as is
(or converted to the client's single-precision floating-point format if
it is different from the one used by the GL).
</para>
<para >
</para>
2014-03-28 19:06:55 +00:00
<informaltable frame= "topbot" >
<tgroup cols= "3" align= "left" >
<colspec />
<colspec align= "center" />
<colspec align= "center" />
2009-03-08 00:46:58 +00:00
<thead >
<row >
2014-03-28 19:06:55 +00:00
<entry rowsep= "1" align= "left" >
<parameter > type</parameter>
</entry>
<entry rowsep= "1" align= "center" > <emphasis role= "bold" >
Index Mask
</emphasis> </entry>
<entry rowsep= "1" align= "center" > <emphasis role= "bold" >
Component Conversion
</emphasis> </entry>
2009-03-08 00:46:58 +00:00
</row>
</thead>
<tbody >
<row >
2014-03-28 19:06:55 +00:00
<entry align= "left" >
2009-03-08 00:46:58 +00:00
<constant > GL_UNSIGNED_BYTE</constant>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 2 sup 8 - 1: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 8</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: (2 sup 8 - 1) c: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 8</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mi mathvariant= "italic" > c</mml:mi>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
</row>
<row >
2014-03-28 19:06:55 +00:00
<entry align= "left" >
2009-03-08 00:46:58 +00:00
<constant > GL_BYTE</constant>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 2 sup 7 - 1: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 7</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: {(2 sup 8 - 1) c - 1} / 2: -->
2009-03-08 00:46:58 +00:00
<mml:mfrac >
<mml:mfenced open= "" close= "" >
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 8</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mi mathvariant= "italic" > c</mml:mi>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mn > 2</mml:mn>
</mml:mfrac>
</mml:math> </inlineequation>
</entry>
</row>
<row >
2014-03-28 19:06:55 +00:00
<entry align= "left" >
<constant > GL_BITMAP</constant>
</entry>
<entry align= "center" >
<inlineequation > <mml:math >
<!-- eqn: 1: -->
<mml:mn > 1</mml:mn>
</mml:math> </inlineequation>
</entry>
<entry align= "center" >
<inlineequation > <mml:math >
<!-- eqn: 1: -->
<mml:mn > 1</mml:mn>
</mml:math> </inlineequation>
</entry>
</row>
<row >
<entry align= "left" >
2009-03-08 00:46:58 +00:00
<constant > GL_UNSIGNED_SHORT</constant>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 2 sup 16 - 1: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 16</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: (2 sup 16 - 1) c: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 16</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mi mathvariant= "italic" > c</mml:mi>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
</row>
<row >
2014-03-28 19:06:55 +00:00
<entry align= "left" >
2009-03-08 00:46:58 +00:00
<constant > GL_SHORT</constant>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 2 sup 15 - 1: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 15</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: {(2 sup 16 - 1) c - 1} / 2: -->
2009-03-08 00:46:58 +00:00
<mml:mfrac >
<mml:mfenced open= "" close= "" >
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 16</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mi mathvariant= "italic" > c</mml:mi>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mn > 2</mml:mn>
</mml:mfrac>
</mml:math> </inlineequation>
</entry>
</row>
<row >
2014-03-28 19:06:55 +00:00
<entry align= "left" >
2009-03-08 00:46:58 +00:00
<constant > GL_UNSIGNED_INT</constant>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 2 sup 32 - 1: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 32</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: (2 sup 32 - 1) c: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 32</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mi mathvariant= "italic" > c</mml:mi>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
</row>
<row >
2014-03-28 19:06:55 +00:00
<entry align= "left" >
2009-03-08 00:46:58 +00:00
<constant > GL_INT</constant>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: 2 sup 31 - 1: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 31</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:math> </inlineequation>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: {(2 sup 32 - 1) c - 1} / 2: -->
2009-03-08 00:46:58 +00:00
<mml:mfrac >
<mml:mfenced open= "" close= "" >
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mrow >
<mml:msup > <mml:mn > 2</mml:mn>
<mml:mn > 32</mml:mn>
</mml:msup>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mi mathvariant= "italic" > c</mml:mi>
<mml:mo > -</mml:mo>
<mml:mn > 1</mml:mn>
</mml:mrow>
</mml:mfenced>
<mml:mn > 2</mml:mn>
</mml:mfrac>
</mml:math> </inlineequation>
</entry>
</row>
2010-11-21 14:34:29 +00:00
<row >
2014-03-28 19:06:55 +00:00
<entry align= "left" >
2009-03-08 00:46:58 +00:00
<constant > GL_FLOAT</constant>
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
none
</entry>
2014-03-28 19:06:55 +00:00
<entry align= "center" >
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > c</mml:mi> </mml:math> </inlineequation>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para >
Return values are placed in memory as follows.
If <parameter > format</parameter> is
2014-03-28 19:06:55 +00:00
<constant > GL_COLOR_INDEX</constant> ,
2009-03-08 00:46:58 +00:00
<constant > GL_STENCIL_INDEX</constant> ,
<constant > GL_DEPTH_COMPONENT</constant> ,
<constant > GL_RED</constant> ,
2014-03-28 19:06:55 +00:00
<constant > GL_GREEN</constant> ,
2009-03-08 00:46:58 +00:00
<constant > GL_BLUE</constant> ,
2014-03-28 19:06:55 +00:00
<constant > GL_ALPHA</constant> , or
<constant > GL_LUMINANCE</constant> ,
a single value is returned and the data for the
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > i</mml:mi> </mml:math> </inlineequation> th
2014-03-28 19:06:55 +00:00
pixel in the
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math > <mml:mi mathvariant= "italic" > j</mml:mi> </mml:math> </inlineequation> th
row
2014-03-28 19:06:55 +00:00
is placed in location
2009-03-08 00:46:58 +00:00
<inlineequation > <mml:math >
2014-03-28 19:06:55 +00:00
<!-- eqn: (j) width + i: -->
2009-03-08 00:46:58 +00:00
<mml:mrow >
<mml:mfenced open= "(" close= ")" >
<mml:mi mathvariant= "italic" > j</mml:mi>
</mml:mfenced>
<mml:mo > ⁢ </mml:mo>
<mml:mi mathvariant= "italic" > width</mml:mi>
<mml:mo > +</mml:mo>
<mml:mi mathvariant= "italic" > i</mml:mi>
</mml:mrow>
</mml:math> </inlineequation> .
<constant > GL_RGB</constant> and <constant > GL_BGR</constant> return three values,
2014-03-28 19:06:55 +00:00
<constant > GL_RGBA</constant> and <constant > GL_BGRA</constant> return four values,
and <constant > GL_LUMINANCE_ALPHA</constant> returns two values for each pixel,
2009-03-08 00:46:58 +00:00
with all values corresponding to a single pixel occupying contiguous space
in <parameter > data</parameter> .
Storage parameters set by <citerefentry > <refentrytitle > glPixelStore</refentrytitle> </citerefentry> ,
such as <constant > GL_PACK_LSB_FIRST</constant> and <constant > GL_PACK_SWAP_BYTES</constant> ,
affect the way that data is written into memory.
See <citerefentry > <refentrytitle > glPixelStore</refentrytitle> </citerefentry> for a description.
</para>
</refsect1>
<refsect1 id= "notes" > <title > Notes</title>
<para >
Values for pixels that lie outside the window
connected to the current GL context are undefined.
</para>
<para >
If an error is generated,
no change is made to the contents of <parameter > data</parameter> .
</para>
</refsect1>
<refsect1 id= "errors" > <title > Errors</title>
<para >
<constant > GL_INVALID_ENUM</constant> is generated if <parameter > format</parameter> or <parameter > type</parameter> is not an
accepted value.
</para>
2014-03-28 19:06:55 +00:00
<para >
<constant > GL_INVALID_ENUM</constant> is generated if <parameter > type</parameter> is <constant > GL_BITMAP</constant> and <parameter > format</parameter> is
not <constant > GL_COLOR_INDEX</constant> or <constant > GL_STENCIL_INDEX</constant> .
</para>
2009-03-08 00:46:58 +00:00
<para >
<constant > GL_INVALID_VALUE</constant> is generated if either <parameter > width</parameter> or <parameter > height</parameter> is negative.
</para>
2014-03-28 19:06:55 +00:00
<para >
<constant > GL_INVALID_OPERATION</constant> is generated if <parameter > format</parameter> is <constant > GL_COLOR_INDEX</constant>
and the color buffers store RGBA color components.
</para>
2009-03-08 00:46:58 +00:00
<para >
<constant > GL_INVALID_OPERATION</constant> is generated if <parameter > format</parameter> is <constant > GL_STENCIL_INDEX</constant>
and there is no stencil buffer.
</para>
<para >
<constant > GL_INVALID_OPERATION</constant> is generated if <parameter > format</parameter> is <constant > GL_DEPTH_COMPONENT</constant>
and there is no depth buffer.
</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>
2014-03-28 19:06:55 +00:00
<para >
The formats <constant > GL_BGR</constant> , and <constant > GL_BGRA</constant> and types
<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 available only if the GL version
is 1.2 or greater.
</para>
2009-03-08 00:46:58 +00:00
<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
2014-03-28 19:06:55 +00:00
<constant > GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
2009-03-08 00:46:58 +00:00
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
2014-03-28 19:06:55 +00:00
<constant > GL_PIXEL_PACK_BUFFER</constant> target and <parameter > data</parameter> is not evenly divisible
2009-03-08 00:46:58 +00:00
into the number of bytes needed to store in memory a datum indicated by <parameter > type</parameter> .
</para>
<para >
2014-03-28 19:06:55 +00:00
<constant > GL_INVALID_OPERATION</constant> is generated if <function > glReadPixels</function>
is executed between the execution of <citerefentry > <refentrytitle > glBegin</refentrytitle> </citerefentry>
and the corresponding execution of <citerefentry > <refentrytitle > glEnd</refentrytitle> </citerefentry> .
2009-03-08 00:46:58 +00:00
</para>
</refsect1>
<refsect1 id= "associatedgets" > <title > Associated Gets</title>
2014-03-28 19:06:55 +00:00
<para >
<citerefentry > <refentrytitle > glGet</refentrytitle> </citerefentry> with argument <constant > GL_INDEX_MODE</constant>
</para>
2009-03-08 00:46:58 +00:00
<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 >
2014-03-28 19:06:55 +00:00
<citerefentry > <refentrytitle > glCopyPixels</refentrytitle> </citerefentry> ,
<citerefentry > <refentrytitle > glDrawPixels</refentrytitle> </citerefentry> ,
<citerefentry > <refentrytitle > glPixelMap</refentrytitle> </citerefentry> ,
2009-03-08 00:46:58 +00:00
<citerefentry > <refentrytitle > glPixelStore</refentrytitle> </citerefentry> ,
2014-03-28 19:06:55 +00:00
<citerefentry > <refentrytitle > glPixelTransfer</refentrytitle> </citerefentry> ,
2009-03-08 00:46:58 +00:00
<citerefentry > <refentrytitle > glReadBuffer</refentrytitle> </citerefentry>
</para>
</refsect1>
<refsect1 id= "Copyright" > <title > Copyright</title>
<para >
2014-03-28 19:06:55 +00:00
Copyright <trademark class= "copyright" > </trademark> 1991-2006
Silicon Graphics, Inc. This document is licensed under the SGI
Free Software B License. For details, see
2009-03-08 00:46:58 +00:00
<ulink url= "http://oss.sgi.com/projects/FreeB/" > http://oss.sgi.com/projects/FreeB/</ulink> .
</para>
</refsect1>
</refentry>
