glGetActiveUniform - повертає інформацію про активні уніфіковані змінні для вказаного програмного об'єкта.
C-специфікація
void glGetActiveUniform (GLuint program,
GLuint index,
GLsizei bufSize,
GLsizei *length,
GLint *size,
GLenum *type,
GLchar *name) ;
Параметри
program вказує програмний об'єкт, який необхідно опитати.
index вказує індекс уніфікованої змінної, яку необхідно опитати.
bufSize вказує максимальну кількість символів, які можна записувати в символьний буфер, переданий вказівником name.
length повертає кількість символів, фактично записаних системою OpenGL у рядок, вказаний за допомогою name (за виключенням нульового символу) якщо передане значення відмінне від NULL.
size повертає розмір уніфікованої змінної.
type повертає тип даних уніфікованої змінної.
name повертає рядок символів з завершуючим нульовим символом, який містить ім'я уніфікованої змінної.
Опис
Функція glGetActiveUnifrom повертає інформацію про активну уніфіковану змінну у програмному об'єкті вказаному за допомогою параметра program. Кількість активних уніфікованих змінних можна отримати за допомогою виклику функції glGetProgram з аргументом GL_ACTIVE_UNIFORMS. Значення 0 для параметру index обирає першу активну уніфіковану змінну. Доступний проміжок значень для параметру index міститься від значення 0 до кількості активних уніфікованих змінних мінус 1.
Шейдери можуть використовувати вбудовані уніфіковані змінні, або визначені користувачем, або їх комбінацією. Вбудовані уніфіковані змінні мають префікс "gl_" і відносяться до існуючого стану OpenGL або значення успадковані від такого стану (тобто, gl_Fog, gl_ModelViewMatrix, тощо, для повного списку перегляньте специфікацію шейдерної мови OpenGL "OpenGL Shading Language specification"). Визначені користувачем уніфіковані змінні мають звичайні імена і отримати їхнє значення з програми можна за допомогою виклику функції glUniform. Уніфіковані змінні (вбудовані або визначені користувачем) вважаються активними, якщо визначено під час операції компонування, що її будуть опитувати під час виконання програми. Отже, програма program повинна попередньо обробленою командою glLinkProgram, але не обов'язково щоб вона була успішно скомпонованою.
Розмір буферу символів, необхідного для збереження найдовшої назви уніфікованої змінної в програмі program можна отримати за допомогою виклику функції glGetProgram з параметром GL_ACTIVE_UNIFORM_MAX_LENGTH. Дане значення повинне бути використаним для створення буферу з достатнім розміром для збереження імені уніфікованої змінної. Розмір даного буфера передається за допомогою параметра bufSize і вказівник на даний буфер символів передається у якості параметру name.
Функція glGetActiveUniform повертає ім'я уніфікованої змінної, зазначеної за допомогою параметру index, зберігаючи його у символьному буферу вказаному за допомогою name. Повернений рядок символів буде містити завершуючий нульовий символ. Фактична кількість символів записаних у цей буфер повертається у параметрі length, і вона не враховує завершуючий нульовий символ. Якщо довжина поверненого рядка не вимагається, можна передавати значення NULL в якості параметру length.
Аргумент type поверне вказівник на тип даних уніфікованої змінної. Можуть бути поверненими наступні символічні константи: GL_FLOAT, GL_FLOAT_VEC2, GL_FLOAT_VEC3, GL_FLOAT_VEC4, GL_INT, GL_INT_VEC2, GL_INT_VEC3, GL_INT_VEC4, GL_BOOL, GL_BOOL_VEC2, GL_BOOL_VEC3, GL_BOOL_VEC4, GL_FLOAT_MAT2, GL_FLOAT_MAT3, GL_FLOAT_MAT4, GL_FLOAT_MAT2x3, GL_FLOAT_MAT2x4, GL_FLOAT_MAT3x2, GL_FLOAT_MAT3x4, GL_FLOAT_MAT4x2, GL_FLOAT_MAT4x3, GL_SAMPLER_1D, GL_SAMPLER_2D, GL_SAMPLER_3D, GL_SAMPLER_CUBE, GL_SAMPLER_1D_SHADOW або GL_SAMPLER_2D_SHADOW.
Якщо один або декілька елементів масиву є активними, ім'я масиву повертається у параметрі name, тип повертається у type і параметр size повертає найвищий індекс елементів масиву плюс один, як визначено компілятором або/і компонувальником. Тільки одна активна уніфікована змінна буде показаною для уніфікованого масиву.
Уніфіковані змінні, які оголошені у якості структур або масивів структур не повертаються безпосередньо даною функцією. Замість цього, кожен з цих уніфікованих змінних будуть розбиті на їх фундаментальні компоненти з використанням оператора крапки "." і оператора індексації масиву "[]", які будуть валідними у якості аргументів до функції glGetUniformLocation. Кожен з цих розбитих уніфікованих змінних обраховується у якості однієї активної уніфікованої змінної з прикріпленим індексом. Коректне ім'я не може являтися структурою, масивом структур, або компонентом вектора чи матриці.
Розмір уніфікованої змінної буде повернено в параметрі size. Уніфіковані змінні відмінні від масивів мають розмір 1. Структури і масиви структур будуть розбиті, як описано раніше, так, що кожне повернене ім'я буде містити тип даних з попереднього списку. Якщо це розбиття спричиняє повернення масиву, повернений розмір буде таким як описаний для уніфікованих масивів; в іншому випадку, повернений розмір буде містити значення 1.
Список активних уніфікованих змінних може включати вбудовані уніфіковані змінні (назви яких починаються з зарезервованого префіксу "gl_") і/або визначені користувачем імена уніфікованих змінних.
Дана функція поверне максимальну кількість інформації, яку можуть вмістити усі буфери. Якщо немає жодної доступної інформації, параметр length буде встановлено у значення 0, і параметр name буде являти собою пустий рядок. Дана ситуація виникає, коли функція викликається після невдалої операції компонування. Якщо виникає помилка, значення параметрів length, size, type і name залишаються без змін.
Нотатки
Функція glGetActiveUniform доступна в системах OpenGL версій 2.0 і вище.
GL_FLOAT_MAT2x3, GL_FLOAT_MAT2x4, GL_FLOAT_MAT3x2, GL_FLOAT_MAT3x4, GL_FLOAT_MAT4x2 і GL_FLOAT_MAT4x3 будуть поверненими у якості типу у системах OpenGL версій 2.1 і вище.
Помилки
GL_INVALID_VALUE генерується якщо program не містить значення згенерованого системою OpenGL.
GL_INVALID_OPERATION генерується якщо значення параметра program не являється ідентифікатором програмного об'єкта.
GL_INVALID_VALUE генерується якщо значення параметру index являється більшим ніж або еквівалентним до кількості активних уніфікованих змінних у програмі program.
GL_INVALID_OPERATION генерується якщо glGetActiveUniform виконується між відповідними викликами glBegin і glEnd.
GL_INVALID_VALUE генерується якщо bufSize містить значення менше 0.
Пов'язані параметри
glGet з аргументом GL_MAX_VERTEX_UNIFORM_COMPONENTS або GL_MAX_FRAGMENT_UNIFORM_COMPONENTS.
glGetProgram з аргументом GL_ACTIVE_UNIFORMS або GL_ACTIVE_UNIFORM_MAX_LENGTH.
Перегляньте також
glGetUniform, glGetUniformLocation, glLinkProgram, glUniform, glUseProgram
Оригінал
https://www.khronos.org/registry/OpenGL-Refpages/gl2.1/xhtml/glGetActiveUniform.xml