GLUBUILD1DMIPMAPS(3G)

💖 NAME 💖

okay so bestie, welcome to the 3G manual, GLU section. this page is all about gluBuild1DMipmaps, and what it does is builds a one-dimensional mipmap. that's the whole job. iconic behavior, honestly. ✨

---

🌸 C SPECIFICATION 🌸

GLint gluBuild1DMipmaps( GLenum target,
                         GLint internalFormat,
                         GLsizei width,
                         GLenum format,
                         GLenum type,
                         const void *data )

like, six arguments. it returns a GLint. she's got a lot going on but we're gonna get through it together 🫶

---

🎀 PARAMETERS 🎀

• target — which target texture we're even talking about. must be GL_TEXTURE_1D. that's it, that's the only option, no cap.
• internalFormat — this one is the internal storage of the texture image, and it's the messy one, so listen up. the most current version of the SGI implementation of GLU does not check this value for validity before passing it on to the underlying OpenGL implementation. and a value that is not accepted by the OpenGL implementation will lead to an OpenGL error. why would they do that? because the benefit of not checking this value at the GLU level is that OpenGL extensions can add new internal texture formats without requiring a revision of the GLU implementation. slay, honestly. but — and this is the plot twist — older implementations of GLU do check this value and raise a GLU error if it is not 1, 2, 3, or 4 or one of these symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, 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, or GL_RGBA16.
• width — the width, in pixels, of the texture image. yes bestie, in pixels. 🦋
• format — specifies the format of the pixel data. has to be one of GL_COLOR_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR, GL_BGRA, GL_LUMINANCE, GL_LUMINANCE_ALPHA.
• type — the data type for data. must be one of 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, or GL_UNSIGNED_INT_2_10_10_10_REV. 💅
• data — a pointer to the image data in memory. just vibes and bytes.

---

✨ DESCRIPTION ✨

gluBuild1DMipmaps builds a series of prefiltered one-dimensional texture maps of decreasing resolutions called a mipmap. and what's a mipmap for, you ask? it's used for the antialiasing of texture mapped primitives. so like, smooth edges. very demure. 🌈

a return value of zero means success — otherwise you get a GLU error code back (go check gluErrorString). 😭

so here's the pipeline, step by step, and it's giving main character energy:

1. first, the width of data gets checked to see if it's a power of 2. if it's not, a copy of data is scaled up or down to the nearest power of 2. (and if width is exactly between powers of 2, then the copy of data will scale upwards.) this copy is what gets used for all the subsequent mipmapping operations described below. for example: if width is 57, then a copy of data scales up to 64 before mipmapping takes place. math girlies rise up 🧚
2. then, proxy textures (see glTexImage1D) are used to figure out if the implementation can even fit the requested texture. if not, width is continually halved until it fits. we love a flexible queen.
3. next, a series of mipmap levels is built by decimating a copy of data in half until size 1×1 is reached. at each level, every texel in the halved mipmap level is an average of the corresponding two texels in the larger mipmap level. that's the whole averaging situation, that's the vibe. 🍓
4. glTexImage1D is called to load each of these mipmap levels. level 0 is a copy of data. the highest level is log2(width). for example, if width is 64 and the implementation can store a texture of this size, these mipmap levels get built: 64×1, 32×1, 16×1, 8×1, 4×1, 2×1 and 1×1. those correspond to levels 0 through 6, respectively. so many little rectangles, obsessed. 💜

see the glTexImage1D reference page for a description of the acceptable values for the type parameter. see the glDrawPixels reference page for a description of the acceptable values for the data parameter. iykyk 👑

---

⭐ NOTES ⭐

okay important side note: there is no direct way of querying the maximum level. rude, i know. but you can derive it indirectly via glGetTexLevelParameter. here's the trick:

1. first, query for the width actually used at level 0. (the width may not be equal to width, since proxy textures might have scaled it to fit the implementation. she does what she wants.)
2. then the maximum level can be derived from the formula log2(width).

and one more thing bestie, format/type tea ☕: the formats GL_BGR, and GL_BGRA, and the 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 only available if the GL version is 1.2 or greater, and if the GLU version is 1.3 or greater. so if you're on something ancient, that's a you problem, not a me problem 🙈

---

💀 ERRORS 💀

bestie, if you hit one of these, that's a you problem — but at least now you know exactly which one. read carefully, the mismatches are sneaky.

• GLU_INVALID_VALUE is returned if width is < 1. (yes, zero is not a width. zero is a concept.)
• GLU_INVALID_ENUM is returned if format or type are not legal.
• GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_BYTE_3_3_2 or GL_UNSIGNED_BYTE_2_3_3_REV and format is not GL_RGB.
• GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_SHORT_5_6_5 or GL_UNSIGNED_SHORT_5_6_5_REV and format is not GL_RGB.
• GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_SHORT_4_4_4_4 or GL_UNSIGNED_SHORT_4_4_4_4_REV and format is neither GL_RGBA nor GL_BGRA.
• GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_SHORT_5_5_5_1 or GL_UNSIGNED_SHORT_1_5_5_5_REV and format is neither GL_RGBA nor GL_BGRA.
• GLU_INVALID_OPERATION is returned if type is GL_UNSIGNED_INT_8_8_8_8 or GL_UNSIGNED_INT_8_8_8_8_REV and format is neither GL_RGBA nor GL_BGRA.
• GLU_INVALID_OPERATION is returned if type is 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.

---

🦋 SEE ALSO 🦋

glDrawPixels(3G), glTexImage1D(3G), glTexImage2D(3G), glTexImage3D(3G), gluBuild2DMipmaps(3G), gluBuild3DMipmaps(3G), gluErrorString(3G), glGetTexImage(3G), glGetTexLevelParameter(3G), gluBuild1DMipmapLevels(3G), gluBuild2DMipmapLevels(3G), gluBuild3DMipmapLevels(3G)

---

and that's the page, bestie 🫶 this one's signed off as GLUBUILD1DMIPMAPS(3G), straight out of the 3G GLU manual — go build some mipmaps, you absolute icon 👑💅✨