GLSEPARABLEFILTER2D(3G)

📦 version 1.1, in centos-stream 9, fedora 43, fedora 44

💖 GLSEPARABLEFILTER2D 💖

bestie. welcome to the 3G manual section, the OpenGL zone, and today's main character is glSeparableFilter2D. it's giving "define a separable two-dimensional convolution filter" and honestly? obsessed. let's get into it 🫶

✨ NAME ✨

glSeparableFilter2D — define a separable two-dimensional convolution filter. that's it, that's the whole vibe. 🎀

🌸 C SPECIFICATION 🌸

void glSeparableFilter2D( GLenum target,
                          GLenum internalformat,
                          GLsizei width,
                          GLsizei height,
                          GLenum format,
                          GLenum type,
                          const GLvoid *row,
                          const GLvoid *column )

🦋 PARAMETERS 🦋

okay so these are the eight things you hand over, and each one has opinions:

  • target — must be GL_SEPARABLE_2D. like, that's the only option, it's not a choose-your-own-adventure 💅
  • internalformat — the internal format of the convolution filter kernel. the allowable values are 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_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. yes that's a lot, no i will not be abbreviating it, we respect completeness in this house ✨
  • width — how many elements live in the pixel array that row points at. (a.k.a. the width of the separable filter kernel, bestie.)
  • height — how many elements live in the pixel array that column points at. (a.k.a. the height of the separable filter kernel. see the pattern? 👑)
  • format — the format of the pixel data in row and column. allowable values: GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_BGR, GL_RGBA, GL_BGRA, GL_INTENSITY, GL_LUMINANCE, and GL_LUMINANCE_ALPHA.
  • type — the type of the pixel data in row and column. these are the accepted symbolic constants: 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.
  • row — pointer to a one-dimensional array of pixel data that gets processed to build the row filter kernel.
  • column — pointer to a one-dimensional array of pixel data that gets processed to build the column filter kernel.

💜 DESCRIPTION 💜

okay so the lore: glSeparableFilter2D builds a two-dimensional separable convolution filter kernel out of two arrays of pixels. two arrays, one kernel, so efficient, we love her 😭

the pixel arrays specified by (width, format, type, row) and (height, format, type, column) get processed exactly as if they had been passed to glDrawPixels — with one exception, bestie: processing stops after the final expansion to RGBA is done. no further, we're done there. 🛑

next up, the R, G, B, and A components of all pixels in both arrays get:

  1. scaled by the four separable 2D GL_CONVOLUTION_FILTER_SCALE parameters, and
  2. biased by the four separable 2D GL_CONVOLUTION_FILTER_BIAS parameters.

(the scale and bias parameters are set by glConvolutionParameter using the GL_SEPARABLE_2D target and the names GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS. the parameters themselves are vectors of four values that are applied to red, green, blue, and alpha, in that order. iykyk.) 🧚

and here's the spicy bit: the R, G, B, and A values are not clamped to [0,1] at any time during this process. not once. no cap. 🫣

each pixel is then converted to the internal format specified by internalformat. this conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). the mapping is as follows — the columns are Internal Format, Red, Green, Blue, Alpha, Luminance, Intensity, and here's every row:

  • GL_LUMINANCE — Luminance = R
  • GL_LUMINANCE_ALPHA — Alpha = A, Luminance = R
  • GL_INTENSITY — Intensity = R
  • GL_RGB — Red = R, Green = G, Blue = B
  • GL_RGBA — Red = R, Green = G, Blue = B, Alpha = A

the red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in floating-point rather than integer. 💀

they form two one-dimensional filter kernel images. here's how they're indexed:

  • the row image is indexed by coordinate i, starting at zero and increasing from left to right. each location in the row image is derived from element i of row.
  • the column image is indexed by coordinate j, starting at zero and increasing from bottom to top. each location in the column image is derived from element j of column.

and one more thing before you go, bestie — 📢 note that after a convolution is performed, the resulting color components are also scaled by their corresponding GL_POST_CONVOLUTION_c_SCALE parameters and biased by their corresponding GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values RED, GREEN, BLUE, and ALPHA). these parameters are set by glPixelTransfer. so many parameters, so little time 🌈

⭐ NOTES ⭐

glSeparableFilter2D is present only if GL_ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS. no GL_ARB_imaging? no function. vibe check failed, unfortunately 🙈

💀 ERRORS 💀

buckle up, there are a bunch, and every single one is here because we do not skip:

  • GL_INVALID_ENUM is generated if target is not GL_SEPARABLE_2D.
  • GL_INVALID_ENUM is generated if internalformat is not one of the allowable values.
  • GL_INVALID_VALUE is generated if width is less than zero or greater than the maximum supported value. this value may be queried with glGetConvolutionParameter using target GL_SEPARABLE_2D and name GL_MAX_CONVOLUTION_WIDTH.
  • GL_INVALID_VALUE is generated if height is less than zero or greater than the maximum supported value. this value may be queried with glGetConvolutionParameter using target GL_SEPARABLE_2D and name GL_MAX_CONVOLUTION_HEIGHT.
  • GL_INVALID_ENUM is generated if format is not one of the allowable values.
  • GL_INVALID_ENUM is generated if type is not one of the allowable values.
  • GL_INVALID_OPERATION is generated if glSeparableFilter2D is executed between the execution of glBegin and the corresponding execution of glEnd. do not do this, bestie, that's the forbidden sandwich 🥪
  • GL_INVALID_OPERATION is generated if height 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.
  • GL_INVALID_OPERATION is generated if height 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.

🔥 ASSOCIATED GETS 🔥

  • glGetConvolutionParameter
  • glGetSeparableFilter

🌈 SEE ALSO 🌈

  • glConvolutionFilter1D(3G)
  • glConvolutionFilter2D(3G)
  • glConvolutionParameter(3G)
  • glPixelTransfer(3G)

and that's the whole page, bestie 💅 the footer of this iconic document just says GLSEPARABLEFILTER2D(3G) all over again — same manual section, same 3G energy, no date or version drama, just the name stamped twice like a little signature. slay, ate, periodt. 🎀✨🦋

📦 where this page comes from