GLTEXGEN(3G)

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

💅 GLTEXGEN(3G) — bestie's guide to texture coordinate generation 💅

okay so welcome to glTexGen, aka the little fam of functions that control the generation of texture coordinates. yes there are SIX of them and yes they're all basically the same function wearing different outfits. come sit with me 🫶

✨ NAME ✨

glTexGend, glTexGenf, glTexGeni, glTexGendv, glTexGenfv, glTexGeniv — control the generation of texture coordinates. that's it. that's the whole vibe. 💖

📜 C SPECIFICATION 📜

the "scalar" girlies first (one value, no pointer, living simple):

void glTexGend( GLenum coord,
                GLenum pname,
                GLdouble param )
void glTexGenf( GLenum coord,
                GLenum pname,
                GLfloat param )
void glTexGeni( GLenum coord,
                GLenum pname,
                GLint param )

🌸 PARAMETERS 🌸

  • coord — which texture coordinate we're talking about, bestie. has to be one of GL_S, GL_T, GL_R, or GL_Q. no substitutions, this is not a build-your-own-coordinate situation.
  • pname — the symbolic name of the texture-coordinate generation function. has to be GL_TEXTURE_GEN_MODE. like, must.
  • param — a single-valued texture generation parameter, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP. pick one, queen.

📜 C SPECIFICATION (the vector edition) 📜

and now the pointer girlies, who brought their whole friend group (an array):

void glTexGendv( GLenum coord,
                 GLenum pname,
                 const GLdouble *params )
void glTexGenfv( GLenum coord,
                 GLenum pname,
                 const GLfloat *params )
void glTexGeniv( GLenum coord,
                 GLenum pname,
                 const GLint *params )

🌸 PARAMETERS 🌸

  • coord — same as before, the texture coordinate, and it must be one of GL_S, GL_T, GL_R, or GL_Q.
  • pname — the symbolic name of the texture-coordinate generation function or the function parameters. this time it must be GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE. yes, three options now, we're fancy.
  • params — a pointer to an array of texture generation parameters. if pname is GL_TEXTURE_GEN_MODE, the array has to hold a single symbolic constant — one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP. otherwise, params holds the coefficients for the texture-coordinate generation function named by pname. iykyk. 💅

💖 DESCRIPTION 💖

glTexGen either picks a texture-coordinate generation function or hands over the coefficients for one of them. so basically it's the "choose your fighter" screen for texture coords.

  • coord names one of the (s, t, r, q) texture coordinates, and it has to be one of GL_S, GL_T, GL_R, or GL_Q.
  • pname has to be one of three symbolic constants: GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE.
  • if pname is GL_TEXTURE_GEN_MODE, then params picks a mode: GL_OBJECT_LINEAR, GL_EYE_LINEAR, or GL_SPHERE_MAP.
  • if pname is either GL_OBJECT_PLANE or GL_EYE_PLANE, then params holds the coefficients for the matching texture generation function.

🦋 the GL_OBJECT_LINEAR era 🦋

if the texture generation function is GL_OBJECT_LINEAR, we use this function:

                                g=p1xo+p2yo+p3zo+p4wo

where g is the value computed for the coordinate named in coord, p1, p2, p3, and p4 are the four values you passed in params, and xo, yo, zo, and wo are the object coordinates of the vertex. ✨

and like, this is genuinely useful, not just theory — you can texture-map terrain using sea level as a reference plane (defined by p1, p2, p3, and p4). the altitude of a terrain vertex gets computed by the GL_OBJECT_LINEAR coordinate generation function as its distance from sea level; then that altitude indexes the texture image so you can slap white snow onto peaks and green grass onto foothills. it's giving mountain range 🏔️

👁️ the GL_EYE_LINEAR era 👁️

if the texture generation function is GL_EYE_LINEAR, we use this function:

                                g=p1xe+p2ye+p3ze+p4we

where

                               (p1p2p3p4)=(p1p2p3p4)M−1

and xe, ye, ze, and we are the eye coordinates of the vertex, p1, p2, p3, and p4 are the values supplied in params, and M is the modelview matrix when glTexGen is invoked.

