vpCreateMinMaxOctree(3)

✨ vpCreateMinMaxOctree — from the Library Functions Manual ✨

okay bestie, gather round, we're doing octrees today and it's gonna be so good 💖

🌸 NAME 🌸

vpCreateMinMaxOctree, vpMinMaxOctreeThreshold, vpDestroyMinMaxOctree — the trio that creates and destroys a min-max octree, which is the whole vibe behind optimized rendering 🦋

---

🌈 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 — your VolPack context, the one you got from vpCreateContext. she's the main character here 👑
• root_node_size — how many voxels per side live in the top level (aka the largest nodes) of the octree. not currently used, so like… she's there, she's just not doing anything rn 🙈
• base_node_size — voxels per side in the bottom level (the smallest nodes). must be a power of 2, no cap, that's the rule.
• 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 larger range than this, bestie, it gets subdivided. periodt.

---

🎀 DESCRIPTION 🎀

These routines create and destroy a min-max octree — an internal data structure that speeds up classifying and rendering volume data in a 3D voxel array. it's giving ✨optimization✨. The octree is a hierarchical data structure holding minimum and maximum values for each voxel field. lowkey important: it does not duplicate the data in the voxel array. and heads up — the octree is not used with preclassified volumes (go read vpClassifyVolume(3) for that lore).

So before you can create an octree, you gotta declare a 3D voxel array using vpSetVolumeSize, vpSetVoxelSize, vpSetVoxelField and vpSetRawVoxels, and then initialize the parameters for the opacity transfer function by calling vpSetClassifierTable. Then you initialize the voxel data in the array. 🫶 and no, the lookup tables for the opacity transfer function do not need to be initialized. we're chill like that.

Now, call vpMinMaxOctreeThreshold once for each parameter to the opacity transfer function. The parameter number is literally the same number you'd pass to vpClassifierTable. The range argument specifies a "small" range of values for the corresponding parameter — the opacity of a voxel shouldn't vary much for voxels within this range of parameter space. Choosing a value that's too small or too large may result in a reduced performance benefit during rendering 😭 so choose wisely. You can use the function vpOctreeMask to visualize how effective your various parameter ranges actually are — vibe check your choices fr.

⚠️ note that 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 of the parameters must be one- or two-byte voxel fields. four-byte fields are not allowed. sorry babe 💀

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 — iconic tradeoff behavior. The octree is stored 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. If an octree already exists when vpCreateMinMaxOctree is called, then the old octree is destroyed. out with the old, in with the new 💅

🚨 if the data in the voxel array changes, then the min-max octree must be explicitly recomputed by calling vpCreateMinMaxOctree again before the next call to vpClassifyVolume or vpRenderRawVolume. no skipping this step, bestie.

vpDestroyMinMaxOctree destroys the current min-max octree and frees the associated storage. she's done, she's free, we love a clean exit 🌈

---

⭐ STATE VARIABLES ⭐

The current octree parameters can be retrieved with the following state variable codes (see 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. 🫶

vpMinMaxOctreeThreshold can return the following error value:

• VPERROR_BAD_VALUE — the parameter number is invalid. that number? not it. 🙈

vpCreateMinMaxOctree can return the following error values:

• VPERROR_BAD_VALUE — the node size arguments are not a power of two. we said power of two, babe!!
• 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 doesn't match the volume dimensions. mismatch energy, we hate to see it 😭
• VPERROR_BAD_CLASSIFIER — the fields specified as parameters to the opacity transfer function are invalid or don't have valid sizes.
• VPERROR_LIMIT_EXCEEDED — the volume is too large, so the maximum size of the octree has been exceeded. the fix? change the constant VP_MAX_OCTREE_LEVELS in volpack.h and recompile the VolPack library. literally just go edit the header, you got this 🔥

---

🦋 SEE ALSO 🦋

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

---

okay that's the whole page, bestie, you ate that 💖 this was vpCreateMinMaxOctree(3) from the VolPack source, and that's the sign-off — slay, go build your octree, ily 🎀✨👑