vpScanlineNormals(3)

💖 vpScanlineNormals — the vpScanlineNormals(3) page, but make it make sense 💖

okay bestie, pull up a chair, we're in section 3 of the library functions manual and we're about to compute surface normal vectors AND gradient magnitudes for a single scanline. yes. both. she does it all. 🎀

---

✨ NAME ✨

vpScanlineNormals — compute surface normal vectors and gradient magnitudes for a scanline

---

🦋 SYNOPSIS 🦋

#include <volpack.h>

vpResult
vpScanlineNormals(vpc, length, scalar_data, scalar_minus_y,
        scalar_plus_y, scalar_minus_z, scalar_plus_z, voxel_data,
        scalar_field, grad_field, norm_field)
    vpContext *vpc;
    int length;
    unsigned char *scalar_data;
    unsigned char *scalar_minus_y, *scalar_plus_y;
    unsigned char *scalar_minus_z, *scalar_plus_z;
    void *voxel_data;
    int scalar_field;
    int grad_field;
    int norm_field;

like. look at that parameter list. she's serving 💅

---

🌸 ARGUMENTS 🌸

• vpc — the VolPack context, the one you got from vpCreateContext. your whole world basically.
• length — size of the scalar_data array, in bytes.
• scalar_data — a 1D array of scalar samples. the main character of this scanline.
• scalar_minus_y — 1D array of scalar samples sitting right next to scalar_data in the -Y direction.
• scalar_plus_y — same vibe, but 1D array of scalar samples adjacent to scalar_data in the +Y direction.
• scalar_minus_z — 1D array of scalar samples adjacent to scalar_data in the -Z direction.
• scalar_plus_z — 1D array of scalar samples adjacent to scalar_data in the +Z direction.
• voxel_data — 1D array of voxels, where the results go to live. it's giving storage unit.
• scalar_field — voxel field number telling us which field to store the scalar samples in.
• grad_field — voxel field number for storing the gradient magnitudes of the scalar samples.
• norm_field — voxel field number for storing encoded surface normal vectors. encoded! not raw! remember that.

---

🌈 DESCRIPTION 🌈

so vpScanlineNormals is your precompute girlie 💖. she crunches values for voxel fields that get used by classification and shading algorithms. the input is a whole collection of 5 adjacent 1D arrays of scalar values. and yes, there's a separate routine for when you've got a full 3D array of voxel data — go check vpVolumeNormals(3), she's right there.

why would you want the scanline version? because it's useful for loading large volumes into memory scanline-by-scanline and precomputing voxel fields incrementally, instead of loading a complete copy of the 3D scalar array on top of the voxel array. no cap, that's a lot of memory you're saving. in every other respect this routine is identical in function to vpVolumeNormals.

okay, rules of the road:

• the 1D scalar arrays must be arrays of 8-bit values — other sizes are not currently supported 🫠
• the length parameter tells you both the size and the number of elements in each of the scalar arrays.
• vpScanlineNormals does the exact computation described in vpVolumeNormals(3), but only for the single scanline specified by scalar_data.
• the other four scanline arguments must be the immediately adjacent scanlines, because they're what we use to compute the gradient. no skipping rows, bestie.

where do results go? into voxel_data, which has to have space for the same number of voxels as the length of one scalar scanline. and listen:

you must specify the size of a voxel with vpSetVoxelSize before calling vpScanlineNormals. but it is not necessary to call vpSetRawVoxels. write that down. 📝

the scalar_field, grad_field and norm_field arguments say which voxel fields the computed quantities get stored into. these field numbers have to correspond to appropriately-sized voxel fields you already specified with vpSetVoxelField.

and here's the fun part — any of these arguments can be the constant VP_SKIP_FIELD, in which case the corresponding quantity is simply not computed or copied. skip era, we love her.

size requirements, pay attention:

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

the constants VP_SCALAR_MAX, VP_GRAD_MAX and VP_NORM_MAX give the maximum value that might be stored in each field, respectively.

and finally, iconic detail: the value stored in the surface normal vector field is actually an encoded surface normal. see vpNormalIndex(3). iykyk ✨

---

💀 ERRORS 💀

the normal return value is VP_OK. but she can also hand you these:

• VPERROR_BAD_VALUE — one or more of the voxel fields 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 have been incorrectly specified.

---

👑 SEE ALSO 👑

VolPack(3), vpCreateContext(3), vpNormalIndex(3), vpVolumeNormals(3), vpSetClassifierTable(3), vpSetLookupShader(3)

---

and that's the whole page, bestie 🫶 this one comes to you from VolPack, straight out of the library functions manual — go forth, compute those normals, and stay encoded. periodt. 💜