GLTEXSTORAGE1D(3G)

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

🦋 GLTEXSTORAGE1D(3G) 🦋

Okay bestie, this is the GLTEXSTORAGE1D(3G) page, and the header is literally sitting there with [FIXME: manual] in it (we love a work-in-progress icon 😭💅). The whole vibe: set up storage for all levels of a one-dimensional texture at once. No cap.

✨ NAME ✨

glTexStorage1D, glTextureStorage1D — simultaneously specify storage for all levels of a one-dimensional texture. Periodt. 💖

💖 C SPECIFICATION 💖

void glTexStorage1D(GLenum target, GLsizei levels,
                    GLenum internalformat, GLsizei width);

void glTextureStorage1D(GLuint texture, GLsizei levels,
                        GLenum internalformat, GLsizei width);

🎀 PARAMETERS 🎀

  • target — tells you which target the texture object is bound to for glTexStorage1D. It must be one of GL_TEXTURE_1D or GL_PROXY_TEXTURE_1D. That's the whole list, bestie. 💅
  • texture — the texture object name for glTextureStorage1D. Its effective target must be one of the valid non-proxy target values above. So no proxy shenanigans here, okay? 🫶
  • levels — the number of texture levels. Yep, plural, because we're doing all of them at once.
  • internalformat — the sized internal format that'll be used to store texture image data. Sized is the key word, iykyk. ✨
  • width — the width of the texture, in texels. Texels! Not pixels! Very important distinction, bestie. 🦋

🌸 DESCRIPTION 🌸

glTexStorage1D and glTextureStorage1D specify the storage requirements for all levels of a one-dimensional texture simultaneously. It's giving "do it in one shot" energy, and honestly? Obsessed. 🔥

Once a texture is specified with this command, the format and dimensions of all levels 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. She's locked in. 👑

Calling glTexStorage1D is equivalent, assuming no errors are generated, to executing the following pseudo-code:

for (i = 0; i < levels; i++) {
    glTexImage1D(target, i, internalformat, width, 0, format, type, NULL);
    width = max(1, (width / 2));
}

Calling glTextureStorage1D is equivalent to the above pseudo-code, where target is the effective target of texture and it is as if texture were bound to target for the purposes of glTexImage1D. Literally the same energy, just with a texture object name instead. 💫

Since no texture data is actually provided, the values used in the pseudo-code for format and type are irrelevant and may be considered to be any values that are legal for the chosen internalformat enumerant. So don't stress about those, bestie — they're not the main character here. 🙈

internalformat must be one of the sized internal formats given in Table 1 below, one of the sized depth-component formats GL_DEPTH_COMPONENT32F, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT16, one of the combined depth-stencil formats, GL_DEPTH32F_STENCIL8, or GL_DEPTH24_STENCIL8, or the stencil-only format, GL_STENCIL_INDEX8. That's the whole approved list — no improvising. 🌈

Upon success, the value of GL_TEXTURE_IMMUTABLE_FORMAT becomes GL_TRUE. The value of GL_TEXTURE_IMMUTABLE_FORMAT may be discovered by calling glGetTexParameter() with pname set to GL_TEXTURE_IMMUTABLE_FORMAT. So you can check the vibe later. 💜

No further changes to the dimensions or format of the texture object may be made. Using any command that might alter the dimensions or format of the texture object (such as glTexImage1D() or another call to glTexStorage1D) will result in the generation of a GL_INVALID_OPERATION error, even if it would not, in fact, alter the dimensions or format of the object. So like… don't try it. The rules are the rules, and this texture is immutable-format now. 💀✨

...and here's the big one, bestie — Table 1. Sized Internal Formats — literally the whole glow-up menu in one place. Scan it, screenshot it, save it to your notes app, whatever. It's giving reference chart energy and honestly? Iconic. 💅

Columns go: Sized Internal Format, Base Internal Format, then the bit counts for Red, Green, Blue, Alpha, and finally Shared Bits — and yeah, that last column is straight-up empty for every single row here, so don't come for me, I'm just transcribing. 😭

