GLCLEARBUFFERSUBDATA(3G)

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

okay bestie, welcome to the GLCLEARBUFFERSUBDATA(3G) page. the header is literally giving [FIXME: manual] (not me, the manpage said it 😭), and the whole vibe is fill all or part of a buffer object's data store with a fixed value. no cap.

✨ NAME ✨

glClearBufferSubData, glClearNamedBufferSubData — fill all or part of buffer object's data store with a fixed value. periodt.

🧾 C SPECIFICATION 🧾

void glClearBufferSubData(GLenum target, GLenum internalformat,
                          GLintptr offset, GLsizeiptr size,
                          GLenum format, GLenum type,
                          const void * data);

void glClearNamedBufferSubData(GLuint buffer, GLenum internalformat,
                               GLintptr offset, GLsizeiptr size,
                               GLenum format, GLenum type,
                               const void *data);

🎀 PARAMETERS 🎀

  • target — specifies the target to which the buffer object is bound for glClearBufferSubData, which must be one of the buffer binding targets in the following list (the original had a table, but the facts are exactly the same):
    • GL_ARRAY_BUFFER — Vertex attributes
    • GL_ATOMIC_COUNTER_BUFFER — Atomic counter storage
    • GL_COPY_READ_BUFFER — Buffer copy source
    • GL_COPY_WRITE_BUFFER — Buffer copy destination
    • GL_DISPATCH_INDIRECT_BUFFER — Indirect compute dispatch commands
    • GL_DRAW_INDIRECT_BUFFER — Indirect command arguments
    • GL_ELEMENT_ARRAY_BUFFER — Vertex array indices
    • GL_PIXEL_PACK_BUFFER — Pixel read target
    • GL_PIXEL_UNPACK_BUFFER — Texture data source
    • GL_QUERY_BUFFER — Query result buffer
    • GL_SHADER_STORAGE_BUFFER — Read-write storage for shaders
    • GL_TEXTURE_BUFFER — Texture data buffer
    • GL_TRANSFORM_FEEDBACK_BUFFER — Transform feedback buffer
    • GL_UNIFORM_BUFFER — Uniform block storage
  • buffer — specifies the name of the buffer object for glClearNamedBufferSubData.
  • internalformat — the internal format with which the data will be stored in the buffer object.
  • offset — the offset in basic machine units into the buffer object's data store at which to start filling.
  • size — the size in basic machine units of the range of the data store to fill.
  • format — the format of the data in memory addressed by data.
  • type — the type of the data in memory addressed by data.
  • data — the address of a memory location storing the data to be replicated into the buffer's data store. that's the pointer bestie, it's giving address of the data to replicate 💅

💖 DESCRIPTION 💖

okay so picture this: glClearBufferSubData and glClearNamedBufferSubData are the besties that fill a specified region of a buffer object's data store with data straight from client memory. no middleman, no drama, just vibes going directly into your buffer 💅

offset and size are the main characters here — they specify the extent of the region within the data store of the buffer object that you're gonna fill with data. think of them as the "where" and "how much" of the whole operation ✨

So the data starts out living in client memory, supplied in a format specified by format, in data type type. It gets read from the memory address given by data, and then converted into the internal representation given by internalformat — which, and this is the important part bestie, must be one of the following sized internal formats 👇

┌─────────────┬───────────┬────────────┬──────┬───────────────┐
│             │           │            │      │   Component   │
├─────────────┼───────────┼────────────┼──────┼───┬───┬───┬───┤
│ Sized       │ Base Type │ Components │ Norm │ 0 │ 1 │ 2 │ 3 │
│ Internal    │           │            │      │   │   │   │   │
│ Format      │           │            │      │   │   │   │   │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R8       │ ubyte     │ 1          │ YES  │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R16      │ ushort    │ 1          │ YES  │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R16F     │ half      │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R32F     │ float     │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R8I      │ byte      │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R16I     │ short     │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R32I     │ int       │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R8UI     │ ubyte     │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R16UI    │ ushort    │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_R32UI    │ uint      │ 1          │ NO   │ R │ 0 │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG8      │ ubyte     │ 2          │ YES  │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG16     │ ushort    │ 2          │ YES  │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG16F    │ half      │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG32F    │ float     │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG8I     │ byte      │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG16I    │ short     │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG32I    │ int       │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG8UI    │ ubyte     │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG16UI   │ ushort    │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RG32UI   │ uint      │ 2          │ NO   │ R │ G │ 0 │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGB32F   │ float     │ 3          │ NO   │ R │ G │ B │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGB32I   │ int       │ 3          │ NO   │ R │ G │ B │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGB32UI  │ uint      │ 3          │ NO   │ R │ G │ B │ 1 │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA8    │ uint      │ 4          │ YES  │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA16   │ short     │ 4          │ YES  │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA16F  │ half      │ 4          │ NO   │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA32F  │ float     │ 4          │ NO   │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA8I   │ byte      │ 4          │ NO   │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA16I  │ short     │ 4          │ NO   │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA32I  │ int       │ 4          │ NO   │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA8UI  │ ubyte     │ 4          │ NO   │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA16UI │ ushort    │ 4          │ NO   │ R │ G │ B │ A │
├─────────────┼───────────┼────────────┼──────┼───┼───┼───┼───┤
│ GL_RGBA32UI │ uint      │ 4          │ NO   │ R │ G │ B │ A │
└─────────────┴───────────┴────────────┴──────┴───┴───┴───┴───┘

