GLTEXSTORAGE3DMULTIS(3G)

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

💖 glTexStorage3DMultisample(3G) 💖

okay bestie, welcome to the <pink>glTexStorage3DMultisample(3G)</pink> manual page — we're doing texture storage setup and it's giving main character energy ✨

🌸 NAME 🌸

glTexStorage3DMultisample, glTextureStorage3DMultisample — specify storage for a two-dimensional multisample array texture. periodt. 💅

✨ C SPECIFICATION ✨

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

void glTextureStorage3DMultisample(GLuint texture, GLsizei samples,
                                   GLenum internalformat, GLsizei width,
                                   GLsizei height, GLsizei depth,
                                   GLboolean fixedsamplelocations);

🎀 PARAMETERS 🎀

  • target — specifies the target to which the texture object is bound for glTexStorage3DMultisample. Must be one of GL_TEXTURE_2D_MULTISAMPLE_ARRAY or GL_PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY. no cap, those are the only two 💫
  • texture — specifies the texture object name for glTextureStorage3DMultisample. The effective target of texture must be one of the valid non-proxy target values above. iykyk 🫶
  • samples — specify the number of samples in the texture.
  • internalformat — specifies the sized internal format to be used to store texture image data.
  • width — specifies the width of the texture, in texels.
  • height — specifies the height of the texture, in texels.
  • depth — specifies the depth of the texture, in layers.
  • fixedsamplelocations — specifies whether 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 size of the image. iconic behavior honestly 🎀

🦋 DESCRIPTION 🦋

glTexStorage3DMultisample and glTextureStorage3DMultisample specify the storage requirements for a two-dimensional multisample array texture. Once a texture is specified with this command, its format and dimensions become immutable unless it is a proxy texture. The contents of the image may still be modified, however, its storage requirements may not change. Such a texture is referred to as an immutable-format texture. lock it in bestie 🔒✨

samples specifies the number of samples to be used for the texture and must be greater than zero and less than or equal to the value of GL_MAX_SAMPLES. internalformat must be a color-renderable, depth-renderable, or stencil-renderable format. width and height specify the width and height, respectively, of the texture and depth specifies the depth (or the number of layers) of the texture. 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 size of the image. the way that's so specific — we love a consistent queen 💖🦋

🎀 Table 1. Sized Internal Formats (the rest of it) 🎀

Okay bestie, this is the full sized-internal-formats board — every row, exactly as printed, no editorialising from me. Quick heads-up before you scroll: a bunch of the bit counts come with a little prefix attached (s8, s16, f16, ui10, ui2), and the Shared Bits column is blank on every single row here, so I'm calling that out once instead of twenty-eight times. Copy what you see, character for character. 💅

  • GL_R8 — base GL_RED. Red 8; green, blue, alpha and shared bits are blank.
  • GL_R8_SNORM — base GL_RED. Red s8; green, blue, alpha and shared bits blank.
  • GL_R16 — base GL_RED. Red 16; green, blue, alpha and shared bits blank.
  • GL_R16_SNORM — base GL_RED. Red s16; green, blue, alpha and shared bits blank.
  • GL_RG8 — base GL_RG. Red 8, green 8; blue, alpha and shared bits blank.
  • GL_RG8_SNORM — base GL_RG. Red s8, green s8; blue, alpha and shared bits blank.
  • GL_RG16 — base GL_RG. Red 16, green 16; blue, alpha and shared bits blank.
  • GL_RG16_SNORM — base GL_RG. Red s16, green s16; blue, alpha and shared bits blank.
  • GL_R3_G3_B2 — base GL_RGB. Red 3, green 3, blue 2; alpha and shared bits blank.
  • GL_RGB4 — base GL_RGB. Red 4, green 4, blue 4; alpha and shared bits blank.
  • GL_RGB5 — base GL_RGB. Red 5, green 5, blue 5; alpha and shared bits blank.
  • GL_RGB8 — base GL_RGB. Red 8, green 8, blue 8; alpha and shared bits blank.
  • GL_RGB8_SNORM — base GL_RGB. Red s8, green s8, blue s8; alpha and shared bits blank.
  • GL_RGB10 — base GL_RGB. Red 10, green 10, blue 10; alpha and shared bits blank.
  • GL_RGB12 — base GL_RGB. Red 12, green 12, blue 12; alpha and shared bits blank.
  • GL_RGB16_SNORM — base GL_RGB. Red 16, green 16, blue 16; alpha and shared bits blank. (Yep — that's how the table writes it. I'm the messenger, not the editor. 🫶)
  • GL_RGBA2 — base GL_RGB. Red 2, green 2, blue 2, alpha 2; shared bits blank. (Base says GL_RGB, the name says RGBA — again, exactly as printed. 🙈)
  • GL_RGBA4 — base GL_RGB. Red 4, green 4, blue 4, alpha 4; shared bits blank.
  • GL_RGB5_A1 — base GL_RGBA. Red 5, green 5, blue 5, alpha 1; shared bits blank.
  • GL_RGBA8 — base GL_RGBA. Red 8, green 8, blue 8, alpha 8; shared bits blank.
  • GL_RGBA8_SNORM — base GL_RGBA. Red s8, green s8, blue s8, alpha s8; shared bits blank.
  • GL_RGB10_A2 — base GL_RGBA. Red 10, green 10, blue 10, alpha 2; shared bits blank.
  • GL_RGB10_A2UI — base GL_RGBA. Red ui10, green ui10, blue ui10, alpha ui2; shared bits blank.
  • GL_RGBA12 — base GL_RGBA. Red 12, green 12, blue 12, alpha 12; shared bits blank.
  • GL_RGBA16 — base GL_RGBA. Red 16, green 16, blue 16, alpha 16; shared bits blank.
  • GL_SRGB8 — base GL_RGB. Red 8, green 8, blue 8; alpha and shared bits blank.
  • GL_SRGB8_ALPHA8 — base GL_RGBA. Red 8, green 8, blue 8, alpha 8; shared bits blank.
  • GL_R16F — base GL_RED. Red f16; green, blue, alpha and shared bits blank.

