vpSetMaterial(3)

💖 vpSetMaterial — set material properties 💖

okay bestie, so this is vpSetMaterial(3) from the VolPack library functions manual, and it's literally the glow-up station for your materials ✨ You know how every voxel can be a lil mix of different material types? Yeah, this is where you tell each one how shiny, how matte, how ambient-girl it should be. Let's get into it 🎀

---

✨ 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, the one you got from vpCreateContext. your main character, fr.
• material — a constant naming a specific material number. your options are VP_MATERIAL0, VP_MATERIAL1, ..., all the way up to VP_MATERIAL5. pick your fighter 💅
• property — a constant naming exactly one material property. that's VP_AMBIENT, VP_DIFFUSE, VP_SPECULAR, or VP_SHINYNESS. one at a time, bestie, we're not greedy.
• surface_side — a constant saying which side of the material surface these properties apply to: VP_EXTERIOR, VP_INTERIOR, or VP_BOTH_SIDES. it's giving duality 🦋
• r, g, b — the RGB components of the color that goes with the property. and heads up: for VP_SHINYNESS, the g and b are literally not used. they're just there vibing 😌

---

💜 DESCRIPTION 💜

So vpSetMaterial sets the properties of a material type. Every voxel can be made up of a mixture of several different material types, and that whole situation is described over in vpSetLookupShader(3). Each material type gets its own color and its own light reflection properties. Those properties get fed as parameters into the Phong shading equation, which computes the color of the material given a set of light sources and a viewing direction — peep vpShadeTable(3) for that.

To initialize your material parameters, you call vpSetMaterial for each property of each material type you're actually gonna use. no skipping, no shortcuts, she's thorough 💅 The total number of materials is specified as an argument to vpSetLookupShader. First material is VP_MATERIAL0, second is VP_MATERIAL1, and so on down the line.

🎀 the properties, one by one 🎀

VP_AMBIENT — sets the RGB ambient light coefficients of the material. This term represents the intensity of background light that's reflected by the material. Each of the RGB components is the coefficient for the corresponding light basis function. The values should be in the range 0.0-1.0. Default: 0.1 ✨

VP_DIFFUSE — sets the RGB diffuse light coefficients of the material. This term is the fraction of incident light intensity that gets reflected diffusely, aka that dull, matte appearance. values go in the range 0.0-1.0. Default: 0.4 🌸

VP_SPECULAR — sets the RGB specular light coefficients of the material. This one is the fraction of incident light intensity reflected specularly — shiny, mirror-like, glossy queen energy 💅 values in the range 0.0-1.0. Default: 0.5 ⭐

VP_SHINYNESS — sets a single exponent that modifies the spread of the specular highlights. The higher the number, the smaller and more intense the specular 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 🔥

🦋 surface_side tea 🦋

The surface_side argument specifies which side of the material surface the properties apply to. By default, the "interior" side of a voxel is the side 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 apply different material parameters to the two surface sides by calling vpSetMaterial separately for each side. The option VP_BOTH_SIDES lets you set the same property for both sides with only one function call — efficient, iconic, we love her. And yes, it's possible to reverse the definition of interior and exterior sides by calling vpEnable with the VP_REVERSE_SURFACE_SIDES option. plot twist 🌀

🧚 the equation, bestie 🧚

Voxels are shaded using this equation:

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

and here's what every 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 is added for each light source — with different values for L, n_dot_l and n_dot_h corresponding to that particular light source. no cap, more lights more math 💀

---

🌈 STATE VARIABLES 🌈

You can retrieve info about the current material properties with these state variable codes (go look at vpGeti(3)): VP_MATERIAL_COUNT, VP_REVERSE_SURFACE_SIDES.

---

😭 ERRORS 😭

The normal return value is VP_OK. These error return values are possible, and yes they will humble you:

• 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)

---

okay that's the whole page, go forth and shade responsibly 🫶

and that's a wrap from your girl at VolPack — this was vpSetMaterial(3), mwah, periodt 💖✨