⚠️ bestie listen — if M is poorly conditioned or singular, the texture coordinates generated by the resulting function may be inaccurate or undefined. no cap. that's a real "your texture is going to look cursed and nobody can help you" situation. 💀

note that the values in params define a reference plane in eye coordinates. and here's the sneaky part: the modelview matrix that gets applied to them may not be the same one in effect when the polygon vertices are transformed. this function establishes a field of texture coordinates that can produce dynamic contour lines on moving objects. main character energy, honestly. 👑

🎀 the GL_SPHERE_MAP era 🎀

if pname is GL_SPHERE_MAP and coord is either GL_S or GL_T, then the s and t texture coordinates are generated as follows:

let u be the unit vector pointing from the origin to the polygon vertex (in eye coordinates). let n sup prime be the current normal, after transformation to eye coordinates. let

                                     f=(fxfyfz)T

be the reflection vector such that

                                     f=u−2n′n′Tu

finally, let m=2√fx+fy+(fz+1)2. then the values assigned to the s and t texture coordinates are

                                        s=__+_

                                        t=__+_

(okay yes that last one looks like the math got ate in the photocopier but that's literally what the page says, so i'm passing it to you exactly as it came. 🫠)

🫶 turning it on and off 🫶

to enable or disable a texture-coordinate generation function, call glEnable or glDisable with one of the symbolic texture-coordinate names — GL_TEXTURE_GEN_S, GL_TEXTURE_GEN_T, GL_TEXTURE_GEN_R, or GL_TEXTURE_GEN_Q — as the argument.

  • when enabled, the specified texture coordinate is computed according to the generating function associated with that coordinate.
  • when disabled, subsequent vertices just take the specified texture coordinate from the current set of texture coordinates. simple. comfy. 🍓

and the defaults, because everyone wants to know the starting outfit:

  • initially, all texture generation functions are set to GL_EYE_LINEAR and are disabled.
  • both s plane equations are (1, 0, 0, 0).
  • both t plane equations are (0, 1, 0, 0).
  • all r and q plane equations are (0, 0, 0, 0).

🌈 the multitexture note 🌈

when the GL_ARB_multitexture extension is supported, glTexGen sets the texture generation parameters for the currently active texture unit, selected with glActiveTextureARB. so if your textures are acting mysterious, check which unit is actually active. 🙈

🔥 ERRORS 🔥

  • GL_INVALID_ENUM is generated when coord or pname is not an accepted defined value, or when pname is GL_TEXTURE_GEN_MODE and params is not an accepted defined value.
  • GL_INVALID_ENUM is generated when pname is GL_TEXTURE_GEN_MODE, params is GL_SPHERE_MAP, and coord is either GL_R or GL_Q.
  • GL_INVALID_OPERATION is generated if glTexGen is executed between the execution of glBegin and the corresponding execution of glEnd.
💀 the last one is the classic trap. do NOT call this between glBegin and glEnd. the GL will simply say no and you will be sad.

⭐ ASSOCIATED GETS ⭐

like, if you wanna read back what you set:

  • glGetTexGen
  • glIsEnabled with argument GL_TEXTURE_GEN_S
  • glIsEnabled with argument GL_TEXTURE_GEN_T
  • glIsEnabled with argument GL_TEXTURE_GEN_R
  • glIsEnabled with argument GL_TEXTURE_GEN_Q

🌸 SEE ALSO 🌸

go read these next, they're all in the group chat:

glActiveTextureARB(3G), glCopyPixels(3G), glCopyTexImage2D(3G), glCopyTexSubImage1D(3G), glCopyTexSubImage2D(3G), glCopyTexSubImage3D(3G), glTexEnv(3G), glTexImage1D(3G), glTexImage2D(3G), glTexImage3D(3G), glTexParameter(3G), glTexSubImage1D(3G), glTexSubImage2D(3G), glTexSubImage3D(3G)

and that's the whole page, bestie 🎀 this was GLTEXGEN(3G) from the 3G manual, and that's the sign-off — go forth and generate some coordinates, you absolute icon. periodt. 💅✨🦋

📦 where this page comes from