vpSetLookupShader(3)

💖 vpSetLookupShader — the manual page, but make it cute 💖

okay bestie, sit down, we're talking about vpSetLookupShader(3) from the Library Functions Manual section 3, aka the shading lookup table glow-up function. this is the one that tells VolPack how to shade ur voxels with precomputed tables. it's giving efficiency. it's giving main character. let's go 🦋

---

✨ NAME ✨

vpSetLookupShader — specify shading lookup tables 🎀

---

🌸 SYNOPSIS 🌸

#include <volpack.h>

vpResult
vpSetLookupShader(vpc, color_channels, num_materials, color_field,
        color_table, color_table_size, weight_field, weight_table,
        weight_table_size)
    vpContext *vpc;
    int color_channels, num_materials;
    int color_field;
    float *color_table;
    int color_table_size;
    int weight_field;
    float *weight_table;
    int weight_table_size;

---

💅 ARGUMENTS 💅

• vpc — the VolPack context u got from vpCreateContext. ur whole vibe lives in here.
• color_channels — how many color channels per pixel. it's 1 or 3, no in between, periodt.
• num_materials — how many material types we're working with.
• color_field — the field number for the voxel field that holds the color lookup table index.
• color_table — the color lookup table itself.
• color_table_size — size of the color lookup table, in bytes.
• weight_field — the field number for the voxel field that holds the material weight lookup table index.
• weight_table — the material weight lookup table.
• weight_table_size — size of the material weight lookup table, in bytes.

---

🌈 DESCRIPTION 🌈

so like, vpSetLookupShader is what u call to specify the lookup tables that define a shading function. the lookup-table shading algorithm VolPack gives u is designed to support this whole shading model, and honestly? it ate. here's the deal:

every voxel is assumed to contain a mixture of some set of basic material types. each material type has its own shading parameters for the Phong shading equation (think: the diffuse color components, the shinyness, all of it). the color of a voxel gets found by computing a color for each material type and then combining those colors in proportion to how much of each material is in the voxel. the shading model also supports directional (infinite-distance) light sources. iconic behavior ✨

this shading model gets implemented using lookup tables, and the reason is literally just speed: the tables can be precomputed so the shading equation never has to be evaluated for every single voxel. VolPack ships routines to compute the lookup tables for u (peep vpShadeTable(3)). u can also use the lookup tables to implement other shading models, by bringing ur own user-supplied routine to compute what goes in the tables. and if u wanna know about depth cueing, go read vpSetDepthCueing(3). 🫶

it's also possible to define a callback function that gets called to shade each voxel during rendering, instead of using a lookup table. that method allows more general shading models, but — and hear me out — it slows down rendering. so like, tradeoffs. to define a callback shader, call vpSetCallback with the VP_GRAY_SHADE_FUNC or VP_RGB_SHADE_FUNC option code (see vpSetCallback(3)). here's the tiebreaker rule, and it's lowkey important: the lookup tables are used if the last successful call to vpSetLookupShader occurred after the last successful call to vpSetCallback with one of the VP_*_SHADE_FUNC options. last one to the function wins. no cap.

the color_channels argument determines whether the shading table will contain grayscale (1 channel) or RGB (3 channel) pixels. the num_materials argument specifies the number of basic material types out of which each voxel can be composed — and that's at least 1, bestie, don't try it. the color_table and weight_table arguments specify two lookup tables, and the color_field and weight_field arguments specify two voxel fields that are used to index those tables.

now, the sizes. the size of the color_table array must be:

float color_table[n][num_materials][color_channels];

where n is the number of possible values in the color_field field of the voxel (that's the maximum value plus one). and the size of the weight_table argument must be:

float weight_table[m][num_materials];

where m is the number of possible values in the weight_field field of the voxel (again, maximum value plus one). and here's a lil treat: if there is only one material then weight_table is not used and may be a NULL pointer. free real estate 🎀

---

🦋 how the tables get read during rendering 🦋

okay so during rendering, the shading lookup tables are accessed like this. suppose a particular voxel to be shaded has the value color_index in the field specified by color_field, and the value weight_index in the field specified by weight_field. for each material number material_index, a weighted color is computed from the formula:

color = color_table[color_index][material_index] *
        weight_table[weight_index][material_index]

then the weighted colors for each material type get added up to give the voxel color. if color_table contains RGB values then each component is treated separately using the above formula. and if there's only one material type, then the constant 1.0 is substituted for the weight_table value. slay. 💅

---

🧚 the suggested way to use the tables 🧚

here's what the docs recommend, and honestly it's a whole strategy:

the voxel field specified by color_field should contain an encoded surface normal vector — and it should be the same field as the norm_field argument to vpVolumeNormals or vpClassifyScalars. in the color_table array, for each possible encoded surface normal (that's the color index) and material type (that's the material index), the array should contain the color of the material given the current viewing direction and lighting arrangement. the color is independent of the voxel location because the light sources are assumed to be infinitely distant. the function vpShadeTable initializes the contents of color_table in this way. easy ✨

the voxel field specified by weight_field should contain some quantity that determines the material composition of the voxel. for example, a field containing the scalar value could be used. in the weight_table array, for each possible value of weight_field there should be one row of material occupancy fractions. each entry should be a number in the range 0.0-1.0 that specifies the fraction of the voxel occupied by the corresponding material.

for example — and i love a concrete example — if there are two material types and a voxel's weight_field contains the value 62, then weight_table[62][0] gives the fraction of the voxel occupied by material 0, and weight_table[62][1] gives the fraction of the voxel occupied by material 1. normally, the numbers in a given row of weight_table should add up to 1.0 (although special effects can be achieved by bending the rules, and honestly? respect the hustle 😌). the function vpRamp is useful for initializing the weight table with piece-wise linear ramps.

the values in the shading lookup tables may be initialized before or after calling vpSetLookupShader. typically vpSetLookupShader is called once at the beginning of a rendering session, and then the values in the shading tables get modified as the user changes the lighting and shading parameters or the viewing direction. it's giving "set it and forget it, then tweak it forever." 💜

---

⭐ STATE VARIABLES ⭐

u can retrieve info about the current shading table parameters with these state variable codes (see vpGeti(3)):

• VP_COLOR_CHANNELS
• VP_SHADE_COLOR_TABLE
• VP_SHADE_COLOR_SIZE
• VP_SHADE_WEIGHT_TABLE
• VP_SHADE_WEIGHT_SIZE
• VP_SHADE_COLOR_FIELD
• VP_SHADE_WEIGHT_FIELD
• VP_MATERIAL_COUNT

---

🚨 ERRORS 🚨

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

• VPERROR_BAD_VALUE — one or more of the arguments has an invalid value or is out of range. 🙈
• VPERROR_LIMIT_EXCEEDED — the num_materials argument has exceeded an internal limit. to fix this, change the value of VP_MAX_MATERIAL in volpack.h and recompile the VolPack library. (yes, really, u gotta recompile. it's a whole thing. 😭)

heads up bestie: that second one means a plain re-run won't save u — u have to edit volpack.h and rebuild. no shortcuts.

---

👑 SEE ALSO 👑

VolPack(3), vpCreateContext(3), vpShadeTable(3), vpSetCallback(3), vpRamp(3), vpVolumeNormals(3), vpClassifyScalars(3), vpSetDepthCueing(3)

---

and that's the whole page, bestie!! 💖✨ this lil bop of a manpage comes to u straight from VolPack, so shoutout to them for the source and the version, and it's dated right there in the footer of the original — go give it a kiss goodnight 🌸🦋🎀 periodt 💅