like, that's the whole guest list 💀 columns are Sized Internal Format, Base Type, Components, Norm, and then the Component slots 0, 1, 2, 3 — every row is serving its own little R/G/B/A lineup 🎀 no gatekeeping, all 40-ish formats are up there, go wild (within the list, bestie, it says must be)

And then ✨ the moment we've all been waiting for ✨ — that converted data gets replicated throughout the specified region of the buffer object's data store. yes, the whole region. it's giving main character energy across the entire range 🦋

and here's the cute lil plot twist: if data is NULL, then the subrange of the buffer's data store is filled with zeros 🫶 so you don't even need to bring data to the function — it'll still hand you a freshly-zeroed region like the icon it is 💅

heads up bestie: data being NULL isn't an error, it's literally a whole feature — zero-fill mode, no cap 🔥

💀 ERRORS 💀

okay bestie, this is the part where OpenGL yells at you. every single one of these is a real thing that can happen, so let's get into it 👇

  • GL_INVALID_ENUM — thrown by glClearBufferSubData when target isn't one of the generic buffer binding targets. wrong target, wrong vibe, immediate no 💅
  • GL_INVALID_VALUE — thrown by glClearBufferSubData when there's no buffer bound to target. like babe, you have to actually bind something first 😭
  • GL_INVALID_OPERATION — thrown by glClearNamedBufferSubData when buffer isn't the name of an existing buffer object. if the name doesn't exist, we can't clear it, that's just how it is 🫶
  • GL_INVALID_ENUM — thrown when internalformat isn't one of the valid sized internal formats listed in the table above. check the table, bestie, it's right there ✨
  • GL_INVALID_VALUE — thrown when offset or range aren't multiples of the number of basic machine units per-element for the internal format specified by internalformat. the manpage literally tells you how to compute it: multiply the number of components for internalformat from the table by the size of the base type from the table. do the math, slay 🔥
  • GL_INVALID_VALUE — thrown when offset or size is negative, or when $offset + size$ is greater than the value of GL_BUFFER_SIZE for the buffer object. no negative numbers, no going out of bounds, no cap 🚫
  • GL_INVALID_OPERATION — thrown when any part of the specified range of the buffer object is mapped with glMapBufferRange() or glMapBuffer(), unless it was mapped with the GL_MAP_PERSISTENT_BIT bit set in the glMapBufferRange access flags. like you cannot clear a thing while it's mapped unless it's persistent-mapped, periodt 💀
  • GL_INVALID_VALUE — thrown when format isn't a valid format, or type isn't a valid type. two separate ways to fumble, iconic of them ngl 🙈

✨ VERSION SUPPORT ✨

okay so this is the whole "which OpenGL version actually has this" chart, and i'm keeping it exactly as-is because you need to read it, not hear me describe it 🎀

┌───────────────────────────┬───────────────────────────────────────────────────────────────────────┐
│                           │                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                      │     │     │     │     │     │     │     │     │     │     │     │     │
├───────────────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ glClearBufferSubData      │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  ✔  │  ✔  │  ✔  │
├───────────────────────────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┼─────┤
│ glClearNamedBufferSubData │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  -  │  ✔  │
└───────────────────────────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┴─────┘

so like, glClearBufferSubData shows up starting at OpenGL 4.3 and hangs around for 4.4 and 4.5 — everything before that is a dash, as in absolutely not available 💀 and glClearNamedBufferSubData? that one is a 4.5-only situation, a true late bloomer, main character energy honestly 👑

🌸 SEE ALSO 🌸

  • glClearBufferData() — that's the one, go read it 🦋

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 bestie that's the whole page, we did it 💖 this cutie was served up from <pink>[FIXME: source]</pink>, dated <purple>08/09/2021</purple>, and it lives at <hotpink>GLCLEARBUFFERSUBDATA(3G)</hotpink> — go clear some buffers, you're gonna slay ✨👑

📦 where this page comes from