vpCreateMinMaxOctree(3)

💖 vpCreateMinMaxOctree — a VolPack moment (section 3, library functions) 💖

okay bestie, so this is the manual page for vpCreateMinMaxOctree(3) and its two ride-or-die friends. no cap, it's a whole trio.

🌸 NAME 🌸

vpCreateMinMaxOctree, vpMinMaxOctreeThreshold, vpDestroyMinMaxOctree — create/destroy a min-max octree for optimized rendering. literally the glow-up your volume rendering was waiting for. ✨

---

🎀 SYNOPSIS 🎀

#include <volpack.h>

vpResult
vpCreateMinMaxOctree(vpc, root_node_size, base_node_size)
    vpContext *vpc;
    int root_node_size, base_node_size;

vpResult
vpMinMaxOctreeThreshold(vpc, param_num, range)
    vpContext *vpc;
    int param_num, range;

vpResult
vpDestroyMinMaxOctree(vpc)
    vpContext *vpc;

---

🦋 ARGUMENTS 🦋

• vpc — the VolPack context, and you get it from vpCreateContext. your main character, basically.
• root_node_size — how many voxels per side live in the top level (aka the biggest nodes) of the octree. not currently used, so don't stress about it bestie.
• base_node_size — voxels per side in the bottom level (the tiniest nodes). must be a power of 2, that's the rule, periodt.
• param_num — the identifying number of one parameter of the opacity transfer function.
• range — the range threshold for one parameter of the opacity transfer function. if an octree node spans a bigger range than this, it gets subdivided. slay.

---

💅 DESCRIPTION 💅

These routines create and destroy a min-max octree — an internal data structure that accelerates classifying and rendering volume data in a 3D voxel array. the octree is a hierarchical structure holding minimum and maximum values for each voxel field. and the best part? it does not duplicate the data in the voxel array. lowkey efficient. it is also not used with preclassified volumes (go check vpClassifyVolume(3) for that vibe).

Before you can create an octree you gotta:

1. declare a 3D voxel array using vpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField and vpSetRawVoxels
2. initialize the parameters for the opacity transfer function by calling vpSetClassifierTable
3. initialize the voxel data in the array

and here's the tea: the lookup tables for the opacity transfer function do not need to be initialized. we love a low-effort step. 💖

Now call vpMinMaxOctreeThreshold once for each parameter of the opacity transfer function. the parameter number is the same number you'd pass to vpClassifierTable. the range argument is a "small" range of values for that parameter — the opacity of a voxel shouldn't vary much for voxels inside this range of parameter space. pick a value too small or too large and you may end up with reduced performance benefit during rendering, which is giving... wasted potential ngl. you can use vpOctreeMask to visualize how effective your various parameter ranges are. also important: you must choose the voxel field associated with each opacity transfer function parameter in advance of creating the octree (by calling vpSetClassiferTable), but the opacity transfer function itself doesn't need to be known, since the lookup tables don't need to be initialized. and in the current implementation, all the parameters must be one or two-byte voxel fields — four-byte fields are not allowed. 🙈

Finally, call vpCreateMinMaxOctree to actually compute the octree. the arguments specify the largest and smallest node size, and you can use these values to trade off storage size of the octree for increased resolution. the octree lives in the rendering context and gets used automatically in subsequent calls to vpClassifyVolume and vpRenderRawVolume. only one octree may be stored in a context at a time, and if an octree already exists when you call vpCreateMinMaxOctree, the old one gets destroyed. out with the old, in with the new. 💀

If the data in the voxel array changes, the min-max octree must be explicitly recomputed by calling vpCreateMinMaxOctree again before the next call to vpClassifyVolume or vpRenderRawVolume. no shortcuts, bestie, it will not update itself.

vpDestroyMinMaxOctree destroys the current min-max octree and frees the associated storage. bye bye, storage. 🫶

---

⭐ STATE VARIABLES ⭐

You can retrieve the current octree parameters with these state variable codes (peep vpGeti(3)):

• VP_CLASSIFY_FIELD_COUNT
• VP_CLASSIFY_FIELDS
• VP_MMOCTREE_THRESHOLDS
• VP_MMOCTREE_SIZE

---

😭 ERRORS 😭

The normal return value for all three functions is VP_OK. iconic behavior.

vpMinMaxOctreeThreshold can return:

• VPERROR_BAD_VALUE — the parameter number is invalid. wrong number, wrong vibe.

vpCreateMinMaxOctree can return:

• VPERROR_BAD_VALUE — the node size arguments are not a power of two.
• VPERROR_BAD_VOXEL — the voxel size or the voxel fields have not been specified or have been incorrectly specified, or the number of parameters to the opacity transfer function has 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 fields specified as parameters to the opacity transfer function are invalid or do not have valid sizes.
• VPERROR_LIMIT_EXCEEDED — the volume is too large, so the maximum size of the octree has been exceeded. change the constant VP_MAX_OCTREE_LEVELS in volpack.h and recompile the VolPack library. that's a whole rebuild, but you got this. 🔥

---

🌈 SEE ALSO 🌈

VolPack(3), vpCreateContext(3), vpClassifyVolume(3), vpOctreeMask(3), vpRenderRawVolume(3)

---

okay that's the whole page, you ate it 💅 this was vpCreateMinMaxOctree(3) straight outta the VolPack library, and if you need it again the name is right there in the title bestie — go forth and octree. 👑✨