GLGETACTIVEUNIFORMSI(3G)

📦
version 1.1 · 7 versions
, in centos-stream 9

💅 glGetActiveUniformsiv(3G) 💅

okay so bestie, welcome to glGetActiveUniformsiv — yes that's a mouthful, no I will not be pronouncing it out loud — and it lives in the [FIXME: manual] manual, section 3G. iconic. let's get into it 🫶

✨ NAME ✨

glGetActiveUniformsiv — returns information about several active uniform variables for the specified program object. that's the whole vibe. it's giving "i have questions and i need answers about my uniforms" 💅

🌸 C SPECIFICATION 🌸

like, literally this is the function signature, copy it exactly, do not touch it, she is perfect:

void glGetActiveUniformsiv(GLuint program, GLsizei uniformCount,
                           const GLuint *uniformIndices, GLenum pname,
                           GLint *params);

🎀 PARAMETERS 🎀

okay so now we meet the cast of characters. five of them. all important. no skips 💖

  • program — specifies the program object to be queried. like, which program are we snooping on. that's the one 🕵️‍♀️
  • uniformCount — specifies both the number of elements in the array of indices uniformIndices and the number of parameters written to params upon successful return. so she's doing double duty, highkey a multi-hyphenate 💅 one number, two jobs, we love a main character ✨
  • uniformIndices — specifies the address of an array of uniformCount integers containing the indices of uniforms within program whose parameter pname should be queried. so it's the lil guest list of which uniforms we're asking about 📋
  • pname — specifies the property of each uniform in uniformIndices that should be written into the corresponding element of params. like, what do you wanna know about them. the property in question 👑🦋
  • params — specifies the address of an array of uniformCount integers which are to receive the value of pname for each uniform in uniformIndices. this is the answer sheet, the receipts, where the tea gets written down 🍓

🌈 DESCRIPTION 🌈

so here's the whole situation, bestie:

glGetActiveUniformsiv queries the value of the parameter named pname for each of the uniforms within program whose indices are specified in the array of uniformCount unsigned integers uniformIndices.

upon success, the value of the parameter for each uniform is written into the corresponding entry in the array whose address is given in params. one in, one out. matching entries. slay ✨

🚨 and listen — if an error is generated, nothing is written into params. like, nothing. zero. not a single entry. so don't go reading your params array all hopeful after an error, because she is untouched 😭💀

Okay so when pname is GL_UNIFORM_TYPE, you get back an array telling you the type of each uniform — one entry per element of your uniformIndices array, in the same order. It's giving very "match the answer sheet to the question sheet" energy ✨

And these are literally all the possible values it can hand back, paired with the shader type they mean:

  • GL_FLOAT — float
  • GL_FLOAT_VEC2 — vec2
  • GL_FLOAT_VEC3 — vec3
  • GL_FLOAT_VEC4 — vec4
  • GL_DOUBLE — double
  • GL_DOUBLE_VEC2 — dvec2
  • GL_DOUBLE_VEC3 — dvec3
  • GL_DOUBLE_VEC4 — dvec4
  • GL_INT — int
  • GL_INT_VEC2 — ivec2
  • GL_INT_VEC3 — ivec3
  • GL_INT_VEC4 — ivec4
  • GL_UNSIGNED_INT — unsigned int
  • GL_UNSIGNED_INT_VEC2 — uvec2
  • GL_UNSIGNED_INT_VEC3 — uvec3
  • GL_UNSIGNED_INT_VEC4 — uvec4
  • GL_BOOL — bool
  • GL_BOOL_VEC2 — bvec2
  • GL_BOOL_VEC3 — bvec3
  • GL_BOOL_VEC4 — bvec4
  • GL_FLOAT_MAT2 — mat2
  • GL_FLOAT_MAT3 — mat3
  • GL_FLOAT_MAT4 — mat4
  • GL_FLOAT_MAT2x3 — mat2x3
  • GL_FLOAT_MAT2x4 — mat2x4
  • GL_FLOAT_MAT3x2 — mat3x2
  • GL_FLOAT_MAT3x4 — mat3x4
  • GL_FLOAT_MAT4x2 — mat4x2
  • GL_FLOAT_MAT4x3 — mat4x3
  • GL_DOUBLE_MAT2 — dmat2
  • GL_DOUBLE_MAT3 — dmat3
  • GL_DOUBLE_MAT4 — dmat4
  • GL_DOUBLE_MAT2x3 — dmat2x3
  • GL_DOUBLE_MAT2x4 — dmat2x4
  • GL_DOUBLE_MAT3x2 — dmat3x2
  • GL_DOUBLE_MAT3x4 — dmat3x4
  • GL_DOUBLE_MAT4x2 — dmat4x2

