vpSetMaterial(3)

💖 NAME 💖

okay so welcome to vpSetMaterial(3), straight outta the Library Functions Manual 📚✨ — this one sets material properties. that's the whole vibe. let's go bestie 🫶

---

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpSetMaterial(vpc, material, property, surface_side, r, g, b)
    vpContext *vpc;
    int material;
    int property;
    int surface_side;
    double r, g, b;

---

🎀 ARGUMENTS 🎀

• vpc — the VolPack context you got from vpCreateContext. your lil home base 🏠
• material — a constant that says which material number you're talking about: VP_MATERIAL0, VP_MATERIAL1, ..., VP_MATERIAL5 ✨
• property — a constant naming exactly one material property: VP_AMBIENT, VP_DIFFUSE, VP_SPECULAR or VP_SHINYNESS 💅
• surface_side — a constant saying which side of the material surface these properties apply to: VP_EXTERIOR, VP_INTERIOR or VP_BOTH_SIDES 🦋
• r, g, b — the RGB components of the color tied to that property. for VP_SHINYNESS, g and b do not get used at all — they're just sitting there. iconic but unemployed 😭

---

👑 DESCRIPTION 👑

vpSetMaterial is how you set the properties of a material type, no cap. every voxel can be a whole mixture of several different material types, which is the tea described over in vpSetLookupShader(3). each material type gets its own color and its own light reflection properties. those properties get fed in as parameters to the Phong shading equation, which computes the color of the material given a set of light sources and a viewing direction — see vpShadeTable(3) 💜

to initialize the material parameters, you call vpSetMaterial for each property of each material type you're gonna use. the total number of materials is specified as an argument to vpSetLookupShader. first material = the constant VP_MATERIAL0, second = VP_MATERIAL1, and so on, forever, in order 🧚

• VP_AMBIENT — the RGB ambient light coefficients of the material. this term is the intensity of background light that the material reflects. each of the RGB components is the coefficient for the corresponding light basis function. the coefficient values should be in the range 0.0-1.0. Default: 0.1
• VP_DIFFUSE — the RGB diffuse light coefficients of the material. this term is the fraction of incident light intensity that gets reflected diffusely (think dull, matte energy — the opposite of a glossy mirror moment). the coefficient values should be in the range 0.0-1.0. Default: 0.4
• VP_SPECULAR — the RGB specular light coefficients of the material. this term is the fraction of incident light intensity reflected specularly (shiny, mirror-like, main character glow ✨). the coefficient values should be in the range 0.0-1.0. Default: 0.5
• VP_SHINYNESS — a single exponent that modifies the spread of specular highlights. the higher the number, the smaller and more intense those highlights get. the exponent is specified with the r argument and can have any value; the generally-useful range is 1.0 to 100.0. the g and b arguments are ignored for this property. Default: 10.0

the surface_side argument says which side of the material surface the properties apply to. by default, the "interior" side of a voxel is the side pointing in the direction of the surface normal. during rendering, if the normal points closer to the direction of the viewer than the opposite of the normal, then the viewer is looking at the exterior side of the voxel rather than the interior. you can give the two surface sides totally different material parameters by calling vpSetMaterial separately for each side. the option VP_BOTH_SIDES lets you set the same property for both sides in just one function call — efficient queen 💅. and yes, it's possible to reverse the definition of interior and exterior sides by calling vpEnable with the VP_REVERSE_SURFACE_SIDES option 🔄

voxels get shaded using this equation, periodt:

I = A + L * (D * n_dot_l + S * pow(n_dot_h, E))

and here's what each lil letter means:

• I — intensity for one color channel
• A — ambient intensity coefficient
• D — diffuse reflection coefficient
• S — specular reflection coefficient
• E — shinyness
• L — light intensity
• n_dot_l — dot product of normal and light vectors
• n_dot_h — dot product of normal and highlight vectors

this equation is evaluated separately for each color channel. and if multiple light sources are enabled, an additional term identical to the second term above gets added for each light source (with different values for L, n_dot_l and n_dot_h corresponding to that particular light source). more lights, more terms, more math, we love to see it 🔥

---

🌈 STATE VARIABLES 🌈

you can retrieve info about the current material properties with these state variable codes (see vpGeti(3)): VP_MATERIAL_COUNT, VP_REVERSE_SURFACE_SIDES 👑

---

💀 ERRORS 💀

the normal return value is VP_OK. the following error return values are possible, and yes they're giving bad news:

• VPERROR_BAD_VALUE — either the material number or the RGB components are invalid 🙈
• VPERROR_BAD_OPTION — either the surface_side or property arguments are invalid 😭

---

🦋 SEE ALSO 🦋

VolPack(3), vpCreateContext(3), vpSetLookupShader(3), vpShadeTable(3), vpGetMaterial(3)

---

that's the whole page, bestie — brought to you by VolPack, closing out on vpSetMaterial(3) 💖🎀✨ slay, go set some materials 🫶