Sized Internal Format | Base Internal Format | Red Bits | Green Bits | Blue Bits | Alpha Bits | Shared Bits
----------------------+----------------------+----------+------------+-----------+------------+------------
GL_R8                 | GL_RED               |    8     |            |           |            |
GL_R8_SNORM           | GL_RED               |    s8    |            |           |            |
GL_R16                | GL_RED               |    16    |            |           |            |
GL_R16_SNORM          | GL_RED               |   s16    |            |           |            |
GL_RG8                | GL_RG                |    8     |     8      |           |            |
GL_RG8_SNORM          | GL_RG                |    s8    |     s8     |           |            |
GL_RG16               | GL_RG                |    16    |     16     |           |            |
GL_RG16_SNORM         | GL_RG                |   s16    |    s16     |           |            |
GL_R3_G3_B2           | GL_RGB               |    3     |     3      |     2     |            |
GL_RGB4               | GL_RGB               |    4     |     4      |     4     |            |
GL_RGB5               | GL_RGB               |    5     |     5      |     5     |            |
GL_RGB8               | GL_RGB               |    8     |     8      |     8     |            |
GL_RGB8_SNORM         | GL_RGB               |    s8    |     s8     |    s8     |            |
GL_RGB10              | GL_RGB               |    10    |     10     |    10     |            |
GL_RGB12              | GL_RGB               |    12    |     12     |    12     |            |
GL_RGB16_SNORM        | GL_RGB               |    16    |     16     |    16     |            |
GL_RGBA2              | GL_RGB               |    2     |     2      |     2     |     2      |
GL_RGBA4              | GL_RGB               |    4     |     4      |     4     |     4      |
GL_RGB5_A1            | GL_RGBA              |    5     |     5      |     5     |     1      |
GL_RGBA8              | GL_RGBA              |    8     |     8      |     8     |     8      |
GL_RGBA8_SNORM        | GL_RGBA              |    s8    |     s8     |    s8     |     s8     |
GL_RGB10_A2           | GL_RGBA              |    10    |     10     |    10     |     2      |
GL_RGB10_A2UI         | GL_RGBA              |   ui10   |    ui10    |   ui10    |    ui2     |
GL_RGBA12             | GL_RGBA              |    12    |     12     |    12     |     12     |
GL_RGBA16             | GL_RGBA              |    16    |     16     |    16     |     16     |
GL_SRGB8              | GL_RGB               |    8     |     8      |     8     |            |
GL_SRGB8_ALPHA8       | GL_RGBA              |    8     |     8      |     8     |     8      |
GL_R16F               | GL_RED               |   f16    |            |           |            |

Quick vibe check on how to read this, because the bit columns are doing the most:

  • Plain numbers like 8, 16, 10, 3 — those are the bit counts, no drama. 🌸
  • s8 / s16 — the s is right there in the name, babe, it's the signed-ish-flavoured vari.
  • ui10 / ui2 — only GL_RGB10_A2UI gets these, and honestly it ate. That's the only row in this whole chunk repping ui anything. 👑
  • f16 — floating-point bits, showing up exactly once here on GL_R16F. ✨
  • And yes, GL_RGBA2 and GL_RGBA4 both list their Base Internal Format as GL_RGB, not GL_RGBA. I am literally just the messenger, do not shoot me 💀 — the table says what the table says.

Also don't @ me about the empty cells — they're empty in the source and they stay empty here. GL_R3_G3_B2 is the only three-channel row that skips 4, 5 and 8 and goes straight for 3/3/2, which, sure, quirky, we love a nonconformist. 🦋

And the list keeps going — GL_R16F is not the last word, bestie...

