vpSetVoxelSize(3)

✨ vpSetVoxelSize(3) ✨

okay bestie, welcome to the VolPack library functions manual, and today's main character is vpSetVoxelSize 💅

---

🌸 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, aka the one you got from vpCreateContext.
• bytes_per_voxel — how big one voxel is, in bytes. that's it, that's the size.
• num_voxel_fields — how many fields live inside a voxel.
• num_shade_fields — how many of those voxel fields get passed as arguments to the shading function.
• num_classify_fields — how many voxel fields get passed as arguments to the opacity transfer function.

---

💖 DESCRIPTION 💖

so vpSetVoxelSize is literally here to define the size in bytes and the number of fields in a voxel. think of each voxel field like a field in a C struct — the contents of each one is user-defined, so you're the boss of what goes in there, no cap.

for setting the size and offset of each individual field, you want the vpSetVoxelField function (vpSetVoxelField(3)). and order matters, bestie: vpSetVoxelSize should be called before vpSetVoxelField and before any functions that access the contents of a voxel. do not skip the queue 🙈

typically, some of the voxel fields get used as arguments to a shading function, and some of them — possibly the same ones — get used as arguments to an opacity transfer function (that's the classification part). the fields used for shading should come first, i.e. they should have the smallest offsets, followed by any fields that are only used for classification. why? because then the classification fields can be stripped off to save space during the precomputation stage for the fast rendering algorithm. the num_shade_fields parameter tells you the number of fields (starting from the first) that must not be stripped off. periodt.

the parameter num_clsfy_fields indicates the total number of fields that are used as parameters to the opacity transfer function. these fields don't necessarily have to be contiguous, although any fields that aren't also used for shading should be the last fields in the voxel. the way that layout saves you space is genuinely iconic ✨

⚠️ heads up: if the call to vpSetVoxelSize succeeds, any existing precomputed volume data structures in the context are destroyed. gone. bye. so know what you're doing 💀

---

⭐ STATE VARIABLES ⭐

you can grab the current voxel size parameters with these state variable codes (peep vpGeti(3) for the how-to): VP_BYTES_PER_VOXEL, VP_VOXEL_FIELD_COUNT, VP_SHADE_FIELD_COUNT, VP_CLASSIFY_FIELD_COUNT.

---

🌈 ERRORS 🌈

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

• VPERROR_LIMIT_EXCEEDED — the number of voxel fields exceeds the implementation limit. you can raise this limit by editing volpack.h and recompiling the library, so it's giving "fixable but effort" 🫶
• VPERROR_BAD_VALUE — either num_clsfy_fields or num_shade_fields is out of range.

---

👑 SEE ALSO 👑

VolPack(3), vpCreateContext(3), vpSetVoxelField(3)

---

and that's the whole vibe check, bestie 🎀 this was vpSetVoxelSize(3) from the VolPack manual — no date on the original page, so we're keeping it timeless, and the source is just VolPack itself. slay, go set some voxel sizes 💜🦋