vpClassifyVolume(3)

💖 vpClassifyVolume 💖

okay bestie, welcome to section 3 of the Library Functions Manual — this is the page all about vpClassifyVolume and its ride-or-die destructor vpDestroyClassifiedVolume. it's giving "make my volume render fast" energy and honestly? iconic. ✨

---

🌸 NAME 🌸

vpClassifyVolume, vpDestroyClassifiedVolume — create/destroy a preclassified volume for fast rendering 🫶

---

🎀 SYNOPSIS 🎀

#include <volpack.h>

vpResult
vpClassifyVolume(vpc)
    vpContext *vpc;

vpResult
vpDestroyClassifyVolume(vpc)
    vpContext *vpc;

---

🦋 ARGUMENTS 🦋

• vpc — the VolPack context you got from vpCreateContext. that's it. that's the whole argument list, she's low maintenance 💅

---

✨ DESCRIPTION ✨

so like, vpClassifyVolume is the girl who does the actual work: she computes a preclassified volume for the fast rendering algorithm. and what IS a preclassified volume? it's an internal data structure that's been optimized for rendering speed. no cap, it's the glow-up your voxel data needed. 💖

the timing matters tho, bestie, don't just call her whenever. vpClassifyVolume should be called after a voxel array has been defined — that means vpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField, and vpSetRawVoxels — and after it's been initialized with vpVolumeNormals or a user-defined routine. you also need an opacity transfer function defined with vpSetClassifierTable, and the minimum opacity threshold should be set with the VP_MIN_VOXEL_OPACITY parameter to vpSeti. that's the whole pre-flight checklist, don't skip steps. 🙈

also there are two alternative routines that compute a preclassified volume directly from a 3D scalar array or a sequence of scalar scanlines, specifically so you can dodge allocating a huge 3D voxel array. go look at vpClassifyScalars(3) and vpClassifyScanline(3) if that's your situation. 🌈

okay so what does she actually do? vpClassifyVolume classifies and processes the data in the voxel array and creates a separate preclassified volume. the preclassified data is stored in a run-length encoded format, and any voxels whose opacities are less than or equal to the minimum opacity threshold get discarded. bye felicia. 👋

normally, three copies of the preclassified volume are created — one for each of the three principal viewing axis. but if only one or two copies are necessary for the range of viewpoints you need, you can call vpSeti with one or more of these parameters to say which copies you actually want:

• VP_VIEW_X_AXIS
• VP_VIEW_Y_AXIS
• VP_VIEW_Z_AXIS

but listen — using these parameters is not recommended unless swap space is lacking. like, they're there, they work, but the docs said "not recommended" and I'm just the messenger. 😭

if a min-max octree is present in the rendering context (peep vpCreateMinMaxOctree(3)), then it gets used to accelerate the computation of the preclassified volume. and it's genuinely advantageous to create a min-max octree if you're gonna classify the same volume data multiple times, like with different opacity transfer functions. it's the "do it once, reap the rewards" moment. 👑

once vpClassifyVolume is finished, the original voxel array is no longer necessary for rendering — as long as the opacity transfer function and the volume data don't change. and if any changes are made? then the preclassified volume must be explicitly recomputed by calling vpClassifyVolume again. no automatic refresh, bestie, she does not update herself. 🔥

also important: only one preclassified volume may be stored in a rendering context at a time. and calling vpClassifyVolume causes any existing preclassified volume to be destroyed. so, y'know. heads up. 💀

and vpDestroyClassifiedVolume? she destroys the current preclassified volume and frees the associated space. clean exit, very main character. 🧚

---

💅 STATE VARIABLES 💅

wanna know stuff about the current preclassified volume? you can retrieve info with these state variable codes (check vpGeti(3)):

• VP_VIEW_X_SIZE
• VP_VIEW_Y_SIZE
• VP_VIEW_Z_SIZE
• VP_VIEW_X_AXIS
• VP_VIEW_Y_AXIS
• VP_VIEW_Z_AXIS

---

💀 ERRORS 💀

the normal return value is VP_OK. and the following error return values are possible — each one is a different flavor of "girl, something's off":

• VPERROR_BAD_VOXEL — the voxel size or the voxel fields have not been specified, or have been incorrectly specified. 🍓
• VPERROR_BAD_VOLUME — the volume array or volume dimensions have not been specified, or the size of the volume array does not match the volume dimensions.
• VPERROR_BAD_CLASSIFIER — the opacity transfer function tables have invalid sizes, or are associated with invalid voxel fields, or have been incorrectly specified.

---

⭐ SEE ALSO ⭐

VolPack(3), vpCreateContext(3), vpSetClassifierTable(3), vpClassifyScalars(3), vpClassifyScanline(3)

---

and that's the whole page, bestie! this one came to you courtesy of VolPack, and the page itself is vpClassifyVolume(3). go forth and classify responsibly. 💜✨