…and the table just keeps going, bestie 😭 so here's the next chunk. Reminder of what the columns mean: internal format first, then the format it pairs with, then what R, G, B and A are each stored as, plus that last shared-exponent column — which is blank on basically everything here except the one icon that literally needs it 👑

  • GL_RG16F — format is GL_RG; R is f16, G is f16 ✨
  • GL_RGB16F — format is GL_RGB; R is f16, G is f16, B is f16 ✨
  • GL_RGBA16F — format is GL_RGBA; R is f16, G is f16, B is f16, A is f16 ✨
  • GL_R32F — format is GL_RED; R is f32 🔥
  • GL_RG32F — format is GL_RG; R is f32, G is f32 🔥
  • GL_RGB32F — format is GL_RGB; R is f32, G is f32, B is f32 🔥
  • GL_RGBA32F — format is GL_RGBA; R is f32, G is f32, B is f32, A is f32 🔥
  • GL_R11F_G11F_B10F — format is GL_RGB; R is f11, G is f11, B is f10 (three channels, no A, and yes the B one is only f10, that's not a typo 💅)
  • GL_RGB9_E5 — format is GL_RGB; R is 9, G is 9, B is 9, and the shared exponent column is 5 👑 this is the special one
  • GL_R8I — format is GL_RED; R is i8
  • GL_R8UI — format is GL_RED; R is ui8
  • GL_R16I — format is GL_RED; R is i16
  • GL_R16UI — format is GL_RED; R is ui16
  • GL_R32I — format is GL_RED; R is i32
  • GL_R32UI — format is GL_RED; R is ui32
  • GL_RG8I — format is GL_RG; R is i8, G is i8
  • GL_RG8UI — format is GL_RG; R is ui8, G is ui8
  • GL_RG16I — format is GL_RG; R is i16, G is i16
  • GL_RG16UI — format is GL_RG; R is ui16, G is ui16
  • GL_RG32I — format is GL_RG; R is i32, G is i32
  • GL_RG32UI — format is GL_RG; R is ui32, G is ui32
  • GL_RGB8I — format is GL_RGB; R is i8, G is i8, B is i8
  • GL_RGB8UI — format is GL_RGB; R is ui8, G is ui8, B is ui8
  • GL_RGB16I — format is GL_RGB; R is i16, G is i16, B is i16
  • GL_RGB16UI — format is GL_RGB; R is ui16, G is ui16, B is ui16
  • GL_RGB32I — format is GL_RGB; R is i32, G is i32, B is i32
  • GL_RGB32UI — format is GL_RGB; R is ui32, G is ui32, B is ui32
  • GL_RGBA8I — format is GL_RGBA; R is i8, G is i8, B is i8, A is i8
  • GL_RGBA8UI — format is GL_RGBA; R is ui8, G is ui8, B is ui8, A is ui8
  • GL_RGBA16I — format is GL_RGBA; R is i16, G is i16, B is i16, A is i16
  • GL_RGBA16UI — format is GL_RGBA; R is ui16, G is ui16, B is ui16, A is ui16

see how the pattern goes? once you clock the i/ui prefix and the bit count, you can basically read these like a group chat handle 😌 the table's not done though — keep going 🫶

…okay so wrapping up that internal-format table, here's the last little chunk of it — same columns as before, no cap:

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

And that's the whole table, bestie, we survived 💀✨

🫶 NOTES

Okay so tiny little footnote but it MATTERS: GL_STENCIL_INDEX8 is accepted for internalformat only if the GL version is 4.4 or higher. That's it, that's the note. Like, it's giving "you must be this tall to ride" 🎢 — on anything older it's just not happening.

💀 ERRORS

Bestie, here's where you find out what you did wrong. All the ways to get yelled at:

  • GL_INVALID_OPERATION — generated by glTexStorage1D if zero is bound to target. Yeah, you gotta have something bound, babe 🎯
  • GL_INVALID_OPERATION — generated by glTextureStorage1D if texture is not the name of an existing texture object. Ghost texture energy 👻 not a vibe.
  • GL_INVALID_ENUM — generated if internalformat is not a valid sized internal format.
  • GL_INVALID_ENUM — generated if target, or the effective target of texture, is not one of the accepted targets described above.
  • GL_INVALID_VALUE — generated if width or levels is less than 1. Zero and negative are NOT slaying here 🙅‍♀️
  • GL_INVALID_OPERATION — generated if levels is greater than log 2 width + 1. Like the mip levels have to actually fit, periodt.
Lowkey if you're getting one of these at 2am, it's almost always the "zero bound to target" one. Just saying 💅

🌈 VERSION SUPPORT

Okay the moment you've been waiting for: the ✨compatibility chart✨. ✔ means slay, - means not yet, girl.

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

So real talk: glTexStorage1D shows up starting at OpenGL 4.2 and rides all the way through 4.5 👑 while glTextureStorage1D is a total 4.5-only exclusive — the newest-new, main character energy only ✨ And everything from 2.0 through 4.1 for both? Dashes. Nope. Not invited to the party 💀

🦋 SEE ALSO

Go read these when you're done here, iykyk:

  • glTexImage1D()
  • glTexStorage2D()
  • glTexStorage3D()

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

And that's a wrap, bestie!! 🫶🌸 This page is from the source [FIXME: source], dated 08/09/2021, and it lives at GLTEXSTORAGE1D(3G) in the manual. Go forth and allocate your 1D texture storage responsibly, love u, bye 💜👑

📦 where this page comes from