...still going through the type match-ups, bestie, we're in the back half now, no stopping 👑 (each one's the GL_* enum on the left and the exact GLSL type name string it hands back on the right — character for character, no cap):

  • GL_DOUBLE_MAT4x3 → dmat4x3
  • GL_SAMPLER_1D → sampler1D
  • GL_SAMPLER_2D → sampler2D
  • GL_SAMPLER_3D → sampler3D
  • GL_SAMPLER_CUBE → samplerCube
  • GL_SAMPLER_1D_SHADOW → sampler1DShadow
  • GL_SAMPLER_2D_SHADOW → sampler2DShadow
  • GL_SAMPLER_1D_ARRAY → sampler1DArray
  • GL_SAMPLER_2D_ARRAY → sampler2DArray
  • GL_SAMPLER_1D_ARRAY_SHADOW → sampler1DArrayShadow
  • GL_SAMPLER_2D_ARRAY_SHADOW → sampler2DArrayShadow
  • GL_SAMPLER_2D_MULTISAMPLE → sampler2DMS
  • GL_SAMPLER_2D_MULTISAMPLE_ARRAY → sampler2DMSArray
  • GL_SAMPLER_CUBE_SHADOW → samplerCubeShadow
  • GL_SAMPLER_BUFFER → samplerBuffer
  • GL_SAMPLER_2D_RECT → sampler2DRect
  • GL_SAMPLER_2D_RECT_SHADOW → sampler2DRectShadow
  • GL_INT_SAMPLER_1D → isampler1D
  • GL_INT_SAMPLER_2D → isampler2D
  • GL_INT_SAMPLER_3D → isampler3D
  • GL_INT_SAMPLER_CUBE → isamplerCube
  • GL_INT_SAMPLER_1D_ARRAY → isampler1DArray
  • GL_INT_SAMPLER_2D_ARRAY → isampler2DArray
  • GL_INT_SAMPLER_2D_MULTISAMPLE → isampler2DMS
  • GL_INT_SAMPLER_2D_MULTISAMPLE_ARRAY → isampler2DMSArray
  • GL_INT_SAMPLER_BUFFER → isamplerBuffer
  • GL_INT_SAMPLER_2D_RECT → isampler2DRect
  • GL_UNSIGNED_INT_SAMPLER_1D → usampler1D
  • GL_UNSIGNED_INT_SAMPLER_2D → usampler2D
  • GL_UNSIGNED_INT_SAMPLER_3D → usampler3D
  • GL_UNSIGNED_INT_SAMPLER_CUBE → usamplerCube
  • GL_UNSIGNED_INT_SAMPLER_1D_ARRAY → usampler2DArray
  • GL_UNSIGNED_INT_SAMPLER_2D_ARRAY → usampler2DArray
  • GL_UNSIGNED_INT_SAMPLER_2D_MULTISAMPLE → usampler2DMS
  • GL_UNSIGNED_INT_SAMPLER_2D_MULTISAMPLE_ARRAY → usampler2DMSArray
  • GL_UNSIGNED_INT_SAMPLER_BUFFER → usamplerBuffer
  • GL_UNSIGNED_INT_SAMPLER_2D_RECT → usampler2DRect
🫶 real talk, bestie: those last two usampler lines — GL_UNSIGNED_INT_SAMPLER_1D_ARRAY → usampler2DArray and GL_UNSIGNED_INT_SAMPLER_2D_ARRAY → usampler2DArray — that's literally what the page says, so I'm passing it straight to you exactly like that. Copy it verbatim, don't go "fixing" it on me. 💅

okay so now — GL_UNIFORM_SIZE 🎀

If pname is GL_UNIFORM_SIZE, then what comes back is an array identifying the size of the uniforms specified by the corresponding array of uniformIndices. That array is returned, periodt.

And the sizes it returns? They're in units of the type returned by a query of GL_UNIFORM_TYPE — so like, whatever type GL_UNIFORM_TYPE just told you that uniform was, that's the unit of measurement for its size ✨.

For active uniforms that are arrays, the size is the number of active elements in the array 🦋. For all other uniforms — everything that isn't one of those array situations — the size is one. One. That's it. That's the number. 🙂‍↕️

