vpVolumeNormals(3)

💖 vpVolumeNormals(3) — the Library Functions Manual glow-up 💖

okay bestie, gather round, because this one is a VolPack classic from the Library Functions Manual and it's literally the girl who precomputes your normals so your renders can eat 🍓

---

✨ NAME ✨

vpVolumeNormals — compute surface normal vectors and gradient magnitudes for a volume 🦋

---

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpVolumeNormals(vpc, scalar_data, length, scalar_field, grad_field,
        norm_field)
    vpContext *vpc;
    unsigned char *scalar_data;
    int length;
    int scalar_field;
    int grad_field;
    int norm_field;

---

🎀 ARGUMENTS 🎀

• vpc — the VolPack context, the one you got from vpCreateContext. your main character ✨
• scalar_data — a 3D array of scalar samples. the raw material, the vibe source 💅
• length — how big the scalar_data array is, in bytes. yes, bytes. no cap.
• scalar_field — the voxel field number that says where to stash the scalar samples.
• grad_field — the voxel field number that says where to stash the gradient magnitudes of those scalar samples.
• norm_field — the voxel field number that says where to stash the encoded surface normal vectors. the glow-up field 💖

---

👑 DESCRIPTION 👑

so vpVolumeNormals is the precompute girlie 🫶 she crunches values for voxel fields that get used later in classification and shading algorithms. the input is a 3D array of scalar values — and if you've got scanlines of voxel data instead, there's a whole separate routine for that, see vpScanlineNormals(3).

for every single voxel, she computes an approximation of the gradient of the scalar field (using a central-difference operator, iconic technique, no notes). from that vector she can then work out:

• the magnitude of the gradient — lowkey essential for some classification schemes, check vpSetClassifierTable(3)
• a surface normal vector pointing in the direction of the gradient vector — this is the one that makes lighting models happen, see vpShadeTable(3) 🔥

and then the scalar value, the gradient magnitude and the surface normal vector all get stored into the fields of the voxel array. and yes — that voxel array is separate from the array of scalar values. two different girlies, two different jobs 💅

okay now the rules, and you need to hear these:

• the scalar array must be an array of 8-bit values. other sizes are not currently supported, periodt. 😭
• the dimensions of the array must match the volume dimensions you already set with vpSetVolumeSize.
• the size argument exists to make sure the array has the correct size. she's checking. she's always checking. 👀
• the voxel array must also be initialized by calling vpSetRawVoxels before you call vpVolumeNormals. do it before, bestie, not after, i'm begging 🙈

now the three voxel field number arguments — they tell her which voxel fields the computed info goes into, and which field the scalar samples get copied to. the field numbers must correspond to appropriately-sized voxel fields you already specified with vpSetVoxelField.

any of these three arguments can be the constant VP_SKIP_FIELD — and in that case the corresponding quantity is just not computed or copied. skipping is valid. skipping is self-care. 💅

the sizing rules, fr fr:

• the voxel fields for the scalar value and the gradient magnitude must be one-byte fields.
• the field for the surface normal vector must be a two-byte field.

and the maximums? they're giving constants:

• VP_SCALAR_MAX — the max value that might be stored in the scalar field
• VP_GRAD_MAX — the max value that might be stored in the gradient magnitude field
• VP_NORM_MAX — the max value that might be stored in the norm field

respectively. respectively!! 🎀

and heads up — the value stored in the surface normal vector field is actually an encoded surface normal, not the raw thing. see vpNormalIndex(3) for the decode lore. 🧚

---

💀 ERRORS 💀

the normal return value is VP_OK. slay. ✨

but here are the possible error return values, and they are not the vibe:

• VPERROR_BAD_SIZE — the size of the scalar array does not match the volume dimensions. she measured. it didn't fit. 😭
• VPERROR_BAD_VALUE — one or more of the voxel fields you specified is invalid, or the corresponding voxel field has the wrong size.
• VPERROR_BAD_VOXEL — the voxel size or the voxel fields have not been specified, or they've been specified incorrectly. incorrect specification is a crime, unfortunately. 💀
• 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.

---

🌈 SEE ALSO 🌈

the whole friend group, go say hi:

• VolPack(3)
• vpCreateContext(3)
• vpNormalIndex(3)
• vpScanlineNormals(3)
• vpSetClassifierTable(3)
• vpSetLookupShader(3)

---

and that's the whole page, bestie 🫶 this was VolPack, manual page vpVolumeNormals(3), and she ate, she left no crumbs, she is the moment 💖✨🎀