GLUSEPROGRAM(3G)

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

✨ GLUSEPROGRAM(3G) — bestie's guide to slapping a shader program into your rendering state ✨

Okay so real talk, this is from the 3G manual section and honestly it's the glow-up function you've been waiting for. No cap.

🌸 NAME 🌸

glUseProgram — installs a program object as part of current rendering state

Like literally, it's giving "make this program the main character of your GPU's whole vibe." 💅

🎀 C SPECIFICATION 🎀

void glUseProgram(GLuint program);

🦋 PARAMETERS 🦋

  • program — Specifies the handle of the program object whose executables are to be used as part of current rendering state.

That's it. One parameter. One handle. One slay. ✨

💖 DESCRIPTION 💖

Okay so glUseProgram installs the program object specified by program as part of current rendering state. Fr fr, that's the whole assignment. One or more executables are created in a program object by:

  • successfully attaching shader objects to it with glAttachShader()
  • successfully compiling the shader objects with glCompileShader()
  • and successfully linking the program object with glLinkProgram()

Like the whole pipeline, bestie. You can't skip steps. 💀

A program object will contain an executable that will run on the vertex processor if it contains one or more shader objects of type GL_VERTEX_SHADER that have been successfully compiled and linked.

A program object will contain an executable that will run on the geometry processor if it contains one or more shader objects of type GL_GEOMETRY_SHADER that have been successfully compiled and linked.

Similarly, a program object will contain an executable that will run on the fragment processor if it contains one or more shader objects of type GL_FRAGMENT_SHADER that have been successfully compiled and linked.

It's giving "each processor gets its own little executable bestie." 🫶

While a program object is in use, applications are free to modify attached shader objects, compile attached shader objects, attach additional shader objects, and detach or delete shader objects. None of these operations will affect the executables that are part of the current state.

So like, you can absolutely be messy and edit your shaders while the program is live and the GPU won't even notice. Iconic behavior honestly. 😌

HOWEVER — and this is the important part — relinking the program object that is currently in use will install the program object as part of the current rendering state if the link operation was successful (see glLinkProgram()).

If the program object currently in use is relinked unsuccessfully, its link status will be set to GL_FALSE, but the executables and associated state will remain part of the current state until a subsequent call to glUseProgram removes it from use. After it is removed from use, it cannot be made part of current state until it has been successfully relinked.

Bestie, this is the "you can't sit with us until you get your link together" clause. No cap. 🙈

If program is zero, then the current rendering state refers to an invalid program object and the results of shader execution are undefined. However, this is not an error.

Not me passing 0 and thinking everything's fine. 💀 It's not an error, but it's undefined behavior, which is like, worse actually. Choose wisely.

If program does not contain shader objects of type GL_FRAGMENT_SHADER, an executable will be installed on the vertex, and possibly geometry processors, but the results of fragment shader execution will be undefined.

So like... no fragment shader? Your fragments are on their own. Live your truth I guess. 🌈

👑 NOTES 👑

Like buffer and texture objects, the name space for program objects may be shared across a set of contexts, as long as the server sides of the contexts share the same address space. If the name space is shared across contexts, any attached objects and the data associated with those attached objects are shared as well.

Shared name space = shared everything. It's giving "we're all in this together." 🎀

Applications are responsible for providing the synchronization across API calls when objects are accessed from different execution threads.

Lowkey this is the "you and your group chat need to actually coordinate" part. Threads = the group chat. Synchronization = not stepping on each other's messages. Periodt. 💅

🔥 ERRORS 🔥

  • GL_INVALID_VALUE is generated if program is neither 0 nor a value generated by OpenGL.
  • GL_INVALID_OPERATION is generated if program is not a program object.
  • GL_INVALID_OPERATION is generated if program could not be made part of current state.
  • GL_INVALID_OPERATION is generated if transform feedback mode is active.
The way GL_INVALID_OPERATION shows up FOUR TIMES. It's giving main character energy in the error section. 😭

💜 ASSOCIATED GETS 💜

Here's all the little query besties you can call to check on things:

  • glGet() with the argument GL_CURRENT_PROGRAM
  • glGetActiveAttrib() with a valid program object and the index of an active attribute variable
  • glGetActiveUniform() with a valid program object and the index of an active uniform variable
  • glGetAttachedShaders() with a valid program object
  • glGetAttribLocation() with a valid program object and the name of an attribute variable
  • glGetProgram() with a valid program object and the parameter to be queried
  • glGetProgramInfoLog() with a valid program object
  • glGetUniform() with a valid program object and the location of a uniform variable
  • glGetUniformLocation() with a valid program object and the name of a uniform variable
  • glIsProgram()

So many getters, so little time. You're welcome. 🫶

⭐ VERSION SUPPORT ⭐

Here's the vibe check table, bestie — glUseProgram has been serving since OpenGL 2.0 and never missed a single version:

┌──────────────┬───────────────────────────────────────────────────────────────────────┐
│              │                OpenGL Version                                         │
├──────────────┼─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┬─────┤
│ Function     │ 2.0 │ 2.1 │ 3.0 │ 3.1 │ 3.2 │ 3.3 │ 4.0 │ 4.1 │ 4.2 │ 4.3 │ 4.4 │ 4.5 │
│ /            │     │     │     │     │     │     │     │     │     │     │     │     │
│ Feature      │     │     │     │     │     │     │     │     │     │     │     │     │
│ Name         │     │     │     │     │     │     │     │     │     │     │     │     │
├──────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ glUseProgram │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │  ✔  │
└──────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

Every single version. A true legend. 🏆

🌈 SEE ALSO 🌈

  • glAttachShader()
  • glBindAttribLocation()
  • glCompileShader()
  • glCreateProgram()
  • glDeleteProgram()
  • glDetachShader()
  • glLinkProgram()
  • glUniform()
  • glValidateProgram()
  • glVertexAttrib()

The whole friend group, honestly. 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

Alright bestie, that's the whole page. This iconic piece of OpenGL documentation comes to you via [FIXME: source] and is dated 08/09/2021. Go forth and glUseProgram() responsibly. Slay. 💖✨🎀

📦 where this page comes from