vpSetVoxelSize(3)

💅 vpSetVoxelSize — the volpack.h girlies' guide

ok so bestie, this is vpSetVoxelSize(3) from the Library Functions Manual ✨ it's a VolPack thing, it lives in volpack.h, and it's literally just you telling VolPack how big your voxels are. no cap. let's go 🫶

---

🌸 NAME 🌸

vpSetVoxelSize — define the size of a voxel 💖

---

✨ SYNOPSIS ✨

#include <volpack.h>

vpResult
vpSetVoxelSize(vpc, bytes_per_voxel, num_voxel_fields, num_shade_fields,
        num_classify_fields)
    vpContext *vpc;
    int bytes_per_voxel;
    int num_voxel_fields;
    int num_shade_fields;
    int num_classify_fields;

---

🎀 ARGUMENTS 🎀

• vpc — the VolPack context you got from vpCreateContext. your whole vibe lives in here 👑
• bytes_per_voxel — how big one voxel is, in bytes. that's it, that's the measurement 🦋
• num_voxel_fields — how many fields are chillin' inside a voxel.
• num_shade_fields — how many of those voxel fields get passed as arguments to the shading function. the main character fields, basically ✨
• num_classify_fields — how many voxel fields get passed as arguments to the opacity transfer function. (the function signature in the synopsis calls this one num_classify_fields, but the prose down below keeps calling it num_clsfy_fields — same girl, different nickname, don't let it stress you 💀)

---

💖 DESCRIPTION 💖

So vpSetVoxelSize is the function where you declare the size in bytes and the number of fields in a voxel. And each voxel field? It's exactly like a field in a C struct, except the contents of every field are totally user-defined. you're the author, you're the director, you're the moment 🌈

For setting the actual size and offset of each field, you wanna hit up vpSetVoxelField (that's vpSetVoxelField(3), go read it). And the ordering matters, okay? vpSetVoxelSize needs to be called before vpSetVoxelField, and before literally any function that touches the contents of a voxel. do it first. periodt. 💅

Now here's the tea ☕ — typically some of those voxel fields are arguments to a shading function, and some of them (possibly the same ones, we love overlap) are arguments to an opacity transfer function for classification. The shading fields should come first, i.e. they should have the smallest offsets. Then after them come any fields that are only used for classification. Why tho? because then the classification fields can get stripped off to save space during the precomputation stage of the fast rendering algorithm 🧚 iconic behavior tbh.

The parameter num_shade_fields tells you how many fields — counting from the very first one — must not be stripped off. they stay. they're protected. 🔥

And num_clsfy_fields (the one the synopsis calls num_classify_fields) is the total number of fields used as parameters to the opacity transfer function. These fields don't necessarily have to be contiguous — no need to be all snuggled up next to each other — although any fields that aren't also used for shading should be the last fields in the voxel.

⚠️ heads up bestie: if the call to vpSetVoxelSize succeeds, any existing precomputed volume data structures in the context are destroyed. gone. deleted. so if you had precomputed stuff you cared about... that's a yikes 😭

---

⭐ STATE VARIABLES ⭐

You can pull the current voxel size parameters back out with these state variable codes (peep vpGeti(3) for how): VP_BYTES_PER_VOXEL, VP_VOXEL_FIELD_COUNT, VP_SHADE_FIELD_COUNT, VP_CLASSIFY_FIELD_COUNT. collecting them like pokémon fr fr 🌸

---

💀 ERRORS 💀

The normal return value is VP_OK. the good ending. but these error return values are possible:

• VPERROR_LIMIT_EXCEEDED — the number of voxel fields exceeds the implementation limit. you can bump that limit up by editing volpack.h and recompiling the library. yes, really, that's the move 🔧
• VPERROR_BAD_VALUE — either num_clsfy_fields or num_shade_fields is out of range. one of them is doing too much 🙈

---

👑 SEE ALSO 👑

VolPack(3), vpCreateContext(3), vpSetVoxelField(3) — go read your sisters' pages, iykyk 🦋

---

k that's the whole page bestie, we ate and left no crumbs 💅 this was vpSetVoxelSize(3) from the Library Functions Manual, brought to you by VolPack — mwah, stay hydrated, go set your voxel sizes correctly 🎀✨