vpSetFilter(3)

✨ NAME ✨

vpSetFilter — define a resampling filter 💖

okay so real talk, this is the vpSetFilter(3) page from the Library Functions Manual, and it's literally the glow-up tutorial for your filter weights. let's get into it bestie 🦋

---

🎀 SYNOPSIS 🎀

#include <volpack.h>

vpResult
vpSetFilter(vpc, num_taps, num_phases, weights)
    vpContext *vpc;
    int num_taps, num_phases;
    float *weights;

---

🫶 ARGUMENTS 🫶

• vpc — the VolPack context, and you got it from vpCreateContext. your whole lil world lives in here 🫙
• num_taps — how many filter taps. that's the count, periodt.
• num_phases — how many filter phases. yes it matters, keep reading 💅
• weights — the array holding the filter weights themselves. the whole point, honestly 👑

---

💅 DESCRIPTION 💅

okay so vpSetFilter is what you call to hand over a table of filter weights before you resample an array with vpResample. think of it as prepping your palette before you paint 🎨. this table lets you specify an arbitrary separable space-invariant filter — yes, that's the whole vibe, no cap.

the vpc argument is a VolPack context that stores the description of your resampling filter. and listen: the volume data and rendering parameters currently chillin' in that context are not affected by calls to vpSetFilter or vpResample. they stay exactly as they were, untouched, iconic behavior fr fr ✨

the num_taps argument says how many filter taps there are. when an array gets resampled, the number of filter taps equals the number of input array elements that contribute to one element of the output array. every tap gets its own filter weight, and that weight decides how much the corresponding input element contributes to that output element. important nuance bestie: when you're upsampling, the number of taps depends only on the support of the filter kernel. when you're downsampling, the number of taps should also depend on the scale factor — because the filter kernel has to be scaled too. don't forget the scale factor, that's the whole plot twist 😭

the num_phases argument says how many filter phases there are, which equals the number of times the filter kernel gets sampled. more phases = more accurate filtering, highkey a slay. BUT. there's a point of diminishing returns where adding more phases gives you barely any accuracy boost while hitting you with the downsides: increased storage requirements and potentially poor cache performance 💀. and here's the hard requirement — to allow for an efficient implementation, num_phases must be a power of two. non-negotiable, that's the law 🚨

the weights array contains the filter weights themselves. the array should have dimensions:

float weights[num_phases][num_taps];

each element should normally be a number between 0.0 and 1.0 (negative values are also possible but can lead to ringing 👻), and for any particular phase, the entries for all of the taps should sum to 1.0 — or else ripple gets introduced into constant regions of the filtered array. so like, sum to one or suffer the ripple, your call 🫠

and the easiest way to initialize that weight table? just call one of the predefined routines described in the vpBoxFilter(3) man page. free real estate, take it 🌸

---

💀 ERRORS 💀

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

• VPERROR_BAD_VALUE — either num_taps is non-positive, or num_phases is not a positive power of two. (again with the power of two bestie, i told you 😭)

---

🌈 SEE ALSO 🌈

VolPack(3), vpBoxFilter(3), vpResample(3)

---

and that's the page, bestie 💜 this was vpSetFilter(3) from VolPack, brought to you by the Library Functions Manual. go forth and resample responsibly, mwah 🎀✨👑