GLHISTOGRAM(3G)

✨ glHistogram — define histogram table ✨

okay bestie, welcome to glHistogram, a page from section 3G of the manual (that's the OpenGL-adjacent girlies 💅). She's short, she's specific, and she's about to redefine your histogram table. let's go 🦋

---

📜 C SPECIFICATION

void glHistogram( GLenum target,
                  GLsizei width,
                  GLenum internalformat,
                  GLboolean sink )

---

🎀 PARAMETERS

• target — the histogram whose parameters we're setting. literally has to be one of GL_HISTOGRAM or GL_PROXY_HISTOGRAM, no other options bestie.
• width — how many entries are in the histogram table. must be a power of 2. that's the vibe check, and it is not optional 💀
• internalformat — the of entries in the histogram table. (no bestie, the blank is in the original, I am not making that up, the source really did just leave a hole there 😭 not me being the one to report it faithfully.) must be one of 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_R3_G3_B2, GL_RGB, 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.
• sink — if it's GL_TRUE, the pixels get consumed by the histogramming process — no drawing, no texture loading, they're gone, they ate and they left no crumbs 🍽️. if it's GL_FALSE, the pixels move on to the minmax process after histogramming like nothing happened.

---

💖 DESCRIPTION

when GL_HISTOGRAM is enabled, RGBA color components get converted into histogram table indices by clamping them to the range [0,1], multiplying by the width of the histogram table, and rounding to the nearest integer. then the table entries those RGBA indices picked out get incremented. (and if the internal of the histogram table includes luminance — same mystery blank, same energy 🙈 — then the index derived from the R color component decides which luminance table entry gets incremented.) if a histogram table entry gets incremented past its maximum value, its value becomes undefined. that is not an error. it's just chaos. periodt.

histogramming only happens for RGBA pixels (though those pixels might have started out as color indices and gotten converted to RGBA by index table lookup). you turn it on with glEnable and off with glDisable.

when target is GL_HISTOGRAM, glHistogram redefines the current histogram table so it has width entries of the specified by internalformat. the entries are indexed 0 through width−1, and every single entry is initialized to zero. whatever was in the previous histogram table, if anything was, is lost 💀. and if sink is GL_TRUE, pixels get discarded after histogramming — no further processing of those pixels happens at all, and no drawing, texture loading, or pixel readback will result. they're just gone, bestie.

when target is GL_PROXY_HISTOGRAM, glHistogram computes all the state information as if the histogram table were about to be redefined, but doesn't actually define the new table. sneaky. if the requested histogram table is too big for anyone to support, the state information gets set to zero. it's basically a vibe check you can run ahead of time to find out whether a histogram table with those parameters can even be supported 🔮

---

📌 NOTES

glHistogram is only present if GL_ARB_imaging comes back when glGetString is called with an argument of GL_EXTENSIONS. so check first, bestie.

---

🚨 ERRORS

• GL_INVALID_ENUM gets generated if target isn't one of the allowable values.
• GL_INVALID_VALUE gets generated if width is less than zero, or is not a power of 2.
• GL_INVALID_ENUM gets generated if internalformat isn't one of the allowable values.
• GL_TABLE_TOO_LARGE gets generated if target is GL_HISTOGRAM and the histogram table you specified is too large for the implementation. she simply cannot hold all that 👑
• GL_INVALID_OPERATION gets generated if glHistogram gets executed between the execution of glBegin and the corresponding execution of glEnd. do not do that. that's the rule.

---

🔍 ASSOCIATED GETS

• glGetHistogramParameter

---

🌈 SEE ALSO

• glGetHistogram(3G)
• glResetHistogram(3G)

---

okay that's the whole page, you ate it 💅 the footer of this one is just GLHISTOGRAM(3G) on its own line — no source, no version, no date, that's all she gave us — so that's the sign-off: GLHISTOGRAM(3G), that's it, that's the whole outro 🫶✨