GLGETACTIVESUBROUTIN(3G)

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

💅 GLGETACTIVESUBROUTIN(3G) — bestie, let's learn this one

okay so this is a page from the 3G manual (yep, the OpenGL one), and it's all about glGetActiveSubroutineUniformName. Which, real talk, is a whole mouthful — but it's genuinely just "tell me the name of this shader subroutine uniform, please." Let's get into it 🎀

✨ NAME ✨

glGetActiveSubroutineUniformName — query the name of an active shader subroutine uniform.

Like. That's the whole vibe. You ask, it tells you the name. Iconic behaviour honestly 👑

🌸 C SPECIFICATION 🌸

void glGetActiveSubroutineUniformName(GLuint program, GLenum shadertype,
                                      GLuint index, GLsizei bufSize,
                                      GLsizei *length, GLchar *name);

Six arguments, no cap. Don't worry, we're going through every single one 💖

🦋 PARAMETERS 🦋

  • program — the name of the program that's holding the subroutine. Like, which program are we even talking about, bestie.
  • shadertype — the shader stage you're querying the subroutine parameter from. It must be one of GL_VERTEX_SHADER, GL_TESS_CONTROL_SHADER, GL_TESS_EVALUATION_SHADER, GL_GEOMETRY_SHADER, or GL_FRAGMENT_SHADER. Those five. No substitutions, no "close enough" 🙈
  • index — the index of the shader subroutine uniform. Your little pointer to which one you want.
  • bufSize — the size of the buffer whose address you're handing over in name. Basically: how much room are you giving it to write into.
  • length — the address of a variable where it writes back the number of characters that got copied into name. It's the "how much did you actually use" receipt 🧾
  • name — the address of a buffer that receives the name of the specified shader subroutine uniform. This is where the actual string lands, bestie.

💜 DESCRIPTION 💜

glGetActiveSubroutineUniformName retrieves the name of an active shader subroutine uniform — literally what it says on the tin.

So: program contains the name of the program containing the uniform. shadertype specifies the stage for which the uniform location — given by index — is valid. And index must be between zero and the value of GL_ACTIVE_SUBROUTINE_UNIFORMS minus one for the shader stage. Off-by-one girlies, be careful, that's a real boundary 😭

The uniform name comes back as a null-terminated string in name. The actual number of characters written into name — excluding the null terminator — is returned in length. And if length is NULL, no length is returned at all. Nothing. Zero info. That's the deal 🫶

The maximum number of characters that may be written into name, including the null terminator, is specified by bufSize.

And if you're wondering how big to make your buffer? The length of the longest subroutine uniform name in program and shadertype is given by the value of GL_ACTIVE_SUBROUTINE_UNIFORM_MAX_LENGTH, which you can query with glGetProgramStage(). Chef's kiss, that's your sizing hookup ✨

🔥 ERRORS 🔥

  • GL_INVALID_ENUM is generated if shadertype or pname is not one of the accepted values. (yes, it says pname — that's what the page says, we don't ask questions 💀)
  • GL_INVALID_VALUE is generated if index is greater than or equal to the value of GL_ACTIVE_SUBROUTINE_UNIFORMS.
  • GL_INVALID_VALUE is generated if program is not the name of an existing program object.
bestie. if you're getting one of these, something you passed in was not it. go check your values before you come for the driver 🙈

🌈 ASSOCIATED GETS 🌈

  • glGetProgramStage() with argument GL_ACTIVE_SUBROUTINE_UNIFORMS

⭐ VERSION SUPPORT ⭐

The original gives you a big grid across OpenGL versions, so here's the tea in list form — the fmt is Function / Feature Name, and the function is glGetActiveSubroutineUniformName:

  • 2.0 — nope ✖
  • 2.1 — nope ✖
  • 3.0 — nope ✖
  • 3.1 — nope ✖
  • 3.2 — nope ✖
  • 3.3 — nope ✖
  • 4.0 — yes ✔
  • 4.1 — yes ✔
  • 4.2 — yes ✔
  • 4.3 — yes ✔
  • 4.4 — yes ✔
  • 4.5 — yes ✔

So like... it really shows up in 4.0 and everything after. Before that? not me being unavailable 💅

🎀 SEE ALSO 🎀

  • glGetSubroutineIndex()
  • glGetActiveSubroutineUniform()
  • glGetProgramStage()

go read those next, they're the friend group 🫶

Copyright © 2010-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 © 2010-2014 Khronos Group.

and that's the page, bestie 🌸 it came from [FIXME: source] and it's dated 08/09/2021 — so go forth and query those subroutine uniform names, you absolute main character 💖🦋

📦 where this page comes from