vpSetCallback(3)

✨ vpSetCallback(3) ✨

ok so bestie, you know that one page from the Library Functions Manual — the one about vpSetCallback? yeah. that one. sit down, get comfy, we're doing this 💖

---

🎀 NAME 🎀

vpSetCallback — define a callback function. that's it. that's the whole vibe. slay ✨

---

🦋 SYNOPSIS 🦋

#include <volpack.h>

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

---

🌸 ARGUMENTS 🌸

• vpc — your VolPack context, the one you got from vpCreateContext. your main character, if you will 👑
• option — a code that tells VolPack which callback function you're setting. it's giving "choose your fighter" energy.
• func — a pointer to the callback function itself. the actual function. the moment. 💅

---

💜 DESCRIPTION 💜

ok so vpSetCallback is literally the "hey, you handle this" function. you use it to set a callback function. here are all the possible values for option, no skips, no summaries, we're doing all of them fr fr:

• VP_GRAY_SHADE_FUNC — func here is a shading callback that produces a floating point grayscale pixel intensity. it should be declared 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. it should be a single-precision floating point in the range 0.0 (black) to 1.0 (white). black to white, the full range, no in-between shenanigans 🖤🤍
• client_data — pointer to the application-defined client data (see vpSetClientData(3)).

the callback can be used to implement custom shading routines that cannot be implemented with a lookup table. see vpSetLookupShader(3) for more info. lowkey iconic.

• VP_RGB_SHADE_FUNC — func here is a shading callback that produces a floating point RGB pixel intensity. it should be declared:

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

• 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 should be a single-precision floating point in the range 0.0 (no intensity) to 1.0 (full intensity).
• client_data — pointer to the application-defined client data (see vpSetClientData(3)).

the callback can be used to implement custom shading routines that cannot be implemented with a lookup table. see vpSetLookupShader(3) for more information.

• VP_READ_FUNC — func here 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. the callback can be used to implement a custom I/O interface — for example a compression/decompression system. custom I/O era 💅
• VP_WRITE_FUNC — func here 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. the callback can be used to implement a custom I/O interface, for example a compression/decompression system.
• VP_MMAP_FUNC — func here is a callback that gets called to memory map data from a file instead of copying the data into memory (see vpLoadRawVolume(3)). it should be declared:

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

• fd — file descriptor from open(2) open 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)).

the function should map the entire file into memory and return a pointer to the memory location that corresponds to the file offset. by default, memory mapping is disabled. it's giving "opt-in only" 🫶

• VP_STATUS_FUNC — func here is a callback that gets called periodically during long-running operations, like during preprocessing of a volume. it should be declared:

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.

the callback can be used to print a status report or to process time-critical events such as user input.

⚠️ okay but for real: the callback should not make any calls to VolPack functions, because the internal VolPack state may be inconsistent. do not do it. hands off. no cap. 💀

• VP_LOG_ALLOC_FUNC — func here is a callback that gets called whenever VolPack allocates memory. it should be declared:

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.

the callback can be used to track memory allocations (primarily for debugging memory leaks). detective mode 🔍

• VP_LOG_FREE_FUNC — func here is a callback that gets called whenever VolPack deallocates memory. it should be declared:

void func(void *ptr, void *client_data)

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

the callback can be used to track memory deallocations (primarily for debugging memory leaks).

and here's the lil plot twist: if the func argument is NULL, then the corresponding callback function gets reset to the default behavior — or disabled if there's no default behavior. so NULL = "never mind, we're so back to normal" ✨

---

😭 ERRORS 😭

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

• VPERROR_BAD_OPTION — the option argument is invalid. like, girl, that's not a real option 💀

---

🌈 SEE ALSO 🌈

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

---

ok that's the whole page bestie, you ate it, no crumbs 🍓💖 this was the vpSetCallback(3) page from the VolPack library, living in the Library Functions Manual — and yes, VolPack is the name at the bottom too, iykyk. go set some callbacks. mwah 💅✨