Ngl, that's a whole lot of formats and every last one of them is here — nothing skipped, nothing merged, nothing "cleaned up". ✨

  • GL_RG16F — format GL_RG, red f16, green f16 💖
  • GL_RGB16F — format GL_RGB, red f16, green f16, blue f16
  • GL_RGBA16F — format GL_RGBA, red f16, green f16, blue f16, alpha f16 ✨
  • GL_R32F — format GL_RED, red f32
  • GL_RG32F — format GL_RG, red f32, green f32
  • GL_RGB32F — format GL_RGB, red f32, green f32, blue f32
  • GL_RGBA32F — format GL_RGBA, red f32, green f32, blue f32, alpha f32 🔥

ok so that whole stretch was the float girlies — f16 then f32, living their best floaty lives. no cap, very demure, very mindless. now we get the weird ones and honestly? iconic behaviour ahead 🫶

  • GL_R11F_G11F_B10F — format GL_RGB, red f11, green f11, blue f10 — yes bestie, the bits are uneven, it's giving chaos but make it efficient 💅
  • GL_RGB9_E5 — format GL_RGB, red 9, green 9, blue 9, and a shared-exponent value of 5 in that last column 🎀
lowkey obsessed with GL_RGB9_E5 because it's the only one on this whole page that uses that shared column for real. main character energy fr fr.

and now, the integer era 😭 buckle up, there are like a million of these and they're all extremely same-but-different. the pattern is genuinely simple though — I means signed, UI means unsigned, the number is the bit width, and R/RG/RGB/RGBA tells you how many channels get that width. slay, honestly.

  • GL_R8I — format GL_RED, red i8
  • GL_R8UI — format GL_RED, red ui8
  • GL_R16I — format GL_RED, red i16
  • GL_R16UI — format GL_RED, red ui16
  • GL_R32I — format GL_RED, red i32
  • GL_R32UI — format GL_RED, red ui32
  • GL_RG8I — format GL_RG, red i8, green i8
  • GL_RG8UI — format GL_RG, red ui8, green ui8
  • GL_RG16I — format GL_RG, red i16, green i16
  • GL_RG16UI — format GL_RG, red ui16, green ui16
  • GL_RG32I — format GL_RG, red i32, green i32
  • GL_RG32UI — format GL_RG, red ui32, green ui32
  • GL_RGB8I — format GL_RGB, red i8, green i8, blue i8
  • GL_RGB8UI — format GL_RGB, red ui8, green ui8, blue ui8
  • GL_RGB16I — format GL_RGB, red i16, green i16, blue i16
  • GL_RGB16UI — format GL_RGB, red ui16, green ui16, blue ui16
  • GL_RGB32I — format GL_RGB, red i32, green i32, blue i32
  • GL_RGB32UI — format GL_RGB, red ui32, green ui32, blue ui32
  • GL_RGBA8I — format GL_RGBA, red i8, green i8, blue i8, alpha i8 🌸
  • GL_RGBA8UI — format GL_RGBA, red ui8, green ui8, blue ui8, alpha ui8
  • GL_RGBA16I — format GL_RGBA, red i16, green i16, blue i16, alpha i16
  • GL_RGBA16UI — format GL_RGBA, red ui16, green ui16, blue ui16, alpha ui16 💜

