GLBINDIMAGETEXTURE(3G)

✨ GLBINDIMAGETEXTURE(3G) — bind a level of a texture to an image unit ✨

okay bestie, welcome to the GLBINDIMAGETEXTURE(3G) page — manual name 3G, and yes the original header literally says [FIXME: manual], we are choosing to ignore that mess and focus on the lore 💅

---

🌸 NAME 🌸

glBindImageTexture — bind a level of a texture to an image unit

---

💻 C SPECIFICATION 💻

void glBindImageTexture(GLuint unit, GLuint texture, GLint level,
                        GLboolean layered, GLint layer, GLenum access,
                        GLenum format);

---

🎀 PARAMETERS 🎀

• unit — the index of the image unit you're binding the texture to, bestie.
• texture — the name of the texture that's getting bound to the image unit.
• level — which level of the texture is getting bound. yes, that level.
• layered — tells us whether a layered texture binding is being established.
• layer — if layered is GL_FALSE, this says which layer of the texture gets bound to the image unit. ignored otherwise, so don't stress it.
• access — a token that says what kind of access is gonna happen on the image.
• format — the format that the image's elements get treated as for formatted stores.

---

🦋 DESCRIPTION 🦋

okay so glBindImageTexture binds a single level of a texture to an image unit so shaders can read from it and write to it. unit is the zero-based index of the image unit where the texture level goes. texture is the name of an existing texture object to bind to that image unit. and if texture is zero? boom, any existing binding to the image unit is broken. level is the level of the texture being bound to the image unit. iconic.

if texture is the name of a one-, two-, or three-dimensional array texture, a cube map or cube map array texture, or a two-dimensional multisample array texture, then you can bind either the entire array or just a single layer of the array to the image unit. in those cases:

• if layered is GL_TRUE, the entire array is attached to the image unit and layer is ignored.
• if layered is GL_FALSE, then layer specifies the layer of the array to attach to the image unit.

access specifies the access types that shaders will perform, and it can be set to GL_READ_ONLY, GL_WRITE_ONLY, or GL_READ_WRITE to mean read-only, write-only, or read-write access, respectively. and listen: violating the access type in access — like if a shader writes to an image bound with access set to GL_READ_ONLY — leads to undefined results, possibly including program termination. not a vibe, do not do it 😭

format specifies the format used when performing formatted stores into the image from shaders. format must be compatible with the texture's internal format and must be one of the formats listed in the following table. here's the whole compatibility roster, no skips:

💖 Table 1. Internal Image Formats 💖

• GL_RGBA32F — rgba32f
• GL_RGBA16F — rgba16f
• GL_RG32F — rg32f
• GL_RG16F — rg16f
• GL_R11F_G11F_B10F — r11f_g11f_b10f
• GL_R32F — r32f
• GL_R16F — r16f
• GL_RGBA32UI — rgba32ui
• GL_RGBA16UI — rgba16ui
• GL_RGB10_A2UI — rgb10_a2ui
• GL_RGBA8UI — rgba8ui
• GL_RG32UI — rg32ui
• GL_RG16UI — rg16ui
• GL_RG8UI — rg8ui
• GL_R32UI — r32ui
• GL_R16UI — r16ui
• GL_R8UI — r8ui
• GL_RGBA32I — rgba32i
• GL_RGBA16I — rgba16i
• GL_RGBA8I — rgba8i
• GL_RG32I — rg32i
• GL_RG16I — rg16i
• GL_RG8I — rg8i
• GL_R32I — r32i
• GL_R16I — r16i
• GL_R8I — r8i
• GL_RGBA16 — rgba16
• GL_RGB10_A2 — rgb10_a2
• GL_RGBA8 — rgba8
• GL_RG16 — rg16
• GL_RG8 — rg8
• GL_R16 — r16
• GL_R8 — r8
• GL_RGBA16_SNORM — rgba16_snorm
• GL_RGBA8_SNORM — rgba8_snorm
• GL_RG16_SNORM — rg16_snorm
• GL_RG8_SNORM — rg8_snorm
• GL_R16_SNORM — r16_snorm
• GL_R8_SNORM — r8_snorm

when a texture is bound to an image unit, the format parameter for the image unit does not need to exactly match the texture's internal format, as long as the formats are considered compatible as defined in the OpenGL Specification. the matching criterion used for a given texture may be determined by calling glGetTexParameter() with value set to GL_IMAGE_FORMAT_COMPATIBILITY_TYPE, with return values of GL_IMAGE_FORMAT_COMPATIBILITY_BY_SIZE and GL_IMAGE_FORMAT_COMPATIBILITY_BY_CLASS, specifying matches by size and class, respectively. iykyk 🧚

---

⭐ NOTES ⭐

glBindImageTexture is available only if the GL version is 4.2 or greater. that's the whole note, bestie — short and slay.

---

💀 ERRORS 💀

• GL_INVALID_VALUE is generated if unit is greater than or equal to the value of GL_MAX_IMAGE_UNITS.
• GL_INVALID_VALUE is generated if texture is not the name of an existing texture object.
• GL_INVALID_VALUE is generated if level or layer is less than zero.
• GL_INVALID_ENUM is generated if access or format is not one of the supported tokens.

💖 ASSOCIATED GETS 💖

okay bestie, these are the glGet() queries associated with this whole situation — if you need to check the binding later, this is the exact list:

• glGet() with argument GL_IMAGE_BINDING_NAME.
• glGet() with argument GL_IMAGE_BINDING_LEVEL.
• glGet() with argument GL_IMAGE_BINDING_LAYERED.
• glGet() with argument GL_IMAGE_BINDING_LAYER.
• glGet() with argument GL_IMAGE_BINDING_ACCESS.
• glGet() with argument GL_IMAGE_BINDING_FORMAT.

---

🌈 VERSION SUPPORT 🌈

the columns are Function / Feature Name and OpenGL Version, and glBindImageTexture is literally the main character here. here's every single version cell, no cap:

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

that's the whole support table preserved cell by cell, bestie ✨

---

🦋 SEE ALSO 🦋

go peek at these besties when you're done:

• glGenTextures()
• glTexImage1D()
• glTexImage2D()
• glTexImage3D()
• glTexStorage1D()
• glTexStorage2D()
• glTexStorage3D()
• glBindTexture()

---

📜 COPYRIGHT 📜

keeping this exactly as it is, because legal text is not the vibe to paraphrase:

Copyright © 2011-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 💜

and yep, there's a second copyright line — still keeping it exact:

Copyright © 2011-2014 Khronos Group

---

and that's the page, bestie 🫶 footer deets: source [FIXME: source], dated 08/09/2021, and the page is GLBINDIMAGETEXTURE(3G). mwah 💋