GLBINDVERTEXBUFFERS(3G)

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

💅 GLBINDVERTEXBUFFERS(3G) — or, how to attach a whole squad of buffers at once 🎀

okay so this is a page from the OpenGL manual — 3G section, bestie, the graphics girlies — and it's genuinely such a slay. it's about glBindVertexBuffers and glVertexArrayVertexBuffers, aka the two functions that let you attach multiple buffer objects to a vertex array object in one shot instead of doing it one at a time like some kind of 2.0-era peasant. no cap, this is efficiency main character energy. 💅

✨ NAME ✨

glBindVertexBuffers, glVertexArrayVertexBuffers — attach multiple buffer objects to a vertex array object 🦋

🌸 C SPECIFICATION 🌸

like, the actual signatures, verbatim, do not touch:

void glBindVertexBuffers(GLuint first, GLsizei count,
                         const GLuint *buffers, const GLintptr *offsets,
                         const GLsizei *strides);

void glVertexArrayVertexBuffers(GLuint vaobj, GLuint first,
                                GLsizei count, const GLuint *buffers,
                                const GLintptr *offsets,
                                const GLsizei *strides);

🎀 PARAMETERS 🎀

  • vaobj — the name of the vertex array object, but only for glVertexArrayVertexBuffers. it's giving "which VAO are we doing this to" vibes.
  • first — the first vertex buffer binding point that's gonna get a buffer object bound to it. the starting point, the opening act, the first of the friend group. ⭐
  • count — how many buffers we're binding. the squad size, basically.
  • buffers — address of an array of names of existing buffer objects. yes "existing", we'll get to that. 👀
  • offsets — address of an array of offsets to associate with the binding points.
  • buffers — address of an array of strides to associate with the binding points.
not me noticing the page lists buffers twice 🙈 the second one is literally the strides description, iykyk. i'm keeping it exactly as printed because the facts do not move, but yeah, that's the strides one bestie. 💀

💖 DESCRIPTION 💖

glBindVertexBuffers and glVertexArrayVertexBuffers bind storage from an array of existing buffer objects to a specified number of consecutive vertex buffer binding points units in a vertex array object. so like, one call, many bindings. ate and left no crumbs. 🔥

for glBindVertexBuffers, the vertex array object is the currently bound vertex array object. for glVertexArrayVertexBuffers, vaobj is the name of the vertex array object. that's the whole difference, periodt.

count existing buffer objects are bound to vertex buffer binding points numbered $first$ through $first + count - 1$. if buffers is not NULL, it specifies an array of count values, each of which must be zero or the name of an existing buffer object. offsets and strides specify arrays of count values indicating the offset of the first element and stride between elements in each buffer, respectively. 🧚

if buffers is NULL, each affected vertex buffer binding point from $first$ through $first + count - 1$ will be reset to have no bound buffer object. in that case, the offsets and strides associated with the binding points are set to default values, ignoring offsets and strides. like, fully ignoring them. they're not even invited to the group chat. 🙈

glBindVertexBuffers is equivalent (assuming no errors are generated) to:

for (i = 0; i < count; i++) {
    if (buffers == NULL) {
        glBindVertexBuffer(first + i, 0, 0, 16);
    } else {
        glBindVertexBuffer(first + i, buffers[i], offsets[i], strides[i]);
    }
}

except that buffers will not be created if they do not exist. that's the key little caveat, ok? do not come for me if you expected it to gen buffers for you. it won't. it refuses. 💀

glVertexArrayVertexBuffers is equivalent to the pseudocode above, but replacing glBindVertexBuffers(args) with glVertexArrayVertexBuffers(vaobj, args). same energy, one extra argument.

the values specified in buffers, offsets, and strides will be checked separately for each vertex buffer binding point. when a value for a specific vertex buffer binding point is invalid, the state for that binding point will be unchanged and an error will be generated. however, state for other vertex buffer binding points will still be changed if their corresponding values are valid. so it's like, the party keeps going even if one person flops. 🫶

🔥 ERRORS 🔥

like, here's where it can all go wrong. read these. seriously.

  • GL_INVALID_OPERATION is generated by glBindVertexBuffers if no vertex array object is bound. bestie. bind a VAO first. 😭
  • GL_INVALID_OPERATION is generated by glVertexArrayVertexBuffers if vaobj is not the name of the vertex array object.
  • GL_INVALID_OPERATION is generated if $first + count$ is greater than the value of GL_MAX_VERTEX_ATTRIB_BINDINGS. respect the limit or perish.
  • GL_INVALID_OPERATION is generated if any value in buffers is not zero or the name of an existing buffer object. "existing" is doing a lot of heavy lifting here, and it means it. 👑
  • GL_INVALID_VALUE is generated if any value in offsets or strides is negative, or if a value is stride is greater than the value of GL_MAX_VERTEX_ATTRIB_STRIDE. (yes, the original says "a value is stride" — that's the printed wording, leave it be. 🍓)

🌈 VERSION SUPPORT 🌈

vibe check, which OpenGL versions actually support these:

  • glBindVertexBuffers — OpenGL 2.0 -, 2.1 -, 3.0 -, 3.1 -, 3.2 -, 3.3 -, 4.0 -, 4.1 -, 4.2 -, 4.3 -, 4.4 ✔, 4.5 ✔
  • glVertexArrayVertexBuffers — OpenGL 2.0 -, 2.1 -, 3.0 -, 3.1 -, 3.2 -, 3.3 -, 4.0 -, 4.1 -, 4.2 -, 4.3 -, 4.4 -, 4.5 ✔

so like, if you're on anything under 4.4 for the first one, or under 4.5 for the second? heartbreaking. truly. 💔

🦋 SEE ALSO 🦋

glGenBuffers(), glBindBuffer(), glDeleteBuffers() glDeleteTextures() — (the comma situation is exactly as printed, don't @ me 💜)

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

and that's the page bestie!! 🎀 source: [FIXME: source] · dated 08/09/2021 · GLBINDVERTEXBUFFERS(3G) — go bind some buffers, you're gonna eat 💖✨

📦 where this page comes from