vpScanlineNormals(3)

💖 vpScanlineNormals(3) 💖

okay bestie so this is a page from the Library Functions Manual and it's literally all about vpScanlineNormals — the girlies in the VolPack house wrote this one and it's lowkey iconic 🫶

✨ 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;

✨ ARGUMENTS ✨

• vpc — the VolPack context you got from vpCreateContext. your whole world basically 🌍
• length — the size of the scalar_data array, in bytes. it's giving "how many bytes, exactly" 📏
• scalar_data — a 1D array of scalar samples.
• scalar_minus_y — a 1D array of scalar samples that are adjacent to scalar_data in the -Y direction.
• scalar_plus_y — a 1D array of scalar samples that are adjacent to scalar_data in the +Y direction.
• scalar_minus_z — a 1D array of scalar samples that are adjacent to scalar_data in the -Z direction.
• scalar_plus_z — a 1D array of scalar samples that are adjacent to scalar_data in the +Z direction.
• voxel_data — a 1D array of voxels where the results get stored. the output girlies 💅
• scalar_field — the voxel field number telling you which field to store the scalar samples in.
• grad_field — the voxel field number telling you which field to store the gradient magnitudes of the scalar samples in.
• norm_field — the voxel field number telling you which field to store the encoded surface normal vectors in.

✨ DESCRIPTION ✨

so vpScanlineNormals is the routine you call when you wanna precompute values for voxel fields used in classification and shading algorithms. the input is a whole collection of 5 adjacent 1D arrays of scalar values. if you're tryna process a full 3D array of voxel data instead, there's a separate routine for that — go check vpVolumeNormals(3) 🦋

vpScanlineNormals is so useful when you're loading big volumes into memory scanline-by-scanline and precomputing voxel fields incrementally, instead of loading a complete copy of the 3D scalar array plus the voxel array. like, why would you do that to yourself 😭 in all other respects though, this routine is identical in function to vpVolumeNormals. no cap.

the 1D scalar arrays must be arrays of 8-bit values — other sizes are not currently supported, sorry bestie, that's just the rules 🙈 the length parameter indicates both the size and the number of elements in each of the scalar arrays. vpScanlineNormals performs the computation described in vpVolumeNormals(3), but only for the single scanline specified by scalar_data. the other four scanline arguments have to be the immediately adjacent scanlines — they're what gets used to compute the gradient. adjacency is the whole vibe 🔥

the results go into the voxel_data array, which needs space for the same number of voxels as the length of one scalar scanline. before you call vpScanlineNormals you gotta specify the size of a voxel with vpSetVoxelSize — but ngl it is not necessary to call vpSetRawVoxels. periodt.

the arguments scalar_field, grad_field and norm_field say which voxel fields the computed quantities get stored into. these field numbers must correspond to appropriately-sized voxel fields you already specified with vpSetVoxelField. any of these arguments can be the constant VP_SKIP_FIELD, and in that case the corresponding quantity is simply not computed or copied. skipping is valid 💅

technical tea, pay attention: the voxel fields for the scalar value and the gradient magnitude must be one-byte fields, and the 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 the value stored in the surface normal vector field is actually an encoded surface normal — see vpNormalIndex(3) for that whole situation 👑

✨ ERRORS ✨

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

• VPERROR_BAD_VALUE — one or more of the voxel fields specified is invalid, or the corresponding voxel field has the wrong size. wrong size = not the vibe 😭
• 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 page bestie, we ate 💅✨ this one came to you from VolPack, and the page is vpScanlineNormals(3) — go forth and precompute those normals, you main character 🫶👑