GLTEXSUBIMAGE1D(3G)

📦 version 24.3.3, in opensuse-leap 16.0

🌸 NAME 🌸

glTexSubImage1D — bestie's guide to specifying a one-dimensional texture subimage ✨

(yes it's from the GLTEXSUBIMAGE1D(3G) manual, section 3G, we love a GL era icon 💅)

🎀 C SPECIFICATION 🎀

void glTexSubImage1D( GLenum target,
                      GLint level,
                      GLint xoffset,
                      GLsizei width,
                      GLenum format,
                      GLenum type,
                      const GLvoid *pixels )

no cap, that's the whole signature, copy it exactly please 🙏

💖 PARAMETERS 💖

  • target — which texture we're targeting, okurr. Has to be GL_TEXTURE_1D. No other options, she's picky.
  • level — the level-of-detail number, i.e. which mipmap floor we're on. Level 0 is the base image level. Level n is the *n*th mipmap reduction image. lowkey a whole elevator system 🛗
  • xoffset — a texel offset in the x direction, inside the texture array. it's giving "where do I start" energy.
  • width — how wide the texture subimage is. the girlies love a width.
  • format — specifies the ___ of the pixel data (bestie the original manpage literally has a blank word here 😭 but it's the format, iykyk). accepted symbolic values: GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_BGR, GL_RGBA, GL_BGRA, GL_LUMINANCE, and GL_LUMINANCE_ALPHA. that's the whole roster, no substitutions ✨
  • type — the data type of the pixel data. accepted values: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and GL_UNSIGNED_INT_2_10_10_10_REV. yes that's all of them, I counted twice 🫶
  • pixels — a pointer to the image data in memory. just a lil pointer, doing its best 💜

🦋 DESCRIPTION 🦋

So texturing maps a portion of a specified texture image onto each graphical primitive that has texturing enabled. iconic behavior honestly. To enable or disable one-dimensional texturing, you call glEnable and glDisable with the argument GL_TEXTURE_1D. that's the on/off switch bestie 🌈

glTexSubImage1D redefines a contiguous subregion of an existing one-dimensional texture image. the texels that pixels points to replace the portion of the existing texture array with x indices xoffset and xoffset+width−1, inclusive. ⭐

⚠️ This region may not include any texels outside the range of the texture array as it was originally specified. stay in your lane, subimage 💀

It is not an error to specify a subtexture with width of 0 — but such a specification has no effect. so like, it's legal, it just does nothing. relatable honestly 🙈

✨ NOTES ✨

  • glTexSubImage1D is available only if the GL version is 1.1 or greater. old-GL girlies stay home 👑
  • Texturing has no effect in color index mode. periodt.
  • glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels. same energy, same pipeline 💫
  • Formats GL_BGR, and GL_BGRA and types GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and GL_UNSIGNED_INT_2_10_10_10_REV are available only if the GL version is 1.2 or greater. ✨ the glow-up tier.
  • When the GL_ARB_multitexture extension is supported, glTexSubImage1D specifies a one-dimensional sub texture for the current texture unit, specified with glActiveTextureARB. main character texture unit energy 👑
  • When the GL_ARB_imaging extension is supported, the RGBA components specified in pixels may be processed by the imaging pipeline. See glTexImage1D for specific details. go read that one bestie, I'm not spoiling it 🧚

🔥 ERRORS 🔥

  • GL_INVALID_ENUM is generated if target is not one of the allowable values. wrong target, girl 💀
  • GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage1D operation. you can't sub-image what was never imaged, babe 😭
  • GL_INVALID_VALUE is generated if level is less than 0. no negative floors, we go up only 🦋
  • GL_INVALID_VALUE may be generated if level is greater than log2max, where max is the returned value of GL_MAX_TEXTURE_SIZE. note the may — it's giving "depends on the implementation" 🙈
  • GL_INVALID_VALUE is generated if xoffset<−b, or if (xoffset+width)>(w−b), where w is the GL_TEXTURE_WIDTH, and b is the width of the GL_TEXTURE_BORDER of the texture image being modified. note that w includes twice the border width. the border math is real, respect it 🎀
  • GL_INVALID_VALUE is generated if width is less than 0. (width of 0 is fine, we covered that, but negative? jail. 💅)
  • GL_INVALID_ENUM is generated if format is not an accepted constant. check the list above, bestie 💖
  • GL_INVALID_ENUM is generated if type is not a type constant. same vibe check 🫶
  • GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX. they're a package deal, no cap.
  • GL_INVALID_OPERATION is generated if glTexSubImage1D is executed between the execution of glBegin and the corresponding execution of glEnd. do not do this inside a begin/end block, I'm begging 😭
  • GL_INVALID_OPERATION is generated if type is one of GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and format is not GL_RGB. those packed types only fw GL_RGB ⭐
  • GL_INVALID_OPERATION is generated if type is one of GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and format is neither GL_RGBA nor GL_BGRA. four-channel types, four-channel formats, matching outfits only 👗✨

🌈 ASSOCIATED GETS 🌈

  • glGetTexImage
  • glIsEnabled with argument GL_TEXTURE_1D

💜 SEE ALSO 💜

glActiveTextureARB(3G), glCopyTexImage1D(3G), glCopyTexImage2D(3G), glCopyTexSubImage1D(3G), glCopyTexSubImage2D(3G), glCopyTexSubImage3D(3G), glDrawPixels(3G), glPixelStore(3G), glPixelTransfer(3G), glTexEnv(3G), glTexGen(3G), glTexImage1D(3G), glTexImage2D(3G), glTexImage3D(3G), glTexParameter(3G), glTexSubImage2D(3G), glTexSubImage3D(3G)

the whole friend group, go say hi 🫶🎀

okay that's the whole page bestie, every flag, every constant, every error, nothing skipped, we ate 💅✨

this cutie is from the GLTEXSUBIMAGE1D(3G) page (section 3G) — no date on the footer, just the page name, so that's all you're getting from me 🌸 mwah 💖

📦 where this page comes from