GLINVALIDATESUBFRAME(3G)

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

💅 GLINVALIDATESUBFRAME — the 3G manual page, bestie edition ✨

Okay so like, this is the 3G manual page and it's about throwing away chunks of your framebuffer like it's last season's fit. No cap, it's giving "selective memory loss, but for pixels" 🫶

✨ NAME ✨

glInvalidateSubFramebuffer, glInvalidateNamedFramebufferSubData — invalidate the content of a region of some or all of a framebuffer's attachments 💫

🎀 C SPECIFICATION 🎀

Like, here's literally the exact signatures, don't @ me:

void glInvalidateSubFramebuffer(GLenum target, GLsizei numAttachments,
                                const GLenum * attachments, GLint x,
                                GLint y, GLint width, GLint height);

void glInvalidateNamedFramebufferSubData(GLuint framebuffer,
                                         GLsizei numAttachments,
                                         const GLenum *attachments,
                                         GLint x, GLint y,
                                         GLsizei width, GLsizei height);

🌸 PARAMETERS 🌸

  • target — the target the framebuffer object is attached to, for glInvalidateSubFramebuffer. iykyk 🎯
  • framebuffer — the name of the framebuffer object, for glInvalidateNamedFramebufferSubData. it's giving "which one, bestie?" 👑
  • numAttachments — how many entries are in the attachments array. count 'em 💅
  • attachments — a pointer to an array identifying the attachments to be invalidated. the hit list 📋
  • x — the X offset of the region to be invalidated 🌈
  • y — the Y offset of the region to be invalidated 🌈
  • width — the width of the region to be invalidated 📏
  • height — the height of the region to be invalidated 📏

🦋 DESCRIPTION 🦋

So glInvalidateSubFramebuffer and glInvalidateNamedFramebufferSubData invalidate the contents of a specified region of a specified set of attachments of a framebuffer. Basically: "this part? don't care. bin it." 💀

For glInvalidateSubFramebuffer, the framebuffer object is the one bound to target, and target must be one of GL_FRAMEBUFFER, GL_READ_FRAMEBUFFER or GL_DRAW_FRAMEBUFFER. Heads up: GL_FRAMEBUFFER is equivalent to GL_DRAW_FRAMEBUFFER. Default framebuffers may also be invalidated if bound to target ✨

For glInvalidateNamedFramebufferSubData, framebuffer is the name of the framebuffer object. If framebuffer is zero, the default draw framebuffer is affected. zero = "do the default one, babe" 🙈

The set of attachments of which a region is to be invalidated is specified in the attachments array, which contains numAttachments elements 🎀

If the specified framebuffer is a framebuffer object, each element of attachments must be one of GL_DEPTH_ATTACHMENT, GL_STENCIL_ATTACHMENT GL_DEPTH_STENCIL_ATTACHMENT, or GL_COLOR_ATTACHMENTi, where i is between zero and the value of GL_MAX_FRAMEBUFFER_ATTACHMENTS minus one. (Yeah, we noticed the missing comma in the original too. copying it exactly, periodt 💅)

If the specified framebuffer is a default framebuffer, each element of attachments must be one of GL_FRONT_LEFT, GL_FRONT_RIGHT, GL_BACK_LEFT, GL_BACK_RIGHT, GL_AUXi, GL_ACCUM, GL_COLOR, GL_DEPTH, or GL_STENCIL. GL_COLOR is treated as GL_BACK_LEFT for a double-buffered context and GL_FRONT_LEFT for a single-buffered context. The other attachments identify the corresponding specific buffer. like, they know exactly which one they are 💁‍♀️

The contents of the specified region of each specified attachment become undefined after execution of glInvalidateSubFramebuffer or glInvalidateNamedFramebufferSubData 😭 Undefined, bestie. The region to be invalidated is specified by x, y, width and height where x and y give the offset from the origin (with lower-left corner at $(0,0)$) and width and height are the width and height, respectively, of the region. Any pixels lying outside of the window allocated to the current GL context (for the default framebuffer), or outside of the attachments of the framebuffer object, are ignored — they're not on the guest list, so they're not getting invalidated 🚫✨ If the framebuffer object is not complete, these commands may be ignored.

If the framebuffer object is not complete, glInvalidateSubFramebuffer and glInvalidateNamedFramebufferSubData may be ignored. This is not an error. no thoughts, head empty, no error 💀

💜 ERRORS 💜

  • GL_INVALID_ENUM by glInvalidateSubFramebuffer if target is not one of the accepted framebuffer targets 😤
  • GL_INVALID_OPERATION by glInvalidateNamedFramebufferSubData if framebuffer is not zero of the name of an existing framebuffer object
  • GL_INVALID_VALUE is generated if numAttachments, width or height is negative. no negative vibes allowed 🚫
  • GL_INVALID_ENUM is generated if any element of attachments is not one of the accepted framebuffer attachment points, as described above
  • GL_INVALID_OPERATION is generated if element of attachments is GL_COLOR_ATTACHMENTm where m is greater than or equal to the value of GL_MAX_COLOR_ATTACHMENTS. m said "I'm too iconic for this" 👑

⭐ ASSOCIATED GETS ⭐

glGet() with argument GL_MAX_COLOR_ATTACHMENTS. that's the one, that's the vibe check 🔥

🌈 VERSION SUPPORT 🌈

So the original ships a whole grid here, and I'm not about to lose a single cell of it — here's every version, every yes/no, intact 🫶

glInvalidateNamedFramebufferSubData

  • 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 — ✔

glInvalidateSubFramebuffer

  • 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 — ✔

💖 SEE ALSO 💖

Go read these next, they're all in the same friend group, fr fr:

  • glInvalidateTexSubImage()
  • glInvalidateTexImage()
  • glInvalidateBufferSubData()
  • glInvalidateBufferData()
  • glInvalidateFramebuffer()

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

okay that's the whole thing, nothing skipped, nothing dropped, every flag and every version cell accounted for. you're welcome, bestie 💅✨

And the cute sign-off: this page comes from [FIXME: source], dated 08/09/2021, and it's the GLINVALIDATESUBFRAME(3G) girlies' official paperwork. mwah 😘💖

📦 where this page comes from