1vpSetCallback(3)           Library Functions Manual           vpSetCallback(3)
2
3
4

NAME

6       vpSetCallback - define a callback function
7

SYNOPSIS

9       #include <volpack.h>
10
11       vpResult
12       vpSetCallback(vpc, option, func)
13           vpContext *vpc;
14           int option;
15           void (*func)();
16

ARGUMENTS

18       vpc    VolPack context from vpCreateContext.
19
20       option A code specifying which callback function to set.
21
22       func   A pointer to the callback function.
23

DESCRIPTION

25       vpSetCallback  is  used to set a callback function.  The following list
26       gives the possible values for option:
27
28       VP_GRAY_SHADE_FUNC
29              The func argument is a shading callback function that produces a
30              floating  point  grayscale pixel intensity.  The function should
31              be declared:
32              void func(void *voxel_ptr, float *i_ptr,
33                        void *client_data);
34
35              voxel_ptr
36                     Pointer to the beginning of a voxel that must be shaded.
37
38              i_ptr  Location  into  which  the  function  should  store   the
39                     grayscale intensity result.  It should be a single-preci‐
40                     sion floating point in  the  range  0.0  (black)  to  1.0
41                     (white).
42
43              client_data
44                     Pointer  to  the  application-defined  client  data  (see
45                     vpSetClientData(3)).
46
47              The callback can be used to implement  custom  shading  routines
48              that  cannot  be  implemented  with  a lookup table.  See vpSet‐
49              LookupShader(3) for more information.
50
51       VP_RGB_SHADE_FUNC
52              The func argument is a shading callback function that produces a
53              floating  point  RGB  pixel  intensity.   The function should be
54              declared:
55              void func(void *voxel_ptr, float *r_ptr,
56                        float *r_ptr, float *r_ptr,
57                        void *client_data);
58
59              voxel_ptr
60                     Pointer to the beginning of a voxel that must be shaded.
61
62              r_ptr, g_ptr, b_ptr
63                     Location into which the function  should  store  the  RGB
64                     intensities  of  the  result.  Each intensity should be a
65                     single-precision floating point  in  the  range  0.0  (no
66                     intensity) to 1.0 (full intensity).
67
68              client_data
69                     Pointer  to  the  application-defined  client  data  (see
70                     vpSetClientData(3)).
71
72              The callback can be used to implement  custom  shading  routines
73              that  cannot  be  implemented  with  a lookup table.  See vpSet‐
74              LookupShader(3) for more information.
75
76       VP_READ_FUNC
77              The func argument is a callback function  that  takes  the  same
78              arguments  and  returns  the  same  result as the read(2) system
79              call.  This function is  used  to  read  data  from  files  (see
80              vpLoadRawVolume(3)).   By default, the read system call is used.
81              The callback can be used to implement a  custom  I/O  interface,
82              for example a compression/decompression system.
83
84       VP_WRITE_FUNC
85              The  func  argument  is  a callback function that takes the same
86              arguments and returns the same result  as  the  write(2)  system
87              call.  This function is used to write data to files (see vpStor‐
88              eRawVolume(3)).  By default, the write system call is used.  The
89              callback  can  be  used to implement a custom I/O interface, for
90              example a compression/decompression system.
91
92       VP_MMAP_FUNC
93              The func argument is a callback function that is called to  mem‐
94              ory map data from a file instead of copying the data into memory
95              (see vpLoadRawVolume(3)).  The function should be declared:
96              void *func(int fd, unsigned offset,
97                         void *client_data);
98
99              fd     File descriptor from open(2) open for reading.
100
101              offset Byte offset in the file to the beginning of the memory to
102                     be mapped.
103
104              client_data
105                     Pointer  to  the  application-defined  client  data  (see
106                     vpSetClientData(3)).
107
108              The function should map the entire file into memory and return a
109              pointer to the memory location that corresponds to the file off‐
110              set.  By default, memory mapping is disabled.
111
112
113       VP_STATUS_FUNC
114              The func argument is a callback function that is called periodi‐
115              cally  during long-running operations such as during preprocess‐
116              ing of a volume.  The function should be declared:
117              void func(double frac, void *client_data);
118
119              frac   An estimate of the fraction of the current operation that
120                     is complete.
121
122              client_data
123                     Pointer to the client data associated with the context.
124
125              The  callback can be used to print a status report or to process
126              time-critical events such as user input.  However, the  callback
127              should  not make any calls to VolPack functions since the inter‐
128              nal VolPack state may be inconsistent.
129
130       VP_LOG_ALLOC_FUNC
131              The func argument is a callback function that is called whenever
132              VolPack allocates memory.  The function should be declared:
133              void func(void *ptr, int size, char *use,
134                        int line, char *file, void *client_data);
135
136              ptr    Address of the allocated memory.
137
138              size   Size (in bytes) of the allocated memory.
139
140              use    Short description of the use of the allocated memory.
141
142              line   Source  code line number for the call to the memory allo‐
143                     cator.
144
145              file   Source code file name for the call to the memory  alloca‐
146                     tor.
147
148              client_data
149                     Pointer to the client data associated with the context.
150
151              The  callback can be used to track memory allocations (primarily
152              for debugging memory leaks).
153
154       VP_LOG_FREE_FUNC
155              The func argument is a callback function that is called whenever
156              VolPack deallocates memory.  The function should be declared:
157              void func(void *ptr, void *client_data)
158
159              ptr    Address of the deallocated memory.
160
161              client_data
162                     Pointer to the client data associated with the context.
163
164              The  callback can be used to track memory deallocations (primar‐
165              ily for debugging memory leaks).
166
167       If the func argument is NULL then the corresponding  callback  function
168       is  reset  to  the  default behavior or disabled if there is no default
169       behavior.
170

ERRORS

172       The normal return value is VP_OK.  The following error return value  is
173       possible:
174
175       VPERROR_BAD_OPTION
176              The option argument is invalid.
177

SEE ALSO

179       VolPack(3),    vpCreateContext(3),   vpSetClientData(3),   vpSetLookup‐
180       Shader(3), vpLoadRawVolume(3), vpStoreRawVolume(3)
181
182
183
184VolPack                                                       vpSetCallback(3)
Impressum