SEE? told you it was a pattern 😌 once you clock that it's just signedness + bit width + channel count, you can basically read the rest of this table on vibes alone. and there's still more coming, because of course there is — the 32-bit RGBA integer crew and friends are right around the corner, so like… stay with me bestie 🙈

...and the last two rows of the format table, same energy, same columns:

│ GL_RGBA32I        │ GL_RGBA  │   i32    │    i32     │    i32    │    i32     │        │
├───────────────────┼──────────┼──────────┼────────────┼───────────┼────────────┼────────┤
│ GL_RGBA32UI       │ GL_RGBA  │   ui32   │    ui32    │   ui32    │    ui32    │        │
└───────────────────┴──────────┴──────────┴────────────┴───────────┴────────────┴────────┘

okay bestie, table's done, deep breath, now the part everyone skims and then regrets skimming 💀

🚨 ERRORS 🚨

Like, these are the ways you can mess up. Read them. Please. For me. 🥺

  • GL_INVALID_OPERATION is generated by glTexStorage3DMultisample if zero is bound to target. (nothing there, nothing to work with 🙈)
  • GL_INVALID_OPERATION is generated by glTextureStorage3DMultisample if texture is not the name of an existing texture object. (girl, that texture does not exist 😭)
  • GL_INVALID_ENUM is generated if internalformat is not a valid color-renderable, depth-renderable or stencil-renderable format. (renderable is the vibe check here, it has to pass)
  • GL_INVALID_ENUM is generated if target or the effective target of texture is not one of the accepted targets described above.
  • GL_INVALID_VALUE is generated if width or height are less than 1 or greater than the value of GL_MAX_TEXTURE_SIZE. (1 is the floor, ok?)
  • GL_INVALID_VALUE is generated if depth is less than 1 or greater than the value of GL_MAX_ARRAY_TEXTURE_LAYERS.
  • GL_INVALID_VALUE is generated if levels is less than 1.
  • GL_INVALID_VALUE is generated if samples is zero. (zero samples is giving nothing, and we do not stan nothing)
  • GL_INVALID_OPERATION is generated if samples is greater than the maximum number of samples supported for this target and internalformat.
  • GL_INVALID_OPERATION is generated if the value of GL_TEXTURE_IMMUTABLE_FORMAT for the texture bound to target is not GL_FALSE. (immutable means immutable, bestie — it's immutable 💅)
tl;dr if it's complaining, it's almost always: bad format, bad target, a number out of range, or you already locked this texture down. Check the list before you spiral. 🫶

🔍 ASSOCIATED GETS 🔍

Stuff you can ask the GL about with glGetInteger with arguments GL_MAX_TEXTURE_SIZE, GL_MAX_ARRAY_TEXTURE_LEVELS, GL_TEXTURE_VIEW_MIN_LAYER, GL_TEXTURE_VIEW_NUM_LAYERS, or GL_TEXTURE_IMMUTABLE_LEVELS.

(ngl this is the "who am I, where am I, what are my limits" section and honestly relatable ✨)

📅 VERSION SUPPORT 📅

Here's the whole grid, verbatim, because I would never gatekeep an OpenGL version table from you 💖

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

so like 🫶 glTexStorage3DMultisample shows up at 4.3 and stays through 4.4 and 4.5, and glTextureStorage3DMultisample is a 4.5-only icon, no earlier dashes for her. the - means not supported, don't try it 💀

🦋 SEE ALSO 🦋

the whole friend group, go say hi:

  • glTexImage3D()
  • glTexImage3DMultisample()
  • glTexStorage1D()
  • glTexStorage2DMultisample()
  • glTexStorage3D()

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

(yes bestie, it really does say it twice. the manpage said it, so I said it. periodt 👑)

and that's the whole page!! you made it to the bottom, I'm so proud of you 🥹💜 the source is a lil [FIXME: source] placeholder situation and the version/date on this one is 08/09/2021, stamped with GLTEXSTORAGE3DMULTIS(3G). now go forth and multisample responsibly, ily, bye 💅✨🍓

📦 where this page comes from