GLCOPYTEXIMAGE1D(3G)

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

💅 GLCOPYTEXIMAGE1D 💅

okay bestie so this one lives in the 3G manual section and it's literally called glCopyTexImage1D — iconic name, iconic job. Let's get into it 🫶

✨ NAME ✨

glCopyTexImage1D — copy pixels into a 1D texture image. that's it, that's the whole vibe 💖

🌸 C SPECIFICATION 🌸

void glCopyTexImage1D(GLenum target, GLint level, GLenum internalformat,
                      GLint x, GLint y, GLsizei width, GLint border);

like, look at that signature. seven whole arguments. she's high-maintenance and she's worth it ✨

🎀 PARAMETERS 🎀

  • target — which texture you're aiming at. must be GL_TEXTURE_1D. no cap, that's the only one allowed.
  • level — the level-of-detail number, aka which mipmap floor you're on. level 0 is the base image level, and level n is the *n*th mipmap reduction image. it's giving elevator floors but make it graphics 💅
  • internalformat — what the texture is made of internally. must be one of these symbolic constants, and yes i'm listing every single one because we don't do half-measures here:

GL_COMPRESSED_RED, GL_COMPRESSED_RG, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGB_ALPHA, GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, GL_DEPTH_COMPONENT32, GL_STENCIL_INDEX8, GL_RED, GL_RG, GL_RGB, GL_R3_G3_B2, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, GL_RGBA16, GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, GL_SRGB8_ALPHA8.

  • x, y — the window coordinates of the left corner of the row of pixels you're copying. left corner, bestie. remember that 🦋
  • width — how wide the texture image is. and the height? it's 1. always 1. one-dimensional, babe, that's the whole point 😌
  • border — must be 0. that's not a suggestion, that's the rule 💀

🦋 DESCRIPTION 🦋

glCopyTexImage1D defines a one-dimensional texture image, and the pixels come straight from the current GL_READ_BUFFER. like she's shopping directly out of the read buffer, no middleman 💖

the screen-aligned pixel row with its left corner at x y and a length of width is what defines the texture array at the mipmap level specified by level. and internalformat says what the internal format of that texture array is. simple as.

the pixels in that row get processed exactly as if glReadPixels() had been called — but the process stops just before final conversion. at that point, every pixel component value is clamped to the range 0 1 and then converted to the texture's internal format so it can be stored in the texel array. it's giving "almost done, one more step" energy ✨

pixel ordering goes like this: lower x screen coordinates correspond to lower texture coordinates. so like, left is left. slay.

⚠️ okay listen: if any of the pixels within the specified row of the current GL_READ_BUFFER are outside the window associated with the current rendering context, then the values you get for those pixels are undefined. not "probably fine", not "close enough" — undefined. do not test her 🙈

glCopyTexImage1D defines a one-dimensional texture image with pixels from the current GL_READ_BUFFER. (yes she says it twice. she's thorough. let her live.)

when internalformat is one of the sRGB types, the GL does not automatically convert the source pixels to the sRGB color space. in that case, the glPixelMap function can be used to accomplish the conversion. so like, do it yourself bestie, she's not doing it for you 💅

💜 NOTES 💜

  • 1, 2, 3, and 4 are not accepted values for internalformat. nope. not a thing. don't try it.
  • an image with 0 width indicates a NULL texture. zero width, zero texture, zero drama.
  • GL_STENCIL_INDEX8 is accepted for internalformat only if the GL version is 4.4 or higher. check your version first, i'm begging 🫶

🔥 ERRORS 🔥

like, the ways she can say no:

  • GL_INVALID_ENUM is generated if target is not one of the allowable values.
  • GL_INVALID_VALUE is generated if level is less than 0.
  • GL_INVALID_VALUE may be generated if level is greater than log 2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
  • GL_INVALID_VALUE is generated if internalformat is not an allowable value.
  • GL_INVALID_VALUE is generated if width is less than 0 or greater than GL_MAX_TEXTURE_SIZE.
  • GL_INVALID_VALUE is generated if border is not 0.
  • GL_INVALID_OPERATION is generated if internalformat is GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32 and there is no depth buffer. no depth buffer, no depth component, that's the deal 😭

⭐ ASSOCIATED GETS ⭐

glGetTexImage()

that's the one. that's the list. she's lowkey minimal here 🌈

👑 VERSION SUPPORT 👑

the original had a whole big table, so here's the tea in a form that won't break your terminal: glCopyTexImage1D is supported in every single OpenGL version listed, ✔ across the board. the columns were 2.0, 2.1, 3.0, 3.1, 3.2, 3.3, 4.0, 4.1, 4.2, 4.3, 4.4, 4.5 — and the function row? checkmarked in all twelve. she ate and left no crumbs 🔥

(the table's row label was Function / Feature Name, and our function is glCopyTexImage1D. full transparency, bestie 👑)

🧚 SEE ALSO 🧚

  • glCopyTexImage2D()
  • glCopyTexSubImage1D()
  • glCopyTexSubImage2D()
  • glPixelStore()
  • glTexImage1D()
  • glTexImage2D()
  • glTexSubImage1D()
  • glTexSubImage2D()
  • glTexParameter()

the whole friend group, honestly 🫶

Copyright © 1991-2006 Silicon Graphics, Inc. Copyright © 2012-2014 Khronos Group. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.

Copyright © 2012-2014 Khronos Group

and that's the page, bestie ✨ sign-off time: the source line up top was literally [FIXME: source] (yes, an actual FIXME, we love a placeholder moment 🙈) and this whole thing was dated 08/09/2021. catch you on the next manpage 💜🦋🎀

📦 where this page comes from