vpSetDepthCueing(3)

💖 NAME 💖

okay so bestie, welcome to vpSetDepthCueing — a Library Functions Manual situation from the VolPack crew ✨ and yes it does exactly what it says on the tin: it sets the depth cueing parameters. that's the whole assignment. slay. 💅

---

🎀 SYNOPSIS 🎀

#include <volpack.h>

vpResult
vpSetDepthCueing(vpc, front_factor, density)
    vpContext *vpc;
    double front_factor;
    double density;

---

🌸 ARGUMENTS 🌸

• vpc — the VolPack context you got from vpCreateContext. your whole little universe lives in here 🫶
• front_factor — the depth cueing factor right at the front clipping plane.
• density — the fog density. how thick is the fog, bestie.

---

🦋 DESCRIPTION 🦋

vpSetDepthCueing sets the parameters for depth cueing. and what is depth cueing, you ask? it's a simulated fog 🌫️ that makes the objects in the distance look darker than the stuff in the foreground. very dramatic lighting, very main character energy, no cap.

the important part: depth cueing is independent of the shading method. it works with lookup-table shading and with callback-function shading. also, it is not stored in the shading lookup table — it is always applied to voxels at rendering time. periodt.

so front_factor is the transparency of the fog at the front clipping plane (go peek at vpWindow(3) or vpWindowPHIGS(3) for that one). it must be a positive number, and it's usually less than 1.0 — although you can go bigger than that if you want to brighten the foreground. live your truth ✨

density controls the "density" of the fog. crank it up and objects recede into darkness over a shorter distance. the equation for the transparency of the fog at a particular voxel is:

T = front_factor * exp(-density * depth)

where depth is 0 at the front clipping plane and 1 at the back clipping plane. each voxel color component gets multiplied by the fog transparency during rendering. math ate, honestly 🧮

by default, depth cueing is not enabled. to turn it on, call vpEnable with the VP_DEPTH_CUE option. don't forget, bestie, or you'll be staring at an unfogged render wondering why nothing is happening 💀

depth cueing is implemented using an internal lookup table (completely unrelated to the shading lookup table, they're not friends, they don't text). there are several VolPack state variables that affect the depth cueing table, although they should not usually be changed. the table holds depth cueing factors as a function of depth. the table must contain entries for depths in the range 0.0-1.0, and possibly for negative depths depending upon the current viewing parameters (the reason for this is beyond the scope of a man page — iykyk 🙈).

the VP_DEPTH_CUE_QUANTIZATION variable (which you can set by calling vpSetd) determines the depth difference between two adjacent entries in the depth cueing table. for instance, the default quantization of 1/255 specifies that each entry in the table represents 1/255 times the distance between the front and back clipping planes. reducing the quantization increases the size and accuracy of the depth cueing table. more accuracy, more table, that's the tradeoff babe ⚖️

normally the depth cueing table is resized and recomputed only when necessary. recomputation may be required if the viewpoint changes, increasing the range of voxel depths that are encountered (recall that there is no lower bound on the depth). you can use vpGeti with the VP_DEPTH_CUE_TABLE_SIZE state variable code to get the current number of table entries. you can also set the value of VP_DEPTH_CUE_TABLE_SIZE_HINT (using vpSeti) to suggest a size for the table. this might be desirable if you plan to compute an animation loop and want to ensure that the depth cueing table does not need to be recomputed in the middle of the sequence. however — and listen — since recomputing the table is relatively inexpensive, it should not be necessary to use this option. so like, you can, but you probably don't have to 🎀

---

👑 STATE VARIABLES 👑

you can retrieve info about the current depth cueing properties with these state variable codes (see vpGeti(3)):

• VP_DEPTH_CUE
• VP_DEPTH_CUE_FRONT
• VP_DEPTH_CUE_DENSITY
• VP_DEPTH_CUE_TABLE_SIZE
• VP_DEPTH_CUE_SIZE_HINT
• VP_DEPTH_CUE_QUANTIZATION

---

💀 ERRORS 💀

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

• VPERROR_BAD_VALUE — the value of front_factor is not positive. yeah, it said positive, bestie, we meant it 😭

---

🌈 SEE ALSO 🌈

VolPack(3), vpCreateContext(3), vpSetLookupShader(3)

---

and that's the whole page, babe 🦋 this one came to you straight out of VolPack, filed under vpSetDepthCueing(3) in the Library Functions Manual — go forth and fog up your renders responsibly 💖✨🎀