vpNormalIndex(3)

💖 vpNormalIndex(3) — your girl's guide to normal vectors, bestie 💖

okay so real talk, this page lives in the Library Functions Manual and it's all about vpNormalIndex and vpNormal, two lil functions from VolPack that do the whole encode/decode thing with surface normal vectors. yes THE surface normals. the ones your shading table has been begging for. let's get into it 🦋

---

✨ NAME ✨

vpNormalIndex, vpNormal — encode/decode a surface normal vector 🎀

---

✨ SYNOPSIS ✨

#include <volpack.h>

int
vpNormalIndex(nx, ny, nz)
    double nx, ny, nz;

vpResult
vpNormal(n, nx_ptr, ny_ptr, nz_ptr)
    int n;
    double *nx_ptr, *ny_ptr, *nz_ptr;

---

✨ ARGUMENTS ✨

• nx — the X component of your surface normal vector. just the x. that's her 💅
• ny — the Y component of your surface normal vector. yes, y, we love her.
• nz — the Z component of your surface normal vector. z is here too, trio complete ✨
• n — an encoded surface normal vector. it's an int, she's compact, she's iconic 👑
• nx_ptr — pointer to storage where we'll drop the X component of the surface normal vector back out. she's a pointer, she receives 🫶
• ny_ptr — pointer to storage for returning the Y component of the surface normal vector.
• nz_ptr — pointer to storage for returning the Z component of the surface normal vector.

---

✨ DESCRIPTION ✨

so these two routines? they convert surface normal vectors between encoded and unencoded forms. that's literally their whole job and they ate 🔥

an unencoded vector is described by its three components, stored as double-precision floating point numbers, in an orthogonal coordinate system. three doubles. very demure, very spacious.

an encoded vector is described by a single integer that is suitable for use as an index in a shading lookup table. one int. tiny. efficient. main character energy 💅

here's the tea: VolPack's built-in shading routines require the use of surface normal vectors encoded using vpNormalIndex — or one of the higher-level normal vector computation routines, vpVolumeNormals or vpScanlineNormals. so like, you could do it yourself, but why 😭

and before you panic — user-defined shading routines or lookup tables are not required to use encoded normal vectors. so if you're going custom, you're free. no cap 💖

okay so vpNormalIndex computes an encoded vector from the components of an unencoded vector. BUT. and this is important bestie, listen — the vector must be normalized, meaning:

nx*nx + ny*ny + nz*nz = 1

the maximum possible value of an encoded normal is given by the constant VP_NORM_MAX. remember her ⭐

then vpNormal does the reverse: it computes the components of a vector from the encoded integer form. but heads up — the encoded normal has less resolution than the unencoded form, so the vector computed by vpNormal may not be equal to the original vector you passed to vpNormalIndex. it's giving "close enough, bestie" 🙈 not a bug, just the tradeoff.

---

✨ ERRORS ✨

vpNormalIndex always returns a valid encoded normal vector. she never misses. periodt 💅✨

vpNormal normally returns the value VP_OK. but the following return value is possible:

• VPERROR_BAD_VALUE — the encoded normal vector is invalid. 💀 yeah. that one.

---

✨ SEE ALSO ✨

VolPack(3), vpVolumeNormals(3), vpScanlineNormals(3) — go read these next, they're the friend group 🫶🌈

---

and that's the whole page!! brought to you by VolPack, page vpNormalIndex(3). mwah, go encode something gorgeous 💜🎀