GLTEXIMAGE3DMULTISAM(3G)

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

💅 GLTEXIMAGE3DMULTISAM(3G) 💅

okay bestie, welcome to the glTexImage3DMultisample page — yes that's a whole mouthful, and yes it's from the 3G manual. Say it with me: gl-tex-image-three-dee-multi-sample. Iconic. Let's get into it 🫶

✨ NAME ✨

glTexImage3DMultisample — the glow-up that sets up the data storage, the format, the dimensions, and the number of samples for a multisample texture's image. it's giving "set the whole vibe of your texture in one call" 💖

🧚 C SPECIFICATION 🧚

copy this exactly, no cap:

void glTexImage3DMultisample(GLenum target, GLsizei samples,
                             GLenum internalformat, GLsizei width,
                             GLsizei height, GLsizei depth,
                             GLboolean fixedsamplelocations);

🌸 PARAMETERS 🌸

  • target — which target we're doing the operation on. lowkey strict: it must be GL_TEXTURE_2D_MULTISAMPLE_ARRAY or GL_PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY. no other options, sorry bestie 💀
  • samples — the number of samples in the multisample texture's image. that's the whole point of the function, so yeah, it matters 🎀
  • internalformat — the internal format used to store the multisample texture's image. and heads up: internalformat must specify a color-renderable, depth-renderable, or stencil-renderable format. those are the only three flavours allowed ✨
  • width — the width of the multisample texture's image, measured in texels 📏
  • height — the height of the multisample texture's image, also in texels 📐
  • fixedsamplelocations — tells you whether the image is gonna use identical sample locations and the same number of samples for all texels in the image, and whether the sample locations won't depend on the internal format or the size of the image. that's a lot of words but it's exactly what it says 🦋

💜 DESCRIPTION 💜

glTexImage3DMultisample establishes the data storage, the format, the dimensions and the number of samples of a multisample texture's image. it's the "let there be texture" moment 🌈

target must be GL_TEXTURE_2D_MULTISAMPLE_ARRAY or GL_PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY — it's a vibe check and you gotta pass it.

width and height are the dimensions in texels of the texture, and they must be in the range zero to the value of GL_MAX_TEXTURE_SIZE minus one. depth is the number of array slices in the array texture's image. samples specifies the number of samples in the image, and it must be in the range zero to the value of GL_MAX_SAMPLES minus one 👑

internalformat must be a color-renderable, depth-renderable, or stencil-renderable format. periodt.

if fixedsamplelocations is GL_TRUE, the image will use identical sample locations and the same number of samples for all texels in the image, and the sample locations will not depend on the internal format or the size of the image. so consistent. so reliable. main character energy 💅

when a multisample texture is accessed in a shader, the access takes one vector of integers describing which texel to fetch, plus an integer corresponding to the sample number describing which sample within the texel to fetch. and no standard sampling instructions are allowed on the multisample texture targets. like, none. don't even try it 😭

⭐ NOTES ⭐

glTexImage2DMultisample is available only if the GL version is 3.2 or greater. (yes, the note says glTexImage2DMultisample — that's literally what it says, don't come for me 🙈)

💀 ERRORS 💀

here's the part where things go wrong, and there are a lot of ways:

  • GL_INVALID_OPERATION is generated if internalformat is a depth- or stencil-renderable format and samples is greater than the value of GL_MAX_DEPTH_TEXTURE_SAMPLES.
  • GL_INVALID_OPERATION is generated if internalformat is a color-renderable format and samples is greater than the value of GL_MAX_COLOR_TEXTURE_SAMPLES.
  • GL_INVALID_OPERATION is generated if internalformat is a signed or unsigned integer format and samples is greater than the value of GL_MAX_INTEGER_SAMPLES.
  • GL_INVALID_VALUE is generated if either width or height negative or is greater than GL_MAX_TEXTURE_SIZE.
  • GL_INVALID_VALUE is generated if depth is negative or is greater than GL_MAX_ARRAY_TEXTURE_LAYERS.
  • GL_INVALID_VALUE is generated if samples is zero.
  • GL_INVALID_OPERATION is generated if samples is greater than the maximum number of samples supported for this target and internalformat.
bestie the sample limits are different per format type and there's also a per-target+internalformat max on top of that. read the room (and the spec) before you pass a number 😤

🎀 VERSION SUPPORT 🎀

the original ships this as a big grid, so let's translate: rows are Function / Feature Name, columns are OpenGL Version, and the checkmarks say where glTexImage3DMultisample exists. here's the tea 🍓

  • 2.0 — - (nope)
  • 2.1 — - (still nope)
  • 3.0 — - (nope again)
  • 3.1 — - (nope, keep waiting)
  • 3.2 — ✔ (THERE she is 🔥)
  • 3.3 — ✔
  • 4.0 — ✔
  • 4.1 — ✔
  • 4.2 — ✔
  • 4.3 — ✔
  • 4.4 — ✔
  • 4.5 — ✔

so: glTexImage3DMultisample shows up from 3.2 onward and slays through 4.5, and it's absent for 2.0, 2.1, 3.0 and 3.1. iykyk 👑

🦋 SEE ALSO 🦋

go read these next, they're literally in the same friend group:

  • glTexImage3D()
  • glTexImage2DMultisample()

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

okay that's the whole page!! this came from [FIXME: source] and it's dated 08/09/2021, and yeah the manual name up top is GLTEXIMAGE3DMULTISAM(3G) in case you forgot 💖 go forth and multisample responsibly, bestie 🧚✨

📦 where this page comes from