1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xml:lang="en-US" lang="en-US" xmlns="http://www.w3.org/1999/xhtml">
3  <head>
4    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5    <meta http-equiv="Content-Style-Type" content="text/css" />
6    <link rel="stylesheet" href="../css/manpage.css" type="text/css" />
7<title>glReadPixels</title>
8  </head>
9  <body>
10<h1><CODE>glReadPixels</CODE> Function</h1>
11<h2>Syntax</h2>
12    <div class="section">
13      <pre class="definition">
14GL_APICALL void GL_APIENTRY glReadPixels(
15     GLint x,
16     GLint y,
17     GLsizei width,
18     GLsizei height,
19     GLenum format,
20     GLenum type,
21     void * pixels
22);
23</pre>
24    </div>
25<h2>Arguments</h2>
26    <div class="section">
27      <table class="arguments">
28        <thead>
29          <tr>
30            <td width="15" />
31<th>Name</th>
32<td>Description</td>
33          </tr>
34        </thead>
35        <tr>
36<td>in</td>
37<th>x</th>
38<td>X coordinate of the lower-left corner of the rectangular region to read from the render buffer</td>
39        </tr>
40        <tr>
41<td>in</td>
42<th>y</th>
43<td>Y coordinate of the lower-left corner of the rectangular region to read from the render buffer</td>
44        </tr>
45        <tr>
46<td>in</td>
47<th>width</th>
48<td>Width of the rectangular region to read</td>
49        </tr>
50        <tr>
51<td>in</td>
52<th>height</th>
53<td>Height of the rectangular region to read</td>
54        </tr>
55        <tr>
56<td>in</td>
57<th>format</th>
58<td>Format of stored pixel data</td>
59        </tr>
60        <tr>
61<td>in</td>
62<th>type</th>
63<td>Type of stored pixel data</td>
64        </tr>
65        <tr>
66<td>out</td>
67<th>pixels</th>
68<td>Array storing the pixel data</td>
69        </tr> </table>
70    </div>
71<h2>Return Values</h2>
72<div class="section">There is no return value. </div>
73<h2>Description</h2>
74    <div class="section">
75<p>Reads pixel data from a rectangular region in the current render buffer.</p><P>
76Set <SPAN class="argument">x</SPAN> to the x coordinate of the lower-left corner of the rectangular region to read from the render buffer. Set <SPAN class="argument">y</SPAN> to the y coordinate of the lower-left corner of the rectangular region to read from the render buffer.
77            </P><P>
78Set <SPAN class="argument">width</SPAN> equal to the width of the rectangular region to read. Set <SPAN class="argument">height</SPAN> equal to the height of the rectangular region to read.
79            </P><P>
80Use <SPAN class="argument">format</SPAN> and <SPAN class="argument">type</SPAN> to configure the format of the data to read. The following combinations can be used.
81</P><TABLE><THEAD><TR><TD>format</TD><TD>type</TD></TR></THEAD><TR><TD><CODE>GL_RGBA</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE>, <CODE>GL_UNSIGNED_SHORT_4_4_4_4</CODE>, <CODE>GL_UNSIGNED_SHORT_5_5_5_1</CODE></TD></TR><TR><TD><CODE>GL_RGB</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE>, <CODE>GL_UNSIGNED_SHORT_5_6_5</CODE></TD></TR><TR><TD><CODE>GL_BGRA</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE>, <CODE>GL_UNSIGNED_SHORT_4_4_4_4</CODE>, <CODE>GL_UNSIGNED_SHORT_5_5_5_1</CODE></TD></TR><TR><TD><CODE>GL_LUMINANCE_ALPHA</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD></TR><TR><TD><CODE>GL_LUMINANCE</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD></TR><TR><TD><CODE>GL_ALPHA</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD></TR><TR><TD><CODE>GL_DEPTH_COMPONENT</CODE></TD><TD><CODE>GL_UNSIGNED_INT</CODE>, <CODE>GL_UNSIGNED_INT24_DMP</CODE>, <CODE>GL_UNSIGNED_SHORT</CODE>, <CODE>GL_UNSIGNED_BYTE</CODE></TD></TR><TR><TD><CODE>GL_STENCIL_INDEX</CODE></TD><TD><CODE>GL_UNSIGNED_BYTE</CODE></TD></TR><TR><TD><CODE>GL_DEPTH24_STENCIL8_EXT</CODE></TD><TD><CODE>GL_UNSIGNED_INT</CODE></TD></TR></TABLE><!-- source                 formatにはGL_RGBA、GL_RGB、GL_BGRA、GL_LUMINANCE_ALPHA、GL_LUMINANCE、GL_ALPHAが指定できます。 formatがGL_RGBAの場合、typeにGL_UNSIGNED_BYTE、GL_UNSIGNED_SHORT_4_4_4_4、GL_UNSIGNED_SHORT_5_5_5_1が指定できます。 formatがGL_RGBの場合、typeにGL_UNSIGNED_BYTE、GL_UNSIGNED_SHORT_5_6_5が指定できます。 formatがGL_BGRAの場合、typeにGL_UNSIGNED_BYTE、GL_UNSIGNED_SHORT_4_4_4_4、GL_UNSIGNED_SHORT_5_5_5_1が指定できます。 formatがGL_LUMINANCE_ALPHA、GL_LUMINANCE、GL_ALPHAの場合、typeにGL_UNSIGNED_BYTEが指定できます。             --><P>
82The pixel data is read into <SPAN class="argument">pixels</SPAN>.
83            </P><P>
84Use <code>glRenderBlockModeDMP</code> to set the block mode. Make sure the same block mode is configured when rendering the color buffer and when using this function to read the color buffer. You cannot get the content of the color buffer correctly when the block modes differ.
85            </P><P>
86Each pixel's depth value is read from the depth buffer in order starting with the least-significant bits. When <SPAN class="argument">type</SPAN> is <CODE>GL_UNSIGNED_INT24_DMP</CODE>, for example, three bytes are obtained for a single pixel in order from the least-significant to the most-significant eight bits. If the depth value is actually rendered with a different bit width than the <SPAN class="argument">type</SPAN> setting, the obtained value is converted for use with the <SPAN class="argument">type</SPAN> setting.
87            </P><P>
88When reading the content of a stencil buffer, the format of the current depth buffer must be <CODE>GL_DEPTH24_STENCIL8_EXT</CODE>. When <B>format</B> is <CODE>GL_STENCIL_INDEX</CODE>, each pixel stencil value is read into each byte of <B>pixels</B> (where 1 byte corresponds to 1 pixel). When the <SPAN class="argument">format</SPAN> argument is <CODE>GL_DEPTH24_STENCIL8_EXT</CODE> each pixel is read into 4 bytes as follows: the least-significant 8 bits of the depth value, the middle 8 bits, the most-significant 8 bits of the depth value, the 8-bit stencil value.
89            </P><P>
90The following errors occur in this function.
91<TABLE><TR><TH><CODE>GL_INVALID_OPERATION</CODE></TH><TD>The <SPAN class="argument">x</SPAN> or <SPAN class="argument">y</SPAN> argument is negative; the sum of <SPAN class="argument">x</SPAN> and <SPAN class="argument">width</SPAN> is greater than the width (in pixels) of the color buffer; or the sum of <SPAN class="argument">y</SPAN> and <SPAN class="argument">height</SPAN> is greater than the height (in pixels) of the color buffer.</TD></TR><TR><TH><CODE>GL_INVALID_FRAMEBUFFER_OPERATION</CODE></TH><TD>The framebuffer was configured incorrectly.</TD></TR><TR><TH><CODE>GL_INVALID_VALUE</CODE></TH><TD>The <SPAN class="argument">width</SPAN> or <SPAN class="argument">height</SPAN> argument is negative.</TD></TR><TR><TH><CODE>GL_INVALID_ENUM</CODE></TH><TD>Invalid combination of <SPAN class="argument">format</SPAN> and <SPAN class="argument">type</SPAN>.</TD></TR><TR><TH><CODE>GL_OUT_OF_MEMORY</CODE></TH><TD>Failed to allocate temporary memory that is used internally.</TD></TR></TABLE><!-- source                      x、yが負の値の場合、xとwidthの和がカラーバッファの横幅のピクセル数を超える場合、 yとheightの和がカラーバッファの縦幅のピクセル数を超える場合エラーGL_INVALID_OPERATIONを生成します。 フレームバッファの設定が正しく行われていない場合エラーGL_INVALID_FRAMEBUFFER_OPERATIONを生成します。 width、heightが負の場合エラーGL_INVALID_VALUEを生成します。 formatとtypeの組み合わせが不正な場合エラーGL_INVALID_OPERATIONを生成します。 内部で使用する一時メモリの確保に失敗した場合エラーGL_OUT_OF_MEMORYを生成します。                 --></P></div>
92<h2>Revision History</h2>
93    <div class="section">
94      <dl class="history">
95        <dt>2010/11/01</dt>
96<dd>Corrected the text.<br />
97        </dd>
98        <dt>2010/08/12</dt>
99<dd>Added description of how stencil buffer is read. Revised description of error occurring for invalid combinations for the <SPAN class="argument">format</SPAN> and <SPAN class="argument">type</SPAN> arguments.<br />
100        </dd>
101        <dt>2010/06/09</dt>
102<dd>Added information on support for reading from the depth buffer.<br />
103        </dd>
104        <dt>2010/01/07</dt>
105<dd>Initial version.<br />
106        </dd>
107      </dl>
108    </div>
109  <hr><p>CONFIDENTIAL</p></body>
110</html>