vpSetCallback(3)

okay bestie, pull up a chair 💖 you've landed on vpSetCallback from the Library Functions Manual — this is the page where VolPack lets you plug your own functions into it. very main character of you, honestly.

---

✨ NAME ✨

vpSetCallback — define a callback function

---

🎀 SYNOPSIS 🎀

#include <volpack.h>

vpResult
vpSetCallback(vpc, option, func)
    vpContext *vpc;
    int option;
    void (*func)();

---

🦋 ARGUMENTS 🦋

• vpc — the VolPack context you got from vpCreateContext.
• option — a code that says which callback function you're setting.
• func — a pointer to the callback function itself.

---

💅 DESCRIPTION 💅

vpSetCallback is literally just you going "hey VolPack, use this function for this thing." And here's the full menu of possible values for option, no skips, no shortcuts:

• VP_GRAY_SHADE_FUNC — func is a shading callback that produces a floating point grayscale pixel intensity. Declare it like this:

void func(void *voxel_ptr, float *i_ptr, void *client_data);

• voxel_ptr — pointer to the beginning of a voxel that must be shaded.
• i_ptr — the location where your function should store the grayscale intensity result. Single-precision floating point, ranging from 0.0 (black) all the way to 1.0 (white).
• client_data — pointer to the application-defined client data (see vpSetClientData(3)).

Use this one when you need custom shading routines that a lookup table simply cannot do. More on that in vpSetLookupShader(3).

• VP_RGB_SHADE_FUNC — func is a shading callback that produces a floating point RGB pixel intensity. Declare it like this:

void func(void *voxel_ptr, float *r_ptr, float *r_ptr, float *r_ptr, void *client_data);

(yes, the page really does list float *r_ptr three times, I'm not editing it, I'm just the messenger 🙈)

• voxel_ptr — pointer to the beginning of a voxel that must be shaded.
• r_ptr, g_ptr, b_ptr — the location where your function should store the RGB intensities of the result. Each intensity is a single-precision floating point from 0.0 (no intensity) to 1.0 (full intensity).
• client_data — pointer to the application-defined client data (see vpSetClientData(3)).

Again: custom shading routines that a lookup table can't pull off. vpSetLookupShader(3) has the tea.

• VP_READ_FUNC — func is a callback that takes the same arguments and returns the same result as the read(2) system call. It's used to read data from files (see vpLoadRawVolume(3)). By default, the read system call is used. Set this when you want a custom I/O interface — a compression/decompression system, for example. slay.
• VP_WRITE_FUNC — func is a callback that takes the same arguments and returns the same result as the write(2) system call. It's used to write data to files (see vpStoreRawVolume(3)). By default, the write system call is used. Same deal: custom I/O interface, compression/decompression, whatever your heart desires.
• VP_MMAP_FUNC — func is a callback that gets called to memory map data from a file instead of copying the data into memory (see vpLoadRawVolume(3)). Declare it like this:

void *func(int fd, unsigned offset, void *client_data);

• fd — file descriptor from open(2), opened for reading.
• offset — byte offset in the file to the beginning of the memory to be mapped.
• client_data — pointer to the application-defined client data (see vpSetClientData(3)).

Your function should map the entire file into memory and return a pointer to the memory location that corresponds to the file offset. Heads up: by default, memory mapping is disabled.

• VP_STATUS_FUNC — func is a callback that gets called periodically during long-running operations, like preprocessing a volume. Declare it like this:

void func(double frac, void *client_data);

• frac — an estimate of the fraction of the current operation that is complete.
• client_data — pointer to the client data associated with the context.

Perfect for printing a status report or handling time-critical events like user input. But 👇

🚨 the callback should not make any calls to VolPack functions, because the internal VolPack state may be inconsistent. do not do it bestie, I am begging 😭

• VP_LOG_ALLOC_FUNC — func is a callback that gets called whenever VolPack allocates memory. Declare it like this:

void func(void *ptr, int size, char *use, int line, char *file, void *client_data);

• ptr — address of the allocated memory.
• size — size (in bytes) of the allocated memory.
• use — short description of the use of the allocated memory.
• line — source code line number for the call to the memory allocator.
• file — source code file name for the call to the memory allocator.
• client_data — pointer to the client data associated with the context.

Great for tracking memory allocations (primarily for debugging memory leaks). detective energy 🔍

• VP_LOG_FREE_FUNC — func is a callback that gets called whenever VolPack deallocates memory. Declare it like this:

void func(void *ptr, void *client_data)

• ptr — address of the deallocated memory.
• client_data — pointer to the client data associated with the context.

Same vibe, opposite direction: tracking memory deallocations (primarily for debugging memory leaks).

And the plot twist: if the func argument is NULL, then the corresponding callback function gets reset to the default behavior — or disabled, if there is no default behavior. clean. simple. iconic.

---

😭 ERRORS 😭

The normal return value is VP_OK. The following error return value is possible:

• VPERROR_BAD_OPTION — the option argument is invalid. (translation: you typed something that isn't one of the codes above, bestie.)

---

🌈 SEE ALSO 🌈

VolPack(3), vpCreateContext(3), vpSetClientData(3), vpSetLookupShader(3), vpLoadRawVolume(3), vpStoreRawVolume(3)

---

and that's the whole page, periodt 💖 this little masterpiece lives in the VolPack collection as the page vpSetCallback(3) — no date on the footer, so it's simply timeless, as it should be. go set a callback, you've got this 🫶✨🎀