glReadPixels

From OpenGL Reference
Jump to navigation Jump to search

Read a block of pixels from the frame buffer.

C Specification[edit]

void glReadPixels( GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, void * data );
void glReadnPixels( GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, GLsizei bufSize, void * data );


Parameters[edit]

x -y - 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.
width -height - Specify the dimensions of the pixel rectangle. width and height of one correspond to a single pixel.
format - Specifies the format of the pixel data. The following symbolic values are accepted: GL_STENCIL_INDEX , GL_DEPTH_COMPONENT , GL_DEPTH_STENCIL , GL_RED , GL_GREEN , GL_BLUE , GL_RGB , GL_BGR , GL_RGBA , and GL_BGRA .
type - Specifies the data type of the pixel data. Must be one of GL_UNSIGNED_BYTE , GL_BYTE , GL_UNSIGNED_SHORT , GL_SHORT , GL_UNSIGNED_INT , GL_INT , GL_HALF_FLOAT , GL_FLOAT , GL_UNSIGNED_BYTE_3_3_2 , GL_UNSIGNED_BYTE_2_3_3_REV , GL_UNSIGNED_SHORT_5_6_5 , GL_UNSIGNED_SHORT_5_6_5_REV , GL_UNSIGNED_SHORT_4_4_4_4 , GL_UNSIGNED_SHORT_4_4_4_4_REV , GL_UNSIGNED_SHORT_5_5_5_1 , GL_UNSIGNED_SHORT_1_5_5_5_REV , GL_UNSIGNED_INT_8_8_8_8 , GL_UNSIGNED_INT_8_8_8_8_REV , GL_UNSIGNED_INT_10_10_10_2 , GL_UNSIGNED_INT_2_10_10_10_REV , GL_UNSIGNED_INT_24_8 , GL_UNSIGNED_INT_10F_11F_11F_REV , GL_UNSIGNED_INT_5_9_9_9_REV , or GL_FLOAT_32_UNSIGNED_INT_24_8_REV .
bufSize - Specifies the size of the buffer data for glReadnPixels function.
data - Returns the pixel data.


Description[edit]

 glReadPixels and glReadnPixels return pixel data from the frame buffer, starting with the pixel whose lower left corner is at location ( x , y ), into client memory starting at location data . Several parameters control the processing of the pixel data before it is placed into client memory. These parameters are set with glPixelStore . This reference page describes the effects on glReadPixels and glReadnPixels of most, but not all of the parameters specified by these three commands.

If a non-zero named buffer object is bound to the GL_PIXEL_PACK_BUFFER target (see glBindBuffer ) while a block of pixels is requested, data is treated as a byte offset into the buffer object's data store rather than a pointer to client memory.

 glReadPixels and glReadnPixels return values from each pixel with lower left corner at [math]()[/math] for [math]0\lt =i\lt width[/math] and [math]0\lt =j\lt height[/math] . This pixel is said to be the [math][/math] th pixel in the [math][/math] th row. Pixels are returned in row order from the lowest to the highest row, left to right in each row.

 format specifies the format for the returned pixel values; accepted values are:


GL_STENCIL_INDEX  - Stencil values are read from the stencil buffer.
GL_DEPTH_COMPONENT  - 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. Each component is clamped to the range [math][0,1][/math] .
GL_DEPTH_STENCIL  - Values are taken from both the depth and stencil buffers. The type parameter must be GL_UNSIGNED_INT_24_8 or GL_FLOAT_32_UNSIGNED_INT_24_8_REV .
GL_RED ,GL_GREEN ,GL_BLUE ,GL_RGB ,GL_BGR ,GL_RGBA ,GL_BGRA  - Color values are taken from the color buffer.

Finally, the indices or components are converted to the proper format, as specified by type . If format is GL_STENCIL_INDEX and type is not GL_FLOAT , each index is masked with the mask value given in the following table. If type is GL_FLOAT , then each integer index is converted to single-precision floating-point format.

If format is GL_RED , GL_GREEN , GL_BLUE , GL_RGB , GL_BGR , GL_RGBA , or GL_BGRA and type is not GL_FLOAT , each component is multiplied by the multiplier shown in the following table. If type is GL_FLOAT , 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).