So like, here's the tea on each pname value you can pass, bestie 💖 — this is the part where it actually tells you what comes back:

  • If pname is GL_UNIFORM_NAME_LENGTH, then you get back an array that tells you the length — including the terminating null character — of the uniform name strings specified by the corresponding array of uniformIndices. ✨
  • If pname is GL_UNIFORM_BLOCK_INDEX, then you get an array identifying the uniform block index of each of the uniforms specified by the corresponding array of uniformIndices. And heads up: the uniform block index of a uniform that's chillin' in the default uniform block is -1. 🫶
  • If pname is GL_UNIFORM_OFFSET, then you get an array of uniform buffer offsets. For uniforms in a named uniform block, the returned value is its offset, in basic machine units, relative to the beginning of the uniform block in the buffer object data store. For atomic counter uniforms, the returned value is its offset relative to the beginning of its active atomic counter buffer. For all other uniforms, -1 is returned. 💀
  • If pname is GL_UNIFORM_ARRAY_STRIDE, then you get an array identifying the stride between elements of each of the uniforms specified by the corresponding array of uniformIndices. For uniforms in named uniform blocks and for uniforms declared as atomic counters, the stride is the difference, in basic machine units, of consecutive elements in an array — or zero for uniforms not declared as an array. For all other uniforms, a stride of -1 is returned. 👑
  • If pname is GL_UNIFORM_MATRIX_STRIDE, then you get an array identifying the stride between columns of a column-major matrix or rows of a row-major matrix, in basic machine units, of each of the uniforms specified by the corresponding array of uniformIndices. The matrix stride of a uniform associated with the default uniform block is -1. Note that this info only makes sense for uniforms that are matrices — for uniforms that aren't matrices but are declared in a named uniform block, a matrix stride of zero is returned. no cap 🧚
  • If pname is GL_UNIFORM_IS_ROW_MAJOR, then you get an array identifying whether each of the uniforms specified by the corresponding array of uniformIndices is a row-major matrix or not. A value of one means row-major matrix, and a value of zero means column-major matrix, a matrix in the default uniform block, or a non-matrix. literally the vibe check for matrices 🌈
  • If pname is GL_UNIFORM_ATOMIC_COUNTER_BUFFER_INDEX, then you get an array identifying the active atomic counter buffer index of each of the uniforms specified by the corresponding array of uniformIndices. For uniforms other than atomic counters, the returned buffer index is -1. These returned indices may be passed to glGetActiveAtomicCounterBufferiv() to query the properties of the associated buffer — and not necessarily the binding point specified in the uniform declaration. iykyk 😭

🌸 NOTES 🌸

Ok so the double types — GL_DOUBLE, GL_DOUBLE_VEC2, GL_DOUBLE_VEC3, GL_DOUBLE_VEC4, GL_DOUBLE_MAT2, GL_DOUBLE_MAT3, GL_DOUBLE_MAT4, GL_DOUBLE_MAT2x3, GL_DOUBLE_MAT2x4, GL_DOUBLE_MAT3x2, GL_DOUBLE_MAT3x4, GL_DOUBLE_MAT4x2, and GL_DOUBLE_MAT4x3 — are only available if the GL version is 4.1 or higher. gatekept fr 💅

And GL_UNIFORM_ATOMIC_COUNTER_BUFFER_INDEX is only accepted by pname if the GL version is 4.2 or higher. ⭐

💀 ERRORS 💀

  • GL_INVALID_VALUE is generated if program is not a value generated by OpenGL.
  • GL_INVALID_OPERATION is generated if program is not a program object.
  • GL_INVALID_VALUE is generated if uniformCount is greater than or equal to the value of GL_ACTIVE_UNIFORMS for program.
  • GL_INVALID_ENUM is generated if pname is not an accepted token.
bestie if you're seeing these, something's not slaying. double-check your program and your pname before you spiral 🙈

🦋 ASSOCIATED GETS 🦋

  • glGet() with argument GL_MAX_VERTEX_UNIFORM_COMPONENTS, GL_MAX_TESS_CONTROL_UNIFORM_COMPONENTS, GL_MAX_TESS_EVALUATION_UNIFORM_COMPONENTS, GL_MAX_GEOMETRY_UNIFORM_COMPONENTS, GL_MAX_FRAGMENT_UNIFORM_COMPONENTS, or GL_MAX_COMBINED_UNIFORM_COMPONENTS.
  • glGetProgram() with argument GL_ACTIVE_UNIFORMS or GL_ACTIVE_UNIFORM_MAX_LENGTH.
  • glIsProgram()

👑 VERSION SUPPORT 👑

Ok the original had a whole table situation, but here's the same tea in list form, because we're cute like that 💖

glGetActiveUniformsiv across the OpenGL versions:

  • 2.0 — not supported
  • 2.1 — not supported
  • 3.0 — not supported
  • 3.1 — supported ✔
  • 3.2 — supported ✔
  • 3.3 — supported ✔
  • 4.0 — supported ✔
  • 4.1 — supported ✔
  • 4.2 — supported ✔
  • 4.3 — supported ✔
  • 4.4 — supported ✔
  • 4.5 — supported ✔

so it's giving 3.1 and up only, periodt 🌸

🎀 SEE ALSO 🎀

glGetUniform(), glGetActiveUniform(), glGetUniformLocation(), glLinkProgram(), glUniform(), glUseProgram()

Copyright © 2011-2014 Khronos Group. This material may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. http://opencontent.org/openpub/.

Copyright © 2011-2014 Khronos Group

ok that's the whole page, you made it to the end bestie, iconic behavior ✨🫶 This lil beauty comes from [FIXME: source], dated 08/09/2021, and it lives under the name GLGETACTIVEUNIFORMSI(3G) — go forth and query those uniforms, mwah 💅💖

📦 where this page comes from