glReadPixels 函数从 framebuffer 读取像素块。
语法
void WINAPI glReadPixels(
GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
GLvoid *pixels
);
参数
x
从帧缓冲区读取的第一个像素的窗口 x 坐标。 与 y 坐标一起指定矩形像素块左下角的位置。
y
从帧缓冲区读取的第一个像素的窗口 y 坐标。 与 x 坐标一起指定矩形像素块左下角的位置。
width
像素矩形的宽度。
height
像素矩形的高度。 值“1”的宽度和高度参数对应于单个像素。
format
像素数据的格式。 接受以下符号值：
值
含义
GL_COLOR_INDEX
从 glReadBuffer 选择的颜色缓冲区读取颜色索引。 每个索引转换为固定点、向左或向右移动，具体取决于GL_INDEX_SHIFT的值和符号，并添加到GL_INDEX_OFFSET。 如果GL_TRUE GL_MAP_COLOR，则索引将替换为表GL_PIXEL_MAP_I_TO_I中的映射。
GL_STENCIL_INDEX
从模具缓冲区读取模具值。 每个索引转换为固定点、向左或向右移动，具体取决于GL_INDEX_SHIFT的值和符号，并添加到GL_INDEX_OFFSET。 如果GL_TRUE GL_MAP_STENCIL，则索引将替换为表GL_PIXEL_MAP_S_TO_S中的映射。
GL_DEPTH_COMPONENT
深度值是从深度缓冲区读取的。 每个分量都转换为浮点，以便最小深度值映射到 0.0，最大值映射到 1.0。 然后，每个分量乘以GL_DEPTH_SCALE，添加到GL_DEPTH_BIAS，最后固定到范围 [0，1]。
GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA、GL_RGB、GL_RGBA、GL_BGR_EXT、GL_BGRA_EXT、GL_LUMINANCE、GL_LUMINANCE_ALPHA
处理因颜色缓冲区是存储颜色索引还是 RGBA 颜色分量而异。 如果存储了颜色索引，则会从 glReadBuffer 选择的颜色缓冲区中读取这些索引。 每个索引转换为固定点、向左或向右移动，具体取决于GL_INDEX_SHIFT的值和符号，并添加到GL_INDEX_OFFSET。 然后，索引将替换为通过索引GL_PIXEL_MAP_I_TO_R、GL_PIXEL_MAP_I_TO_G、GL_PIXEL_MAP_I_TO_B和GL_PIXEL_MAP_I_TO_A表获得的红色、绿色、蓝色和 alpha 值。 如果 RGBA 颜色分量存储在颜色缓冲区中，则会从 glReadBuffer 选择的颜色缓冲区中读取它们。 每个颜色分量都转换为浮点，使零强度映射到 0.0，全强度映射到 1.0。 然后，每个分量乘以GL_c_SCALE并添加到GL_c_BIAS，其中 c 为GL_RED、GL_GREEN、GL_BLUE和GL_ALPHA。 每个组件被固定到 [0，1] 范围内。 最后，如果GL_MAP_COLOR GL_TRUE，则每个颜色分量 c 都将替换为表GL_PIXEL_MAP_c_TO_c中的映射，其中 c 再次GL_RED、GL_GREEN、GL_BLUE和GL_ALPHA。 在执行查找之前，将每个组件缩放到其相应表的大小。 最后，将丢弃不需要的数据。 例如，GL_RED放弃绿色、蓝色和 alpha 分量，而GL_RGB只放弃 alpha 分量。 GL_LUMINANCE将单个分量值计算为红色、绿色和蓝色分量的总和，GL_LUMINANCE_ALPHA执行相同的操作，同时将 alpha 保留为第二个值。
type
像素数据的数据类型。 必须是以下值之一。
类型
索引掩码
组件转换
GL_UNSIGNED_BYTE
281
(281) c
GL_BYTE
271
[ (271) c-1]/2
GL_BITMAP
1
1
GL_UNSIGNED_SHORT
2 61
(2 61) c
GL_SHORT
2 51
[ (2 51) c1]/2
GL_UNSIGNED_INT_
2 1
(2 1) c
GL_INT
2 1
[ (2 1) c1]/2
GL_FLOAT
无
c
像素
返回像素数据。
返回值
此函数不返回值。
错误代码
glGetError 函数可以检索以下错误代码。
名称
含义
GL_INVALID_ENUM
format 或 type 不是接受的值。
GL_INVALID_VALUE
宽度或高度为负值。
GL_INVALID_OPERATION
format 已GL_COLOR_INDEX，并且颜色缓冲区存储了 RGBA 或 BGRA 颜色分量。
GL_INVALID_OPERATION
format 已GL_STENCIL_INDEX，并且没有模具缓冲区。
GL_INVALID_OPERATION
格式 已GL_DEPTH_COMPONENT，并且没有深度缓冲区。
GL_INVALID_OPERATION
函数是在 对 glBegin 的调用和对 glEnd 的相应调用之间调用的。
备注
glReadPixels 函数从 framebuffer 返回像素数据，从左下角位于 x、y) 位置 (的像素开始，返回到客户端内存中，从位置像素开始。 在将像素数据放入客户端内存之前，有多个参数控制像素数据的处理。 这些参数使用三个命令设置： glPixelStore、 glPixelTransfer 和 glPixelMap。 本主题介绍对大多数 glReadPixels 的影响，但不是这三个命令指定的所有参数。
glReadPixels 函数返回每个像素的值，其左下角位于 (x + i， y + j) 0 = i <宽度，0 = j <高度。 此像素据说是第 j行中的第 i个像素。 像素按行顺序从最低到最高行返回，每行从左到右。
上述移位、缩放、偏差和查找因素均由 glPixelTransfer 指定。 查阅表格内容由 glPixelMap 指定。
最后一步涉及将索引或组件转换为由 类型指定的正确格式。 如果 format 为GL_COLOR_INDEX或GL_STENCIL_INDEX且 类型 未GL_FLOAT，则使用下表中给定的掩码值屏蔽每个索引。 如果 type 为GL_FLOAT，则每个整数索引将转换为单精度浮点格式。
如果 format 为GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA、GL_RGB、GL_RGBA、GL_BGR_EXT、GL_BGRA_EXT、GL_LUMINANCE或 GL_LUMINANCE_ALPHA且类型 未GL_FLOAT，则每个组件乘以上表所示的乘数。 如果 type 为GL_FLOAT，则每个组件将按 (传递，或者如果它不同于 OpenGL) 所用的单精度浮点格式，则将其转换为客户端的单精度浮点格式。
返回值放置在内存中，如下所示。 如果 format 为 GL_COLOR_INDEX、GL_STENCIL_INDEX、GL_DEPTH_COMPONENT、GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA 或 GL_LUMINANCE，则返回单个值，并将第 j行中第 i个像素的数据放置在宽度i (j ) 。 + GL_RGB和GL_BGR_EXT返回三个值，GL_RGBA和GL_BGRA_EXT返回四个值，GL_LUMINANCE_ALPHA为每个像素返回两个值，与单个像素对应的所有值占用以 像素为单位的连续空间。
glPixelStore 设置的存储参数（如GL_PACK_SWAP_BYTES和GL_PACK_LSB_FIRST）会影响将数据写入内存的方式。 有关说明，请参阅 glPixelStore 。
未定义位于连接到当前 OpenGL 上下文的窗口外部的像素值。
如果生成错误，则不会更改 像素的内容。
以下函数检索 与 glReadPixels 相关的信息：
带参数GL_INDEX_MODE的 glGet
要求
要求
值
最低受支持的客户端
Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器
Windows 2000 Server [仅限桌面应用]
标头
Gl.h
库
Opengl32.lib
DLL
Opengl32.dll
另请参阅
glBegin
glCopyPixels
glDrawPixels
glEnd
glPixelMap
glPixelStore
glPixelTransfer
glReadBuffer