glReadPixels
NAME
glReadPixels - read a block of pixels from the frame buffer
C SPECIFICATION
void glReadPixels( GLint x, GLint y, GLsizei width,GLsizei height, GLenum format, GLenum type, GLvoid *pixels)
width, height
Specify the dimensions of the pixel rectangle. width and heightof one correspond to a single pixel.
format
Specifies the format of the pixel data. The following symbolic values areaccepted: GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.
type
Specifies the data type of the pixel data. Must be one of GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, or GL_FLOAT.
pixels
Returns the pixel data.
DESCRIPTION
glReadPixels returns pixeldata from the frame buffer, starting with the pixel whose lower left corner isat location ( x, y), into client memory starting at location pixels.Several parameters control the processing of the pixel data before it is placedinto client memory. These parameters are set with three commands: glPixelStore, glPixelTransfer,and glPixelMap. Thisreference page describes the effects on glReadPixels of most, but notall of the parameters specified by these three commands.
glReadPixels returns valuesfrom each pixel with lower left-hand 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 arereturned in row order from the lowest to the highest row, left to right in eachrow.
format specifies the format for thereturned pixel values. Accepted values for format are as follows:
GL_COLOR_INDEX
Color indices are read from the color buffer selected by glReadBuffer. Eachindex is converted to fixed point, shifted left or right depending on the valueand sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. If GL_MAP_COLORis GL_TRUE, indices are replaced by their mappings in the table GL_PIXEL_MAP_I_TO_I.
GL_STENCIL_INDEX
Stencil values are read from the stencil buffer. Each index is converted tofixed point, shifted left or right depending on the value and sign of 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
Depth values are read from the depth buffer. Each component is converted tofloating point such that the minimum depth value maps to 0.0 and the maximumvalue maps to 1.0. Each component is then multiplied by GL_DEPTH_SCALE,added to GL_DEPTH_BIAS, and finally clamped to the range [0,1].
GL_RED
GL_GREEN
GL_BLUE
GL_ALPHA
GL_RGB
GL_RGBA
GL_LUMINANCE
GL_LUMINANCE_ALPHA
Processing differs depending on whether color buffers store color indices orRGBA color components. If color indices are stored, they are read from thecolor buffer selected by glReadBuffer.Each index is converted to fixed point, shifted left or right depending on thevalue and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET.Indices are then replaced by the red, green, blue, and alpha values obtained byindexing the 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 tables.
If RGBA color components are stored in the color buffers, they are read fromthe color buffer selected by glReadBuffer.Each color component is converted to floating point such that zero intensitymaps to 0.0 and full intensity maps to 1.0. Each component is then multipliedby GL_c_SCALE and added to GL_c_BIAS, where c is GL_RED, GL_GREEN, GL_BLUE, and GL_ALPHA. Each component is clampedto the range [0,1]. Finally, if GL_MAP_COLOR is GL_TRUE, eachcolor component c is replaced by its mapping in the table GL_PIXEL_MAP_c_TO_c,where c again is GL_RED, GL_GREEN, GL_BLUE, and GL_ALPHA.Each component is scaled to the size its corresponding table before the lookupis performed.
Finally, unneeded data is discarded. For example, GL_RED discards thegreen, blue, and alpha components, while GL_RGB discards only the alphacomponent. GL_LUMINANCE computes a single component value as the sum ofthe red, green, and blue components, and GL_LUMINANCE_ALPHA does thesame, while keeping alpha as a second value.
The shift, scale, bias, and lookup factors described above are allspecified by glPixelTransfer.The lookup table contents themselves are specified by glPixelMap.
The final step involves converting the indices or components to the properformat, as specified by type. If format is GL_COLOR_INDEX or GL_STENCIL_INDEX and type is not GL_FLOAT, each index ismasked 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_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, or GL_LUMINANCE_ALPHAand type is not GL_FLOAT, each component is multiplied by themultiplier shown in the following table. If type is GL_FLOAT, then eachcomponent is passed as is (or converted to the client's single-precisionfloating-point format if it is different from the one used by the GL).
【中文版】
glReadPixels - 從幀快取里讀取一個像素塊
void glReadPixels(GLint x,GLint y,GLsizesi width,GLsizei height,
GLenum format,GLenum type,GLvoid *pixel);
函式參數(x, y)定義圖像區域左下角點的坐標，width和height分別是圖像的高度和寬度，*pixel是一個指針，指向存儲圖像數據的數組。參數format指出所讀象素數據元素的格式（索引值或R、G、B、A值，如下面表所示），而參數type指出每個元素的數據類型（也見下面表）。
寫入象素數據：
void glDrawPixels(GLsizesi width,GLsizei height,GLenum format,
GLenum type,GLvoid *pixel);
函式參數format和type與glReadPixels()有相同的意義，pixel指向的數組包含所要畫的象素數據。注意，調用這個函式前必須先設定當前光柵位置，若當前光柵位置無效，則給出該函式時不畫任何圖形，並且當前光柵位置仍然保持無效。
+++++++++++像素格式表++++++++++++++++++++++
GL_INDEX 單個顏色索引
GL_RGB 先是紅色分量，再是綠色分量，然後是藍色分量
GL_RED 單個紅色分量
GL_GREEN 單個綠色分量
GL_BLUE 單個藍色分量
GL_ALPHA 單個Alpha值
GL_LUMINANCE_ALPHA 先是亮度分量，然後是Alpha值
GL_STENCIL_INDEX 單個的模板索引
GL_DEPTH_COMPONENT 單個深度分量
++++++++++++++++++++++++++++++++++++++++++
+++++++++++++++++++ 數據類型+++++++++++++++++++
GL_UNSIGNED_BYTE 無符號的8位整數
GL_BYTE 8位整數
GL_BITMAP 無符號的8位整數數組中的單個數位
GL_UNSIGNED_SHORT 無符號的16位整數
GL_SHORT 16位整數
GL_UNSIGNED_INT 無符號的32位整數
GL_INT 32位整數
GL_FLOAT 單精度浮點數
+++++++++++++++++++++++++++++++++++++++
圖像的每個元素按上面表給出的數據類型存儲。若元素表示連續的值，如紅、綠、藍或亮度分量，每個值都按比例放縮使之適合於可用的位數。例如，紅色分量是0.0到1.0之 間的浮點值。若它需要放到無符號單位元組整數中，也僅有8位精度保存下來，其他無符號整數類型同理。對於有符號的數據類型還要少一位，例如顏色索引存到有符號的8位整數中，它的第一位被0xfe禁止掉了（即這個掩碼包含7個1）。若類型是GL_FLOAT，索引值簡單地轉化成單精度浮點值，例如索引17轉化成17.0，同理。
