--- name: "Callback" section: "3" platform: "linux" package: "libvolpack1-dev" version: "1.0b3-10" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Callback" --- # Callback(3) define a callback function ## NAME vpSetCallback - define a callback function ## SYNOPSIS \#include \ vpResult **vpSetCallback(***vpc, option, func***)** - vpContext \**vpc;* - int *option;* - void *(\*func)();* ## ARGUMENTS - *vpc* VolPack context from **vpCreateContext.** - *option* A code specifying which callback function to set. - *func* A pointer to the callback function. ## DESCRIPTION **vpSetCallback** is used to set a callback function. The following list gives the possible values for *option:* - VP\_GRAY\_SHADE\_FUNC The *func* argument is a shading callback function that produces a floating point grayscale pixel intensity. The function should be declared: - void *func*(void \**voxel\_ptr,* float \**i\_ptr*,\ - *voxel\_ptr* Pointer to the beginning of a voxel that must be shaded. - *i\_ptr* Location into which the 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). - *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\_RGB\_SHADE\_FUNC The *func* argument is a shading callback function that produces a floating point RGB pixel intensity. The function should be declared: - void *func*(void \**voxel\_ptr,* float \**r\_ptr*,\ \ - *voxel\_ptr* Pointer to the beginning of a voxel that must be shaded. - *r\_ptr, g\_ptr, b\_ptr* Location into which the 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 The *func* argument is a callback function that takes the same arguments and returns the same result as the [**read**(2)](/read/2.md) system call. This function is 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. - VP\_WRITE\_FUNC The *func* argument is a callback function that takes the same arguments and returns the same result as the [**write**(2)](/write/2.md) system call. This function is 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 The *func* argument is a callback function that is called to memory map data from a file instead of copying the data into memory (see vpLoadRawVolume(3)). The function should be declared: - void \**func*(int *fd,* unsigned *offset,*\ - *fd* File descriptor from [**open**(2)](/open/2.md) 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. - VP\_STATUS\_FUNC The *func* argument is a callback function that is called periodically during long-running operations such as during preprocessing of a volume. The function 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. However, the callback should not make any calls to VolPack functions since the internal VolPack state may be inconsistent. - VP\_LOG\_ALLOC\_FUNC The *func* argument is a callback function that is called whenever VolPack allocates memory. The function should be declared: - void *func*(void \**ptr,* int *size*, char \**use*,\ - *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). - VP\_LOG\_FREE\_FUNC The *func* argument is a callback function that is called whenever VolPack deallocates memory. The function 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). If the *func* argument is NULL then the corresponding callback function is reset to the default behavior or disabled if there is no default behavior. ## ERRORS The normal return value is VP\_OK. The following error return value is possible: - VPERROR\_BAD\_OPTION The *option* argument is invalid. ## SEE ALSO [VolPack(3)](/VolPack/3.md), vpCreateContext(3), vpSetClientData(3), vpSetLookupShader(3), vpLoadRawVolume(3), vpStoreRawVolume(3)