.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford .\" Junior University. All rights reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation for any purpose is hereby granted without fee, provided .\" that the above copyright notice and this permission notice appear in .\" all copies of this software and that you do not sell the software. .\" Commercial licensing is available by contacting the author. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. .\" .\" Author: .\" Phil Lacroute .\" Computer Systems Laboratory .\" Electrical Engineering Dept. .\" Stanford University .\" .\" $Date: 1994/12/31 19:49:53 $ .\" $Revision: 1.1 $ .\" .\" Macros .\" .FS -- function start .\" is return type of function .\" name and arguments follow on next line .de FS .PD 0v .PP \\$1 .HP 8 .. .\" .FA -- function arguments .\" one argument declaration follows on next line .de FA .IP " " 4 .. .\" .FE -- function end .\" end of function declaration .de FE .PD .. .\" .DS -- display start .de DS .IP " " 4 .. .\" .DE -- display done .de DE .LP .. .TH vpSetCallback 3 "" VolPack .SH NAME vpSetCallback \- define a callback function .SH SYNOPSIS #include .sp .FS vpResult \fBvpSetCallback(\fIvpc, option, func\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIoption;\fR .FA void \fI(*func)();\fR .FE .SH ARGUMENTS .IP \fIvpc\fR VolPack context from \fBvpCreateContext.\fR .IP \fIoption\fR A code specifying which callback function to set. .IP \fIfunc\fR A pointer to the callback function. .SH DESCRIPTION \fBvpSetCallback\fR is used to set a callback function. The following list gives the possible values for \fIoption:\fR .IP VP_GRAY_SHADE_FUNC The \fIfunc\fR argument is a shading callback function that produces a floating point grayscale pixel intensity. The function should be declared: .RS .DS void \fIfunc\fR(\kxvoid *\fIvoxel_ptr,\fR float *\fIi_ptr\fR, .br \h.\nxu'void *\fIclient_data\fR); .DE .IP \fIvoxel_ptr\fR Pointer to the beginning of a voxel that must be shaded. .IP \fIi_ptr\fR 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). .IP \fIclient_data\fR Pointer to the application-defined client data (see vpSetClientData(3)). .PP The callback can be used to implement custom shading routines that cannot be implemented with a lookup table. See vpSetLookupShader(3) for more information. .RE .IP VP_RGB_SHADE_FUNC The \fIfunc\fR argument is a shading callback function that produces a floating point RGB pixel intensity. The function should be declared: .RS .DS void \fIfunc\fR(\kxvoid *\fIvoxel_ptr,\fR float *\fIr_ptr\fR, .br \h.\nxu'float *\fIr_ptr\fR, float *\fIr_ptr\fR, .br \h.\nxu'void *\fIclient_data\fR); .DE .IP \fIvoxel_ptr\fR Pointer to the beginning of a voxel that must be shaded. .IP "\fIr_ptr, g_ptr, b_ptr\fR" 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). .IP \fIclient_data\fR Pointer to the application-defined client data (see vpSetClientData(3)). .PP The callback can be used to implement custom shading routines that cannot be implemented with a lookup table. See vpSetLookupShader(3) for more information. .RE .IP VP_READ_FUNC The \fIfunc\fR argument is a callback function that takes the same arguments and returns the same result as the \fBread\fR(2) system call. This function is used to read data from files (see vpLoadRawVolume(3)). By default, the \fBread\fR system call is used. The callback can be used to implement a custom I/O interface, for example a compression/decompression system. .IP VP_WRITE_FUNC The \fIfunc\fR argument is a callback function that takes the same arguments and returns the same result as the \fBwrite\fR(2) system call. This function is used to write data to files (see vpStoreRawVolume(3)). By default, the \fBwrite\fR system call is used. The callback can be used to implement a custom I/O interface, for example a compression/decompression system. .IP VP_MMAP_FUNC The \fIfunc\fR 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: .RS .DS void *\fIfunc\fR(\kxint \fIfd,\fR unsigned \fIoffset,\fR .br \h.\nxu'void *\fIclient_data\fR); .DE .IP \fIfd\fR File descriptor from \fBopen\fR(2) open for reading. .IP \fIoffset\fR Byte offset in the file to the beginning of the memory to be mapped. .IP \fIclient_data\fR Pointer to the application-defined client data (see vpSetClientData(3)). .PP 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. .RE .IP VP_STATUS_FUNC The \fIfunc\fR 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: .RS .DS void \fIfunc\fR(double \fIfrac\fR, void *\fIclient_data\fR); .DE .IP \fIfrac\fR An estimate of the fraction of the current operation that is complete. .IP \fIclient_data\fR Pointer to the client data associated with the context. .PP 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. .RE .IP VP_LOG_ALLOC_FUNC The \fIfunc\fR argument is a callback function that is called whenever VolPack allocates memory. The function should be declared: .RS .DS void \fIfunc\fR(\kxvoid *\fIptr,\fR int \fIsize\fR, char *\fIuse\fR, .br \h.\nxu'int \fIline\fR, char *\fIfile\fR, void *\fIclient_data\fR); .DE .IP \fIptr\fR Address of the allocated memory. .IP \fIsize\fR Size (in bytes) of the allocated memory. .IP \fIuse\fR Short description of the use of the allocated memory. .IP \fIline\fR Source code line number for the call to the memory allocator. .IP \fIfile\fR Source code file name for the call to the memory allocator. .IP \fIclient_data\fR Pointer to the client data associated with the context. .PP The callback can be used to track memory allocations (primarily for debugging memory leaks). .RE .IP VP_LOG_FREE_FUNC The \fIfunc\fR argument is a callback function that is called whenever VolPack deallocates memory. The function should be declared: .RS .DS void \fIfunc\fR(void *\fIptr\fR, void *\fIclient_data\fR) .DE .IP \fIptr\fR Address of the deallocated memory. .IP \fIclient_data\fR Pointer to the client data associated with the context. .PP The callback can be used to track memory deallocations (primarily for debugging memory leaks). .RE .PP If the \fIfunc\fR argument is NULL then the corresponding callback function is reset to the default behavior or disabled if there is no default behavior. .SH ERRORS The normal return value is VP_OK. The following error return value is possible: .IP VPERROR_BAD_OPTION The \fIoption\fR argument is invalid. .SH SEE ALSO VolPack(3), vpCreateContext(3), vpSetClientData(3), vpSetLookupShader(3), vpLoadRawVolume(3), vpStoreRawVolume(3)