Função glReadPixels

A função glReadPixels lê um bloco de pixels do framebuffer.

Sintaxe

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

Parâmetros

x

A coordenada de janela x do primeiro pixel que é lido do framebuffer. Junto com a coordenada y , especifica o local do canto inferior esquerdo de um bloco retangular de pixels.

y

As coordenadas de janela y do primeiro pixel que é lido do framebuffer. Junto com a coordenada x , especifica o local do canto inferior esquerdo de um bloco retangular de pixels.

width

A largura do retângulo de pixel.

altura

A altura do retângulo de pixel. Os parâmetros de largura e altura do valor "1" correspondem a um único pixel.

format

O formato dos dados de pixel. Os seguintes valores simbólicos são aceitos:

Valor	Significado
GL_COLOR_INDEX	Os índices de cores são lidos no buffer de cores selecionado pelo glReadBuffer. Cada índice é convertido em ponto fixo, deslocado para a esquerda ou para a direita, dependendo do valor e do sinal de GL_INDEX_SHIFT e adicionado a GL_INDEX_OFFSET. Se GL_MAP_COLOR for GL_TRUE, os índices serão substituídos por seus mapeamentos na tabela GL_PIXEL_MAP_I_TO_I.
GL_STENCIL_INDEX	Os valores de estêncil são lidos do buffer de estêncil. Cada índice é convertido em ponto fixo, deslocado para a esquerda ou para a direita, dependendo do valor e do sinal de GL_INDEX_SHIFT e adicionado a GL_INDEX_OFFSET. Se GL_MAP_STENCIL for GL_TRUE, os índices serão substituídos por seus mapeamentos na tabela GL_PIXEL_MAP_S_TO_S.
GL_DEPTH_COMPONENT	Os valores de profundidade são lidos do buffer de profundidade. Cada componente é convertido em ponto flutuante de modo que o valor mínimo de profundidade seja mapeado para 0,0 e o valor máximo seja mapeado para 1,0. Cada componente é multiplicado por GL_DEPTH_SCALE, adicionado a GL_DEPTH_BIAS e, por fim, fixado ao intervalo [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	O processamento difere dependendo se os buffers de cores armazenam índices de cores ou componentes de cor RGBA. Se os índices de cores forem armazenados, eles serão lidos no buffer de cores selecionado pelo glReadBuffer. Cada índice é convertido em ponto fixo, deslocado para a esquerda ou para a direita, dependendo do valor e do sinal de GL_INDEX_SHIFT e adicionado a GL_INDEX_OFFSET. Em seguida, os índices são substituídos pelos valores vermelho, verde, azul e alfa obtidos pela indexação das tabelas GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B e GL_PIXEL_MAP_I_TO_A. Se os componentes de cor RGBA forem armazenados nos buffers de cores, eles serão lidos no buffer de cores selecionado pelo glReadBuffer. Cada componente de cor é convertido em ponto flutuante, de modo que a intensidade zero é mapeada para 0,0 e a intensidade total é mapeada para 1,0. Cada componente é multiplicado por GL_c_SCALE e adicionado a GL_c_BIAS, em que c é GL_RED, GL_GREEN, GL_BLUE e GL_ALPHA. Cada componente é fixado ao intervalo [0,1]. Por fim, se GL_MAP_COLOR for GL_TRUE, cada componente de cor c será substituído por seu mapeamento na tabela GL_PIXEL_MAP_c_TO_c, em que c novamente é GL_RED, GL_GREEN, GL_BLUE e GL_ALPHA. Cada componente é dimensionado para o tamanho de sua tabela correspondente antes que a pesquisa seja executada. Por fim, os dados desnecessários são descartados. Por exemplo, GL_RED descarta os componentes verde, azul e alfa, enquanto GL_RGB descarta apenas o componente alfa. GL_LUMINANCE calcula um único valor de componente como a soma dos componentes vermelho, verde e azul, e GL_LUMINANCE_ALPHA faz o mesmo, mantendo alfa como um segundo valor.

tipo

O tipo de dados dos dados de pixel. Deve ser um dos valores a seguir.

Type	Máscara de índice	Conversão de componente
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	nenhum	c

Pixels

Retorna os dados de pixel.

Retornar valor

Essa função não retorna um valor.

Códigos de erro

Os códigos de erro a seguir podem ser recuperados pela função glGetError .

Nome	Significado
GL_INVALID_ENUM	formato ou tipo não era um valor aceito.
GL_INVALID_VALUE	A largura ou a altura foram negativas.
GL_INVALID_OPERATION	O formato era GL_COLOR_INDEX e os buffers de cores armazenavam componentes de cor RGBA ou BGRA.
GL_INVALID_OPERATION	o formato era GL_STENCIL_INDEX e não havia nenhum buffer de estêncil.
GL_INVALID_OPERATION	O formato era GL_DEPTH_COMPONENT e não havia nenhum buffer de profundidade.
GL_INVALID_OPERATION	A função foi chamada entre uma chamada para glBegin e a chamada correspondente para glEnd.

Comentários

A função glReadPixels retorna dados de pixel do framebuffer, começando com o pixel cujo canto inferior esquerdo está no local (x, y), na memória do cliente começando em pixels de localização. Vários parâmetros controlam o processamento dos dados de pixel antes de serem colocados na memória do cliente. Esses parâmetros são definidos com três comandos: glPixelStore, glPixelTransfer e glPixelMap. Este tópico descreve os efeitos em glReadPixels da maioria, mas não todos os parâmetros especificados por esses três comandos.

A função glReadPixels retorna valores de cada pixel com canto inferior esquerdo em (x + i, y + j) para 0 = i <width e 0 = j <height. Diz-se que esse pixel é o ith pixel na linha jth. Os pixels são retornados em ordem de linha da linha mais baixa para a linha mais alta, da esquerda para a direita em cada linha.

Os fatores shift, scale, bias e lookup descritos acima são todos especificados por glPixelTransfer. O conteúdo da tabela de pesquisa é especificado por glPixelMap.

A etapa final envolve a conversão de índices ou componentes para o formato adequado, conforme especificado por tipo. Se o formato for GL_COLOR_INDEX ou GL_STENCIL_INDEX e o tipo não for GL_FLOAT, cada índice será mascarado com o valor de máscara fornecido na tabela a seguir. Se o tipo for GL_FLOAT, cada índice inteiro será convertido em formato de ponto flutuante de precisão única.

Se o formato for GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR_EXT, GL_BGRA_EXT, GL_LUMINANCE ou GL_LUMINANCE_ALPHA e o tipo não for GL_FLOAT, cada componente será multiplicado pelo multiplicador mostrado na tabela anterior. Se o tipo for GL_FLOAT, cada componente será passado como está (ou convertido no formato de ponto flutuante de precisão única do cliente se for diferente do usado pelo OpenGL).

Os valores retornados são colocados na memória da seguinte maneira. Se o formato for GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA ou GL_LUMINANCE, um único valor será retornado e os dados do ith pixel na linha jserão colocados no local (j )width + i. GL_RGB e GL_BGR_EXT retornam três valores, GL_RGBA e GL_BGRA_EXT retornam quatro valores e GL_LUMINANCE_ALPHA retorna dois valores para cada pixel, com todos os valores correspondentes a um único pixel ocupando espaço contíguo em pixels. Os parâmetros de armazenamento definidos pelo glPixelStore, como GL_PACK_SWAP_BYTES e GL_PACK_LSB_FIRST, afetam a forma como os dados são gravados na memória. Consulte glPixelStore para obter uma descrição.

Os valores de pixels que estão fora da janela conectada ao contexto opengl atual são indefinidos.

Se um erro for gerado, nenhuma alteração será feita no conteúdo dos pixels.

A função a seguir recupera informações relacionadas ao glReadPixels:

glGet com GL_INDEX_MODE de argumento

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	Gl.h
Biblioteca	Opengl32.lib
DLL	Opengl32.dll

Confira também

glBegin

glCopyPixels

glDrawPixels

glEnd

glPixelMap

glPixelStore

glPixelTransfer

glReadBuffer