vpRenderRawVolume(3)

✨ vpRenderRawVolume — the manual page, bestie edition 💖

okay so we're deep in the VolPack library functions manual and today's main character is vpRenderRawVolume(3) (and its twin sister vpRenderClassifiedVolume(3), we love a duo 🫶). buckle up, this one's about rendering a volume and it's giving very much "graphics girlie" energy.

---

🌸 NAME 🌸

vpRenderRawVolume, vpRenderClassifiedVolume — render a volume

like. that's it. that's the whole job. rendering. a volume. iconic.

---

🎀 SYNOPSIS 🎀

#include <volpack.h>

vpResult
vpRenderRawVolume(vpc)
    vpContext *vpc;

vpResult
vpRenderClassifiedVolume(vpc)
    vpContext *vpc;

copy it exactly bestie, no typos, the compiler WILL know 🔥

---

💅 ARGUMENTS 💅

• vpc — your VolPack context, the one you got from vpCreateContext. it's the whole vibe holder, everything lives in here.

---

🦋 DESCRIPTION 🦋

okay so these routines render a volume using the parameters sitting in a rendering context. vpRenderRawVolume renders the data in the current voxel array and drops the result into the current image array. and here's the cute part: if there's an octree hanging out in the context (see vpCreateMinMaxOctree(3)), it gets used to accelerate rendering. speed. ✨

vpRenderClassifiedVolume is literally identical in function, except it renders the current preclassified volume (see vpClassifyVolume(3)) instead of the voxel array — and no, the octree does not get used here. she's independent.

---

which one do i use tho 😭

vpRenderClassifiedVolume is the move when you're rendering the same volume multiple times with the same opacity transfer function. this rendering mode is the fastest. but listen — the opacity transfer function must not change, because the voxel opacities have to be fixed in order to compute a preclassified volume. so like, pick a function and commit, no cap.

vpRenderRawVolume is the move when the volume data or the opacity transfer function changes in between renderings. and if the volume data stays fixed, you should compute a min-max octree to accelerate rendering. rendering is significantly faster with an octree than without it — though ngl, it's still slower than rendering with vpRenderClassifiedVolume. the hierarchy is real.

---

setup era 🌈

before you call these rendering routines, the rendering context has to be initialized to set:

• the volume parameters
• the classification parameters (vpRenderRawVolume only)
• the viewing parameters
• the shading and lighting parameters
• and the image array

see VolPack(3) for a list of the relevant functions. she's got the receipts.

---

the one state variable you actually need to adjust 👑

one important state variable should be adjusted before calling the rendering routines: the maximum opacity threshold. this number is a threshold value for the opacity of an image pixel. if the opacity of the pixel reaches the threshold, then no more voxels are composited into the pixel. bye. done. she's full.

the threshold should be a number slightly less than one (0.95 is a good value). numbers closer to 1.0 result in longer rendering times, but less error. so it's giving tradeoff, it's giving "choose your fighter".

you change the threshold by calling vpSetd with the VP_MAX_RAY_OPACITY option. the default value is 1.0.

---

intermediate image / work buffer lore 🧚

there are two additional state variables you can adjust to set the size of an internal data structure. during rendering, a work buffer called the intermediate image is used to hold temporary results.

the size of this data structure depends on the size of the volume and the current view transformation matrix. over the course of an animation sequence, the intermediate image may have to be enlarged multiple times, resulting in many calls to the memory allocator. normally the overhead of reallocating the data structure is negligible and can be ignored — like, it's fine, don't stress.

however, this overhead can be eliminated by specifying hints for the maximum size of the intermediate image. the data structure will then be allocated once, and will never be reallocated unless an even larger intermediate image is required. glow up, one and done.

to set the size hints, call vpSeti with the VP_INT_WIDTH_HINT and VP_INT_HEIGHT_HINT state variable codes.

if the viewing transformation does not include any scaling, then the maximum possible size of each dimension of the intermediate image is twice the size of the largest dimension of the volume. to get a more precise bound, the intermediate image size required for rendering a volume with the current viewing parameters can be found by calling vpGeti with the VP_INTERMEDIATE_WIDTH and VP_INTERMEDIATE_HEIGHT state variable codes.

---

💀 ERRORS 💀

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

• VPERROR_BAD_SHADER — the shading lookup tables are sized incorrectly, or one of the voxel fields used to index the tables is invalid, or the number of material types is invalid.
• VPERROR_SINGULAR — one of the current view transformation matrices is singular. 😭
• VPERROR_BAD_VOLUME — the volume size has not been set or is invalid, or there is no volume data.
• VPERROR_BAD_VOXEL — the voxel size or the voxel fields have not been specified or have been incorrectly specified.
• VPERROR_BAD_CLASSIFIER — the opacity transfer function tables have invalid sizes, or are associated with invalid voxel fields, or have been incorrectly specified. (vpRenderRawVolume only)
• VPERROR_BAD_SHADOW — the angle between the shadow light vector and the viewing direction is too large (must be less than 45 degrees). either change the light direction or disable shadows (see vpSetShadowLookupShader).

ngl the error list is giving "check your setup before you check your code" energy. but fr fr, every one of these is a real state problem, not a vibe problem. fix the state.

---

👑 SEE ALSO 👑

VolPack(3), vpCreateContext(3)

---

and that's the page, bestie 🎀 this little drop of wisdom comes to you from the VolPack source, as page vpRenderRawVolume(3) of the Library Functions Manual. go render something gorgeous. slay. periodt. 💖✨