vpSetLight(3)

💡 vpSetLight — like, the lighting glow-up page (NAME)

okay bestie, this is vpSetLight(3) from the VolPack library functions manual, and it's literally the function that sets your lighting properties. slay. ✨

📜 SYNOPSIS

#include <volpack.h>

vpResult
vpSetLight(vpc, light_num, property, n0, n1, n2)
    vpContext *vpc;
    int light_num;
    int property;
    double n0, n1, n2;

🎀 ARGUMENTS

• vpc — the VolPack context, and you got it from vpCreateContext. your whole vibe lives in there 💖
• light_num — a constant that picks out one specific light source: VP_LIGHT0, VP_LIGHT1, ..., VP_LIGHT5. pick your fighter 🫶
• property — a constant naming one lighting property, either VP_COLOR or VP_DIRECTION. one at a time, babes.
• n0, n1, n2 — the components. for VP_COLOR these are RGB color components; for VP_DIRECTION they're a direction vector. same three slots, two totally different jobs 🌈

✨ DESCRIPTION ✨

so vpSetLight sets the properties of a light source. and here's the tea: VolPack currently only supports directional light sources. each light is infinitely distant, which means it can be fully characterized by just a direction vector and a color. that's it, that's the whole personality. these lighting properties get used by vpShadeTable to compute the shading lookup table, and that is what gets used to compute a color for each voxel. it's giving pipeline. 💅

to initialize the lighting environment, call vpSetLight twice for each light source you're gonna enable. one call sets the RGB components of the light color (pass the VP_COLOR code as the property parameter), and one call sets the XYZ components of the light direction vector (pass the VP_DIRECTION code as the property parameter). the particular light source is specified with one of the light source codes defined in volpack.h: VP_LIGHT0, VP_LIGHT1, ..., VP_LIGHT5. in the current implementation, at most six light sources may be specified. six. that's the limit, no cap. 🙈

the RGB components of a light color should be numbers in the range 0.0 (zero intensity) to 1.0 (full intensity). for grayscale renderings only the first (red) component is used, and the other components may be set to any legal value. the default is white light (1.0, 1.0, 1.0). clean, classic, iconic. 🤍

the light direction vector points from the light source towards the lit object. it gets transformed by the current contents of the modeling matrix (see vpCurrentMatrix). this is what lets you specify the direction vector in an arbitrary coordinate system — as long as the current modeling matrix properly transforms the vector into world coordinates. the default is the vector (1,1,1). ✨

each light source only contributes to the shading computation if it's enabled by calling vpEnable. by default, VP_LIGHT0 is enabled and all the other lights are disabled. also heads up: the more light sources that are enabled, the longer it takes to precompute the contents of the shading lookup table. more glow = more waiting, bestie 😭

one additional property of the light sources can be set with vpEnable: VP_LIGHT_BOTH_SIDES. with this option enabled, each light source shines in two opposing directions — as if there were two light sources facing each other with opposite direction vectors. and the best part? no additional computation is required when this option is enabled. free real estate 👑

🔍 STATE VARIABLES

you can retrieve info about the current lighting properties with the following state variable codes (see vpGeti(3)): VP_LIGHT_BOTH_SIDES. 💜

💀 ERRORS

the normal return value is VP_OK. the following error return values are possible:

• VPERROR_LIMIT_EXCEEDED — the light number is invalid or exceeds an implementation limit. too many lights, girl.
• VPERROR_SINGULAR — the light direction vector is a zero vector. it's pointing nowhere, which is a problem 😭
• VPERROR_BAD_VALUE — the RGB color components are out of range.
• VPERROR_BAD_OPTION — the property argument is invalid.

👀 SEE ALSO

VolPack(3), vpCreateContext(3), vpSetLookupShader(3), vpShadeTable(3), vpGetLight(3)

fr fr, if the direction vector is zero you get VPERROR_SINGULAR, so don't do that. a light that points at nothing is not main character energy, it's just broken. 🚫

and that's the whole page, bestie!! 🦋 this one came straight out of the VolPack library manual — vpSetLight(3), manual section 3, Library Functions Manual. go forth and light your voxels, you absolute queen 👑💖