glReadPixels

glReadPixels - читає блок пікселів з буфера кадру.

C-специфікація

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

Параметри

x,y вказує координати вікна першого пікселя, який буде зчитано з буферу кадру. Дане розміщення являється нижнім лівим кутком прямокутного блоку пікселів.

width, height вказує розміри піксельного блоку. Параметри width і height цього блоку відповідають одному пікселю.

format вказує формат піксельних даних. Приймаються наступні символічні дані: GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_BGR, GL_RGBA, GL_BGRA, GL_LUMINANCE і GL_LUMINANCE_ALPHA.

type вказує тип даних піксельних даних. Повинен містити одне з значень: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2 або GL_UNSIGNED_INT_2_10_10_10_REV.

data в даному параметрі розміщуються піксельні дані.

Опис

Функція glReadPixels повертає піксельні дані з буферу кадру, розпочинаючи з пікселів, лівий нижній кут яких розміщений у позиції (x,y), у пам'ять клієнта на яку вказує параметр data. Деякі параметри контролюють обробку піксельних даних перед її розміщенням у пам'ять клієнта. Ці параметри встановлюються трьома командами: glPixelStore, glPixelTransfer і glPixelMap. Даний документ в більшості описує функцію glReadPixels, і не усі параметри цих трьох команд вказуються тут.

Якщо ненульовий іменований буферний об'єкт прив'язаний до цілі GL_PIXEL_PACK_BUFFER (перегляньте glBindBuffer) поки опитується блок пікселів, параметр data розглядається у якості байтового зміщення у дані буферного об'єкту, ніж як вказівник на пам'ять клієнта.

Якщо підтримується розширення ARB_imaging, піксельні дані можуть бути оброблені додатковими операціями, включаючи пошук по таблиці кольорів, матричні перетворення кольору, згортання, гістограми, і обчислення мінімального і максимального піксельних значень.

Функція glReadPixels повертає значення з кожного пікселю з нижнім лівим кутом при x+i y+j для 0<=i<width і 0<=j<height. Дані пікселі називаються i-тий піксель у j-тому рядку. Пікселі повертаються у порядку рядків з найнижчого рядка до найвищого, зліва направо у кожному рядку.

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 і максимальні значення перетворюється на 1. Кожен компонент множиться на значення параметру GL_DEPTH_SCALE, додається до GL_DEPTH_BIAS, і в кінці обрізається до проміжку [0;1].
• GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_BGR, GL_RGBA, GL_BGRA, 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. Кожна таблиця повинна мати розмір 2n, але n може бути різним для різних таблиць. Перед тим як індекс використовується для пошуку значення у таблицях розміру 2n, він не повинен перевищувати 2n-1. Якщо колірні компоненти RGBA зберігаються у колірних буферах, вони зчитуються з колірного буферу обраного за допомогою glReadBuffer. Кожен колірний компонент перетворюється у таке дійсне значення, при якому нульова інтенсивність перетворюється у значення 0.0, а повна - у значення 1.0. Після цього кожен компонент перемножується на GL_c_SCALE і додається до GL_c_BIAS, де c являється RED, GREEN, BLUE або ALPHA. На кінець, якщо GL_MAP_COLOR містить значення GL_TRUE, кожен компонент обрізається у проміжок [0;1], і масштабується до розміру відповідної таблиці, і після цього змінюється на його відповідні значення перетворення у таблицях GL_PIXEL_MAP_c_TO_с, де c являється R, G, B або A. Після цього непотрібні дані відкидаються. Наприклад, GL_RED відкидає зелений, синій і компонент прозорості, коли GL_RGB відкидає тільки компонент прозороcті. GL_LUMINANCE обчислює значення одного компоненту у якості суми червоного, зеленого і синього компонентів, і GL_LIMINANCE_ALPHA виконує ту ж дію, утримуючи компонент прозорості у якості другого значення. Фінальні значення обрізаються до проміжку [0;1].

Тільки-що описані множники для зміщення, масштабування, додавання вказуються за допомогою виклику функції glPixelTransfer. Вміст таблиць перетворення вказується за допомогою виклику функції glPixelMap.

На кінець, індекси або компоненти перетворюються до відповідного формату, як вказано у параметрі type. Якщо параметр format містить значення GL_COLOR_INDEX або GL_STENCIL_INDEX і параметр type не являється GL_FLOAT, кожен індекс маскується за допомогою значення маски наданого у відповідній таблиці. Якщо параметр type містить значення GL_FLOAT, тоді кожен цілочисельний індекс перетворюється на дійсне число з одинарною точністю.

