vpSetVoxelField(3)

💖 vpSetVoxelField 💖

okay so bestie, welcome to vpSetVoxelField(3) from the Library Functions Manual — this is the one where we tell VolPack what our voxels actually look like on the inside. she's a function AND a macro, she's booked and busy. ✨

---

🌸 NAME 🌸

vpSetVoxelField, vpFieldOffset — define the size and location of a voxel field

---

🎀 SYNOPSIS 🎀

#include <volpack.h>

vpResult
vpSetVoxelField(vpc, field_num, field_size, field_offset, field_max)
    vpContext *vpc;
    int field_num;
    int field_size;
    int field_offset;
    int field_max;

int
vpFieldOffset(voxel_ptr, field_name)
    vpContext *vpc;
    LITERAL field_name;

---

💅 ARGUMENTS 💅

• vpc — the VolPack context you got from vpCreateContext. your whole world lives in here.
• field_num — which field number you're defining. first field is 0, no cap.
• field_size — how big the field is, in bytes.
• field_offset — how many bytes from the beginning of the voxel to the beginning of the field. it's giving "where does this field start, exactly".
• field_max — the maximum possible value this field could ever hold.
• voxel_ptr — pointer to a C structure that defines the fields in the voxel.
• field_name — the literal name of the voxel field inside that C structure. yes literally the name, iykyk.

---

✨ DESCRIPTION ✨

vpSetVoxelField is your girl for defining the size and location of every single field in a voxel. 💖

So here's the flow, bestie: once you've picked your sizes and your order for the voxel fields, you call vpSetVoxelSize once, and then you call vpSetVoxelField once for each field. that's the whole ritual, periodt.

Every field gets a unique field number — that's the field_num argument. first field is 0, next is 1, and so on, all the way up to one less than the total number of fields you defined with VpSetVoxelSize.

The field_max argument is what determines the required size for lookup tables that get indexed by the value in a particular field. the maximum field value can be any number from 0 up to the maximum unsigned integer that's representable by the field size. 👑

🦋 declaring your voxel with a C struct 🦋

If you've declared the layout of a voxel using a C structure, you can use the sizeof operator and the vpFieldOffset macro to compute your field sizes and offsets. vpFieldOffset returns the number of bytes from the beginning of a C structure to the beginning of a particular field in that structure.

for example, here's how you'd declare the size and offset for one voxel field:

struct voxel {
    char field0;
    char field1;
    short field2;
} *dummy_voxel;

#define SIZE_0    sizeof(char)
#define OFFSET_0  vpFieldOffset(dummy_voxel, field0)
#define MAX_0     127

vpSetVoxelField(vpc, 0, SIZE_0, OFFSET_0, MAX_0);

🌈 the rules, and you WILL respect them 🌈

• the size of each field must be 1, 2 or 4 bytes. that's it. that's the list.
• you also have to obey any byte-alignment restrictions your hardware demands. on many machines, two-byte fields must begin on a two-byte boundary, and four-byte fields must begin on a four-byte boundary.
• the total size of a voxel may also need to be padded so that voxels packed one after the other still obey the alignment restrictions.
• if you declare your voxel as a C structure and use the sizeof operator and the vpFieldOffset macro, then you should always get correct results. 💯
• however — and this is the shady part — if you don't consider alignment restrictions when you're choosing the voxel field ordering, the compiler may have to insert padding for you, and that's wasted memory. not cute. 😭

🧚 fields that other routines need 🧚

Some VolPack routines require you to declare fields of a particular size so they have somewhere to store their results. the functions that precompute surface normals and gradient magnitudes (see vpVolumeNormals(3), vpScanlineNormals(3), vpClassifyVolume(3), vpClassifyScalars(3) and vpClassifyScanline(3)) can optionally store a one-byte scalar value, a one-byte gradient magnitude, and a two-byte surface normal value in each voxel.

the following constants, defined in volpack.h, give you the corresponding maximum field values: VP_SCALAR_MAX, VP_GRAD_MAX, and VP_NORM_MAX. 🎀

If you choose not to use these functions, then there's no need to declare these fields. skip them, live your life.

🫶 opacity tea 🫶

It's usually not necessary to declare a field for the voxel opacity if the opacity can be computed from the other voxel fields. see vpSetClassifierTable(3) for further discussion.

⚠️ heads up bestie: if the call to vpSetVoxelSize succeeds, any existing precomputed volume data structures in the context are destroyed. gone. bye. 💀

---

⭐ STATE VARIABLES ⭐

You can retrieve the current voxel field parameters with these state variable codes (see vpGeti(3)): VP_FIELD_SIZES, VP_FIELD_OFFSETS, VP_FIELD_MAXES.

---

🔥 ERRORS 🔥

The normal return value is VP_OK. the following error return value is possible:

• VPERROR_BAD_VALUE — the field number, size or offset is out of range. someone's not colouring inside the lines. 🙈

---

🌟 SEE ALSO 🌟

VolPack(3), vpCreateContext(3), vpSetVoxelSize(3)

---

and that's the page, bestie!! this iconic lil manual came to you from VolPack, under the name vpSetVoxelField(3) — go forth and define your voxel fields correctly, no cap. 💜✨🎀