Man Linux: Main Page and Category List

NAME

       vpSetCallback - define a callback function

SYNOPSIS

       #include <volpack.h>

       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,
                            void *client_data);

              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,
                            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
                     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) 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)  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,
                             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.

       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,
                            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).

       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),           vpCreateContext(3),           vpSetClientData(3),
       vpSetLookupShader(3), vpLoadRawVolume(3), vpStoreRawVolume(3)