Якщо параметр format містить значення GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_BGR, GL_RGBA, GL_BGRA, GL_LUMINANCE, або GL_LUMINANCE_ALPHA і тип не являється GL_FLOAT, кожен компонент множиться на множник вказаний у даних таблицях. Якщо тип являється GL_FLOAT, тоді кожен компонент передається без змін (або перетворюється на дійсне число одинарної точності, якщо він відрізняється від аналогічного формату що використовується у OpenGL).

Повернені значення розміщуються у пам'яті наступним чином. Якщо параметр format містить значення GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTHC_OMPONENT, GL_READ, GL_GREEN, GL_BLUE, GL_ALPHA або GL_LUMINANCE - повертається одне значення і дані для i-того пікселя у j-тому рядку розміщуються у позиції j width+1. Значення GL_RGB i GL_BGR повертають три значення, значення GL_RGBA і GL_BGRA повертають чотири, і GL_LUMINANCE_ALPHA повертає два значення для кожного пікселя, усі дані відповідають одному пікселю займають безперервний простір у data. Параметри зберігання встановлені за допомогою виклику функції glPixelStore, на подобі GL_PACK_LSB_FIRST і GL_PACK_SWAP_BYTES, змінюють шлях, у який дані записуються у пам'ять. Перегляньте функцію glPixelStore для детального опису.

Нотатки

Значення для пікселів, які попадають за межі вікна підключеного до поточного контексту OpenGL невизначені.

Якщо генерується помилка, жодні зміни вносяться до вмісту data.

Формати GL_BGR і GL_BGRA і типи GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2 і GL_UNSIGNED_INT_2_10_10_10_REV доступні у системах OpenGL версії 1.2 або вище.

Помилки

GL_INVALID_ENUM генерується якщо параметр format або тип не містять допустимого значення

GL_INVALID_ENUM генерується якщо параметр type містить GL_BITMAP, а параметр format не містить значення GL_COLOR_INDEX або GL_STENCIL_INDEX.

GL_INVAID_VALUE генерується якщо width або height містять негативні значення.

GL_INVALID_OPERATION генеруються якщо параметр format являється GL_COLOR_INDEX і колірні буфери зберігаються колірні компоненти RGBA.

GL_INVALID_OPERATION генерується якщо параметр format містить GL_STENCOL_INDEX і не існує трафаретного буфера.

GL_INVALID_OPERATION генерується якщо параметр format містить GL_DEPTH_COMPONENT і не існує буфера глибини.

GL_INVALID_OPERATION генерується якщо параметр type містить одне з значень GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5 або GL_UNSIGNED_SHORT_5_6_5_REV і параметр format не містить GL_RGB.

GL_INVALID_OPERATION генерується якщо type містить одне з наступних значень GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, або GL_UNSIGNED_INT_2_10_10_10_REV і параметр format не містить значення GL_RGBA або GL_BGRA.

GL_INVALID_OPERATION генерується якщо не нульове ім'я об'єктного буфера прив'язане до цілі GL_PIXEL_PACK_BUFFER і збережені дані об'єктного буфера перетворюються в даний момент.

GL_INVALID_OPERATION генерується якщо ненульове ім'я буферного об'єкта прикріплений до цілі GL_PIXEL_PACK_BUFFER і дані будуть упаковані у буферний об'єкт, при якому запити на запис пам'яті будуть виходити за межі буферу.

GL_INVALID_OPERATION генерується якщо не нульове ім'я об'єкта буферу прив'язане до цілі GL_PIXEL_PACK_BUFFER і параметр data містить непарне значення, яке не можна цілочисельно поділити на потрібну кількість байтів, які потребують зберігання у пам'яті з типом вказаним за допомогою параметра type.

GL_INVALID_OPERATION генерується якщо glReadPixels викликається між відповідними викликами функцій glBegin і glEnd.

Пов'язані параметри

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

glGet з аргументом GL_PIXEL_PACK_BUFFER_BINDING

Перегляньте також

glCopyPixels, glDrawPixels, glPixelMap, glPixelStore, glPixelTransfer, glReadBuffer

Оригінал

https://www.khronos.org/registry/OpenGL-Refpages/gl2.1/xhtml/glReadPixels.xml