1vpLoadRawVolume(3) Library Functions Manual vpLoadRawVolume(3)
2
6 vpLoadRawVolume, vpLoadMinMaxOctree, vpLoadClassifiedVolume, vpLoadCon‐
7 text - load volume data structures from a file
8
10 #include <volpack.h>
11 vpResult
13 vpLoadRawVolume(vpc, fd)
14 vpContext *vpc;
15 int fd;
16 vpResult
18 vpLoadMinMaxOctree(vpc, fd)
19 vpContext *vpc;
20 int fd;
21 vpResult
23 vpLoadClassifiedVolume(vpc, fd)
24 vpContext *vpc;
25 int fd;
26 vpResult
28 vpLoadContext(vpc, fd)
29 vpContext *vpc;
30 int fd;
31
33 vpc VolPack context from vpCreateContext.
34 fd File descriptor from open(2), open for reading.
36
38 These functions are used to load volume data structures into a render‐
39 ing context from files in the format written by the VolPack file stor‐
40 ing routines (see vpStoreRawVolume(3)).
41 vpLoadRawVolume loads a 3D voxel array file. The file includes infor‐
43 mation about the size of the volume and the layout of the voxels as
44 well as the volume data itself. A new voxel array is allocated, the
45 data is read into the array, and the array is stored in the rendering
46 context. Note that the array will not be freed automatically when the
47 context is destroyed; the application is responsible for freeing the
48 array when appropriate (by using vpGetp with the VP_VOXEL_DATA state
49 variable code to retrieve the array pointer), or for unmapping the
50 voxel array if it has been memory mapped (see below).
51 Any existing min-max octree or preclassified volume data is destroyed
53 when vpLoadRawVolume is called. The information loaded from the file
54 includes all of the parameters set with vpSetVolumeSize, vpSetVoxel‐
55 Size, vpSetVoxelField and vpSetRawVoxels. The data in the file is
56 automatically byte-swapped if the file was written on an architecture
57 with different byte ordering than the current architecture. A magic
58 constant in the file is used to determine if byte-swapping is neces‐
59 sary. Volume fields that have not been explicitly declared (by calling
60 vpSetVoxelField before storing the voxel array file) cannot be byte-
61 swapped.
62 vpLoadMinMaxOctree loads a min-max octree file. The current 3D voxel
64 array size and voxel layout must match the data in the octree file
65 before the file is loaded; consistency checks are performed. Any
66 existing octree is destroyed and the new octree is stored in the ren‐
67 dering context. Byte-swapping is performed if necessary.
68 vpLoadClassifiedVolume loads a preclassified volume data file. The
70 file includes information about the size of the volume and the layout
71 of the voxels as well as the volume data itself. If the volume matches
72 the size and layout of any existing volume data in the rendering con‐
73 text then the data in the file replaces only the current preclassified
74 volume; otherwise, the old octree is destroyed, the 3D voxel array
75 parameters are zeroed out, and the new size and layout parameters are
76 loaded. The information loaded from the file includes all of the
77 parameters set with vpSetVolumeSize, vpSetVoxelSize and vpSetVox‐
78 elField. Byte-swapping is performed if necessary.
79 vpLoadContext loads a rendering context file. The file includes all
81 rendering parameters except volume data and callback functions. The
82 contents of any lookup tables for shading and classification are also
83 loaded. Any existing preclassified volume data or octree are destroyed
84 and the 3D voxel array parameters pointer is zeroed out. The lookup
85 tables are loaded into dynamically allocated arrays, and the applica‐
86 tion is responsible for freeing those array when necessary; the arrays
87 are not automatically freed when vpDestroyContext is called. In the
88 current implementation byte swapping is not performed so context files
89 from other architectures cannot be read.
90 The function used to read data from the files can be set by calling
92 vpSetCallback with the VP_READ_FUNC option. This could be used to
93 implement a file-compression system, for example. It is also possible
94 to memory-map data from files by setting the VP_MMAP_FUNC option. If
95 this function is set then large data structures are memory mapped from
96 files instead of being copied into memory, when possible. Data that
97 must be byte-swapped cannot be memory mapped. Memory mapping has the
98 advantages that less swap space is required and data is loaded into
99 memory only as it is used.
100
102 The current file I/O parameters can be retrieved with the following
103 state variable codes (see vpGeti(3)): VP_READ_FUNC, VP_MMAP_FUNC.
104
106 The normal return value is VP_OK. The following error return values
107 are possible:
108 VPERROR_IO
110 The file reading or memory mapping function returned an error
111 value (in which case the external variable errno should contain
112 an operating-system specific error code), or the end of the file
113 was reached prematurely.
114 VPERROR_BAD_FILE
116 The data in the file is invalid, usually meaning that it isn't a
117 file written by the appropriate VolPack function.
118 VPERROR_BAD_VOLUME
120 The data in a min-max octree file does not match the current
121 volume size (vpLoadMinMaxOctree only).
122 VPERROR_BAD_VOXEL
124 The data in a min-max octree file does not match the current
125 voxel layout parameters (vpLoadMinMaxOctree only).
126
128 VolPack(3), vpCreateContext(3), vpStoreRawVolume(3)
129VolPack vpLoadRawVolume(3)