GLGETUNIFORMLOCATION(3G)

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

💅 GLGETUNIFORMLOCATION(3G) — like, the whole glow-up

okay bestie, so this is the 3G manual page for glGetUniformLocation, and I promise it's gonna make sense. It's one little function that finds out where a uniform variable lives inside a program object. That's the whole vibe. Let's go. ✨

🌸 NAME 🌸

glGetUniformLocation — returns the location of a uniform variable. that's it, that's the tweet. 🫶

✨ C SPECIFICATION ✨

GLint glGetUniformLocation(GLuint program, const GLchar *name);

like, two arguments, one GLint back. iconic signature ngl.

🎀 PARAMETERS 🎀

  • program — the program object you're querying. this is the thing you're asking questions about, bestie.
  • name — points to a null terminated string holding the name of the uniform variable whose location you wanna know. yes, null terminated. yes, it matters. 💀

🦋 DESCRIPTION 🦋

So glGetUniformLocation returns an integer that represents the location of a specific uniform variable within a program object.

Now the rules, and please read them because they will trip you up:

  • name must be a null terminated string that contains no white space. none. zero. not a single space.
  • name must be an active uniform variable name in program that is not a structure, an array of structures, or a subcomponent of a vector or a matrix.

And it returns -1 — the sad number, the "no thoughts head empty" number — if any of these happen:

  • name does not correspond to an active uniform variable in program
  • name starts with the reserved prefix "gl_"
  • name is associated with an atomic counter or a named uniform block

Uniform variables that are structures or arrays of structures may be queried by calling glGetUniformLocation for each field within the structure. like, one field at a time, one call at a time. that's the move. 💅

The array element operator "[]" and the structure field operator "." may be used in name in order to select elements within an array or fields within a structure. Slay. But — and this is the catch — the result of using these operators is not allowed to be another structure, an array of structures, or a subcomponent of a vector or a matrix. so don't try it. 🙈

Except! If the last part of name indicates a uniform variable array, the location of the first element of an array can be retrieved by using the name of the array, or by using the name appended by "[0]". okay so both of those work. both. cute.

Now the timing of it all, because this is the part people get wrong:

The actual locations assigned to uniform variables are not known until the program object is linked successfully. So like, don't come asking before the link. Periodt.

After linking has occurred, the command glGetUniformLocation can be used to obtain the location of a uniform variable. This location value can then be passed to glUniform() to set the value of the uniform variable, or to glGetUniform() in order to query the current value of the uniform variable. 🎯

After a program object has been linked successfully, the index values for uniform variables remain fixed until the next link command occurs. so they're stable, but only until you relink. keep that in mind.

And one last thing: uniform variable locations and values can only be queried after a link if the link was successful. failed link = no locations for you. 😭

🔥 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_OPERATION is generated if program has not been successfully linked.
three ways to upset the driver. none of them are fun. 🌈

👑 ASSOCIATED GETS 👑

  • glGetActiveUniform() with arguments program and the index of an active uniform variable
  • glGetProgram() with arguments program and GL_ACTIVE_UNIFORMS or GL_ACTIVE_UNIFORM_MAX_LENGTH
  • glGetUniform() with arguments program and the name of a uniform variable
  • glIsProgram()

⭐ VERSION SUPPORT ⭐

the original ships this as a big grid, but here's the tea in list form — glGetUniformLocation is supported in every single one of these OpenGL versions, all checkmarks, no gaps:

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

the row in the original table is glGetUniformLocation, and the column header situation is "OpenGL Version" over "Function / Feature Name". that's the whole grid. ate. 💖

🌈 SEE ALSO 🌈

  • glLinkProgram()
  • glUniform()

iykyk 🦋

Copyright © 2003-2005 3Dlabs Inc. Ltd. 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 © 2003-2005 3Dlabs Inc. Ltd. Copyright © 2010-2014 Khronos Group

okay that's the whole page bestie, you're officially educated ✨ stay hydrated, link your programs, and remember: no white space in name, ever. mwah 🎀

sign-off szn: this one came from [FIXME: source] and it's dated 08/09/2021 — that's the version and date on the original footer, so now you know exactly when this lore dropped. 🍓
📦 where this page comes from