Index Mask Component Conversion
GL_UNSIGNED_BYTE   [math]28-1[/math]   [math]()⁢c[/math] 
GL_BYTE   [math]27-1[/math]   [math][/math] 
GL_UNSIGNED_SHORT   [math]216-1[/math]   [math]()⁢c[/math] 
GL_SHORT   [math]215-1[/math]   [math][/math] 
GL_UNSIGNED_INT   [math]232-1[/math]   [math]()⁢c[/math] 
GL_INT   [math]231-1[/math]   [math][/math] 
GL_HALF_FLOAT  none  [math][/math] 
GL_FLOAT  none  [math][/math] 
GL_UNSIGNED_BYTE_3_3_2   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_BYTE_2_3_3_REV   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_SHORT_5_6_5   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_SHORT_5_6_5_REV   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_SHORT_4_4_4_4   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_SHORT_4_4_4_4_REV   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_SHORT_5_5_5_1   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_SHORT_1_5_5_5_REV   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_INT_8_8_8_8   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_INT_8_8_8_8_REV   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_INT_10_10_10_2   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_INT_2_10_10_10_REV   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_INT_24_8   [math]2N-1[/math]   [math]()⁢c[/math] 
GL_UNSIGNED_INT_10F_11F_11F_REV 
Special
GL_UNSIGNED_INT_5_9_9_9_REV 
Special
GL_FLOAT_32_UNSIGNED_INT_24_8_REV  none  [math][/math] (Depth Only)

Return values are placed in memory as follows. If format is GL_STENCIL_INDEX , GL_DEPTH_COMPONENT , GL_RED , GL_GREEN , or GL_BLUE , a single value is returned and the data for the [math][/math] th pixel in the [math][/math] th row is placed in location [math]()⁢width+i[/math] . GL_RGB and GL_BGR return three values, GL_RGBA and GL_BGRA return four values for each pixel, with all values corresponding to a single pixel occupying contiguous space in data . Storage parameters set by glPixelStore , such as GL_PACK_LSB_FIRST and GL_PACK_SWAP_BYTES , affect the way that data is written into memory. See glPixelStore for a description.

 glReadnPixels function will only handle the call if bufSize is at least of the size required to store the requested data. Otherwise, it will generate a GL_INVALID_OPERATION error.


Notes[edit]

Values for pixels that lie outside the window connected to the current GL context are undefined.

If an error is generated, no change is made to the contents of data .


Errors[edit]

 GL_INVALID_ENUM is generated if format or type 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_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 format is GL_DEPTH_STENCIL and there is no depth buffer or if there is no stencil buffer.

 GL_INVALID_ENUM is generated if format is GL_DEPTH_STENCIL and type is not GL_UNSIGNED_INT_24_8 or GL_FLOAT_32_UNSIGNED_INT_24_8_REV .

 GL_INVALID_OPERATION is generated if type is one of GL_UNSIGNED_BYTE_3_3_2 , GL_UNSIGNED_BYTE_2_3_3_REV , GL_UNSIGNED_SHORT_5_6_5 , or GL_UNSIGNED_SHORT_5_6_5_REV and format is not GL_RGB .

 GL_INVALID_OPERATION is generated if type is one of GL_UNSIGNED_SHORT_4_4_4_4 , GL_UNSIGNED_SHORT_4_4_4_4_REV , GL_UNSIGNED_SHORT_5_5_5_1 , GL_UNSIGNED_SHORT_1_5_5_5_REV , GL_UNSIGNED_INT_8_8_8_8 , GL_UNSIGNED_INT_8_8_8_8_REV , GL_UNSIGNED_INT_10_10_10_2 , or GL_UNSIGNED_INT_2_10_10_10_REV and format is neither GL_RGBA nor GL_BGRA .

 GL_INVALID_OPERATION is generated if a non-zero buffer object name is bound to the GL_PIXEL_PACK_BUFFER target and the buffer object's data store is currently mapped.

 GL_INVALID_OPERATION is generated if a non-zero buffer object name is bound to the GL_PIXEL_PACK_BUFFER target and the data would be packed to the buffer object such that the memory writes required would exceed the data store size.

 GL_INVALID_OPERATION is generated if a non-zero buffer object name is bound to the GL_PIXEL_PACK_BUFFER target and data is not evenly divisible into the number of bytes needed to store in memory a datum indicated by type .

 GL_INVALID_OPERATION is generated if GL_READ_FRAMEBUFFER_BINDING is non-zero, the read framebuffer is complete, and the value of GL_SAMPLE_BUFFERS for the read framebuffer is greater than zero.

 GL_INVALID_OPERATION is generated by glReadnPixels if the buffer size required to store the requested data is greater than bufSize .


Associated Gets[edit]

 glGet with argument GL_PIXEL_PACK_BUFFER_BINDING 


Version Support[edit]

 glReadPixels  2.0+
 glReadnPixels  4.5+

See Also[edit]

 glPixelStore , glReadBuffer 


Copyright[edit]

Copyright© 1991-2006 Silicon Graphics, Inc. Copyright© 2010-2014 Khronos Group. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.