glReadPixels 函数

glReadPixels 函数从 framebuffer 读取像素块。

语法

void WINAPI glReadPixels(
   GLint   x,
   GLint   y,
   GLsizei width,
   GLsizei height,
   GLenum  format,
   GLenum  type,
   GLvoid  *pixels
);

parameters

x

从帧缓冲区读取的第一个像素的窗口 x 坐标。 与 y 坐标一起,指定矩形像素块左下角的位置。

y

从帧缓冲区中读取的第一个像素的窗口 y 坐标。 与 x 坐标一起,指定矩形像素块左下角的位置。

width

像素矩形的宽度。

height

像素矩形的高度。 值“1”的宽度高度参数对应于单个像素。

format

像素数据的格式。 接受以下符号值:

含义
GL_COLOR_INDEX
glReadBuffer 选择的颜色缓冲区读取颜色索引。 每个索引将转换为固定点、向左或向右移动,具体取决于GL_INDEX_SHIFT的值和符号,并添加到GL_INDEX_OFFSET。 如果GL_MAP_COLOR GL_TRUE,索引将替换为表GL_PIXEL_MAP_I_TO_I中的映射。
GL_STENCIL_INDEX
模具值是从模具缓冲区读取的。 每个索引将转换为固定点、向左或向右移动,具体取决于GL_INDEX_SHIFT的值和符号,并添加到GL_INDEX_OFFSET。 如果GL_MAP_STENCIL GL_TRUE,索引将替换为表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,则表GL_PIXEL_MAP_c_TO_c中的每个颜色分量 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 none c

像素

返回像素数据。

返回值

此函数不返回值。

错误代码

glGetError 函数可以检索以下错误代码。

名称 含义
GL_INVALID_ENUM
格式类型 不是接受的值。
GL_INVALID_VALUE
宽度高度为负数。
GL_INVALID_OPERATION
格式 GL_COLOR_INDEX,并且颜色缓冲区存储 RGBA 或 BGRA 颜色组件。
GL_INVALID_OPERATION
格式 GL_STENCIL_INDEX,没有模具缓冲区。
GL_INVALID_OPERATION
格式 GL_DEPTH_COMPONENT,没有深度缓冲区。
GL_INVALID_OPERATION
在对 glBegin 的调用和 对 glEnd 的相应调用之间调用了该函数。

注解

glReadPixels 函数从帧缓冲区返回像素数据,从左下角位于位置 (x,y) ,从位置像素开始的客户端内存中返回像素数据。 多个参数控制在将像素数据放入客户端内存之前进行处理。 这些参数使用三个命令进行设置: glPixelStoreglPixelTransferglPixelMap。 本主题介绍对大多数 glReadPixels 的影响,但不是这三个命令指定的所有参数。

glReadPixels 函数从左下角 (x + i、y + j) 0 = i <宽度和 0 = j <高度的每个像素返回值。 此像素据说是 jth 行中的第个像素。 像素按行顺序从最低到最高行返回,每行从左到右。

上述移动、缩放、偏差和查找因素均由 glPixelTransfer 指定。 查阅表格内容由 glPixelMap 指定。

最后一步包括将索引或组件转换为按 类型指定的正确格式。 如果 格式 GL_COLOR_INDEX或GL_STENCIL_INDEX且 类型 未GL_FLOAT,则会使用下表中给定的掩码值屏蔽每个索引。 如果 类型 GL_FLOAT,则将每个整数索引转换为单精度浮点格式。

如果 格式 为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,则每个组件乘以上表中所示的乘数。 如果类型是GL_FLOAT,则每个组件按 (传递,或者转换为客户端的单精度浮点格式(如果它不同于 OpenGL) 使用的浮点格式)。

返回值放置在内存中,如下所示。 如果格式为GL_COLOR_INDEX、GL_STENCIL_INDEX、GL_DEPTH_COMPONENT、GL_RED、GL_GREEN、GL_BLUE、GL_ALPHA或GL_LUMINANCE,则返回单个值,并将 jth 行中第一个像素的数据放置在 j (j ) widthi + 的位置。 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