Функция glReadPixels

Статья
06/13/2023

Функция glReadPixels считывает блок пикселей из framebuffer.

Синтаксис

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

Параметры

x

Координата окна x первого пикселя, считываемого из framebuffer. Вместе с координатой y задает расположение левого нижнего угла прямоугольного блока пикселей.

y

Координаты окна Y первого пикселя, считываемого из framebuffer. Вместе с координатой 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. Если компоненты цвета 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 отменяет зеленый, синий и альфа-компоненты, а GL_RGB — только альфа-компонент. GL_LUMINANCE вычисляет значение одного компонента как сумму красного, зеленого и синего компонентов, и GL_LUMINANCE_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	формат или тип не является допустимым значением.
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 возвращает данные о пикселях из framebuffer, начиная с пикселя, нижний левый угол которого находится в расположении (x, y), в память клиента, начиная с пикселей расположения. Несколько параметров управляют обработкой пиксельных данных перед их размещением в памяти клиента. Эти параметры задаются с помощью трех команд: glPixelStore, glPixelTransfer и glPixelMap. В этом разделе описывается влияние на glReadPixels большинства, но не всех параметров, заданных этими тремя командами.

Функция glReadPixels возвращает значения из каждого пикселя с левым нижним углом в (x + i, y + j) для 0 = i <ширина и 0 = высота j<. Этот пиксель называется i-мпикселем в j-йстроке. Пиксели возвращаются в порядке строк от самой низкой к самой высокой, слева направо в каждой строке.

Описанные выше факторы сдвига, масштаба, смещения и подстановки определяются glPixelTransfer. Содержимое таблицы подстановки определяется с помощью glPixelMap.

Последний шаг включает преобразование индексов или компонентов в правильный формат в соответствии с типом . Если формат GL_COLOR_INDEX или GL_STENCIL_INDEX, а тип не GL_FLOAT, каждый индекс маскируется значением маски, указанным в следующей таблице. Если тип 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, каждый компонент умножается на множитель, показанный в предыдущей таблице. Если тип GL_FLOAT, каждый компонент передается как есть (или преобразуется в клиентский формат с плавающей запятой с одной точностью, если он отличается от формата, используемого OpenGL).

Возвращаемые значения помещаются в память следующим образом. Если формат имеет значение GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA или GL_LUMINANCE, возвращается одно значение, а данные для i-гопикселя в j-йстроке помещаются в расположение (j )width + i. 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:

glGet с аргументом GL_INDEX_MODE

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Заголовок	Gl.h
Библиотека	Opengl32.lib
DLL	Opengl32.dll

См. также раздел

glBegin
glCopyPixels
glDrawPixels
glEnd
glPixelMap
glPixelStore
glPixelTransfer
glReadBuffer