pixelsArray = gl.ReadPixels(x, y, width, height, format)
gl.ReadPixels()
returns pixel data from the frame buffer, starting with the pixel whose lower left corner is at location (x, y),
in a table. Several parameters control the processing of the pixel data before it is placed into the table. These parameters are
set with three commands: gl.PixelStore(), gl.PixelTransfer(), and gl.PixelMap().
This reference page describes the effects on gl.ReadPixels()
of most, but not all of the parameters specified by these three commands.
gl.ReadPixels()
returns values from each pixel with lower left corner at (x + i, y + j) for 0 <= i < width and 0 <= j < height. This
pixel is said to be the ith pixel in the jth row. Pixels are returned in row order from the lowest to the highest row, left to right in
each row.
gl.ReadPixels()
always uses type #GL_FLOAT
to read the pixels from the frame buffer. For fine-tuned control over the data type
of the pixel data, you can use gl.ReadPixelsRaw() instead. See gl.ReadPixelsRaw for details.
format
specifies the format for the returned pixel values; accepted values are:
#GL_COLOR_INDEX
#GL_INDEX_SHIFT
, and added to #GL_INDEX_OFFSET
. If #GL_MAP_COLOR
is #GL_TRUE
, indices
are replaced by their mappings in the table #GL_PIXEL_MAP_I_TO_I
.
#GL_STENCIL_INDEX
#GL_INDEX_SHIFT
, and added to #GL_INDEX_OFFSET
. If #GL_MAP_STENCIL
is #GL_TRUE
, indices are replaced by their
mappings in the table #GL_PIXEL_MAP_S_TO_S
.
#GL_DEPTH_COMPONENT
#GL_DEPTH_SCALE
, added to #GL_DEPTH_BIAS
, and finally
clamped to the range (0,1).
#GL_RED
#GL_INDEX_SHIFT
, and added to #GL_INDEX_OFFSET
. Indices are then replaced by the red, green,
blue, and alpha values obtained by indexing the tables #GL_PIXEL_MAP_I_TO_R
, #GL_PIXEL_MAP_I_TO_G
, #GL_PIXEL_MAP_I_TO_B
, and
#GL_PIXEL_MAP_I_TO_A
. Each table must be of size 2^n , but n may be different for different tables. Before an index is used to
look up a value in a table of size 2^n , it must be masked against 2^n - 1.
If RGBA color components are stored in the color buffers, they are read from the color buffer selected by gl.ReadBuffer(). 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 #GL_c_SCALE
and added to #GL_c_BIAS
, where c is RED, GREEN, BLUE, or ALPHA. Finally, if #GL_MAP_COLOR
is #GL_TRUE
, each
component is clamped to the range (0,1), scaled to the size of its corresponding table, and is then replaced by its mapping in the
table #GL_PIXEL_MAP_c_TO_c
, where c is R, G, B, or A.
Unneeded data is then discarded. For example, #GL_RED
discards the green, blue, and alpha components, while #GL_RGB
discards only
the alpha component. #GL_LUMINANCE
computes a single-component value as the sum of the red, green, and blue components, and #GL_LUMINANCE_ALPHA
does the same, while keeping alpha as a second value. The final values are clamped to the range (0,1).
#GL_GREEN
#GL_RED
.
#GL_BLUE
#GL_RED
.
#GL_ALPHA
#GL_RED
.
#GL_RGB
#GL_RED
.
#GL_RGBA
#GL_RED
.
#GL_LUMINANCE
#GL_RED
.
#GL_LUMINANCE_ALPHA
#GL_RED
.
The shift, scale, bias, and lookup factors just described are all specified by gl.PixelTransfer(). The lookup table contents themselves are specified by gl.PixelMap().
Return values are placed in the table as follows. If format
is #GL_COLOR_INDEX
, #GL_STENCIL_INDEX
, #GL_DEPTH_COMPONENT
, #GL_RED
, #GL_GREEN
, #GL_BLUE
, #GL_ALPHA
,
or #GL_LUMINANCE
, a single floating-point value is returned. #GL_RGB
returns three values, #GL_RGBA
returns four values, and #GL_LUMINANCE_ALPHA
returns two values
for each pixel, with all values corresponding to a single pixel occupying contiguous space in data. Storage parameters set by gl.PixelStore(),
such as #GL_PACK_LSB_FIRST
and #GL_PACK_SWAP_BYTES
, affect the way that data is written into memory. See gl.PixelStore for details.
Values for pixels that lie outside the window connected to the current GL context are undefined.
Please consult an OpenGL reference manual for more information.
#GL_INVALID_ENUM
is generated if format
is not an accepted value.
#GL_INVALID_VALUE
is generated if either width
or height
is negative.
#GL_INVALID_OPERATION
is generated if format
is #GL_COLOR_INDEX
and the color buffers store RGBA color components.
#GL_INVALID_OPERATION
is generated if format
is #GL_STENCIL_INDEX
and there is no stencil buffer.
#GL_INVALID_OPERATION
is generated if format
is #GL_DEPTH_COMPONENT
and there is no depth buffer.
#GL_INVALID_OPERATION
is generated if gl.ReadPixels()
is executed between the execution of gl.Begin() and the corresponding execution of gl.End().
#GL_INDEX_MODE