GLDRAWRANGEELEMENTS(3G)

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

💅 GLDRAWRANGEELEMENTS — ok so bestie, let's talk about glDrawRangeElements

(that's a section of the OpenGL manual, and yeah the placeholder header literally says [FIXME: manual], we love a work-in-progress queen 🎀)

🌸 NAME 🌸

glDrawRangeElements — render primitives from array data, but make it range-restricted ✨

🦋 C SPECIFICATION 🦋

void glDrawRangeElements(GLenum mode, GLuint start, GLuint end,
                         GLsizei count, GLenum type,
                         const GLvoid * indices);

💖 PARAMETERS 💖

  • mode — tells the GPU what kind of primitives to render, like, the whole vibe of the shape. It accepts these symbolic constants: GL_POINTS, GL_LINE_STRIP, GL_LINE_LOOP, GL_LINES, GL_LINE_STRIP_ADJACENCY, GL_LINES_ADJACENCY, GL_TRIANGLE_STRIP, GL_TRIANGLE_FAN, GL_TRIANGLES, GL_TRIANGLE_STRIP_ADJACENCY, GL_TRIANGLES_ADJACENCY and GL_PATCHES.
  • start — the smallest array index that's chillin' inside indices.
  • end — the biggest array index that's chillin' inside indices.
  • count — how many elements you want rendered, like a headcount for the party 🎉
  • type — what type the values in indices are. Has to be one of GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT, or GL_UNSIGNED_INT. That's it, that's the list, no negotiations 💅
  • indices — a pointer to wherever you stashed the indices.

✨ DESCRIPTION ✨

So glDrawRangeElements is basically glDrawElements() but with restrictions — it's the good-girl version, the one that stays in its lane. The mode and count arguments match the corresponding arguments to glDrawElements(), except there's this extra rule: every single value in the arrays count has to lie between start and end, inclusive. No sneaking out of range, bestie 🙈

Implementations will tell you the recommended maximum amounts of vertex and index data, and you get those by calling glGet() with the argument GL_MAX_ELEMENTS_VERTICES and GL_MAX_ELEMENTS_INDICES. So here's the tea: if end - start + 1 is greater than the value of GL_MAX_ELEMENTS_VERTICES, OR if count is greater than the value of GL_MAX_ELEMENTS_INDICES, then the call may operate at reduced performance. Like, it still works, it's just gonna be slower and a little sad about it 😭

And listen — there's no requirement that all vertices in the range start end actually get referenced. Nobody's forcing you. But the implementation may partially process unused vertices anyway, which reduces performance from what you could've achieved with an optimal index set. Basically if you're messy about your ranges, you pay for it. Lowkey tragic but that's the deal 🫶

When glDrawRangeElements is called, it uses count sequential elements from an enabled array, starting at start, to construct a sequence of geometric primitives. The mode specifies what kind of primitives get constructed, and how the array elements construct these primitives. If more than one array is enabled, each is used. All of them. Every single one 💀

⚠️ Important vibe check: vertex attributes that are modified by glDrawRangeElements have an unspecified value after glDrawRangeElements returns. Attributes that aren't modified keep their previous values. So don't come crying to me about the ones that got touched, okay? That's undefined territory, that's not my business 🙈

📝 NOTES 📝

GL_LINE_STRIP_ADJACENCY, GL_LINES_ADJACENCY, GL_TRIANGLE_STRIP_ADJACENCY and GL_TRIANGLES_ADJACENCY are only available if the GL version is 3.2 or greater. They're the VIP-only constants, iykyk 👑

💀 ERRORS 💀

  • It is an error for indices to lie outside the range start end — but implementations may not check for this situation. So like, you might just get away with it, and then what happens is implementation-dependent behavior. Which is a fancy way of saying "chaos, unpredicted, good luck" 😭 Don't do it.
  • GL_INVALID_ENUM gets generated if mode is not an accepted value.
  • GL_INVALID_VALUE gets generated if count is negative. Negative elements? In this economy? No ma'am.
  • GL_INVALID_VALUE gets generated if end < start. The range has to go the right way, bestie, be serious.
  • GL_INVALID_OPERATION gets generated if a geometry shader is active and mode is incompatible with the input primitive type of the geometry shader in the currently installed program object. Yes, that's a whole mouthful, and yes, it will yell at you.
  • GL_INVALID_OPERATION gets generated if a non-zero buffer object name is bound to an enabled array or the element array and the buffer object's data store is currently mapped. (Mapped = already busy. Don't double-book. Rude.)

🔍 ASSOCIATED GETS 🔍

  • glGet() with argument GL_MAX_ELEMENTS_VERTICES
  • glGet() with argument GL_MAX_ELEMENTS_INDICES

👑 VERSION SUPPORT 👑

So the original is a big sparkly table called "Function / Feature Name" versus "OpenGL Version" and honestly the whole row is checks all the way down, bestie. glDrawRangeElements has been booked and busy since forever:

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

Every. Single. One. Ate and left no crumbs 🔥

🧚 SEE ALSO 🧚

  • glDrawArrays()
  • glDrawElements()
  • glDrawElementsBaseVertex()

(go read those too, they're the sibling lore 🌈)

Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014 Khronos Group. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.

Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2010-2014 Khronos Group

💜 okay that's the whole page!! source note says [FIXME: source] and the date on this one is 08/09/2021 — so this manual page is a 2021 baby, iconic, and it's the GLDRAWRANGEELEMENTS(3G) page, mwah 💋 go render something beautiful bestie ✨
📦 where this page comes from