NAME
vpLoadRawVolume, vpLoadMinMaxOctree, vpLoadClassifiedVolume,
vpLoadContext - load volume data structures from a file
SYNOPSIS
#include <volpack.h>
vpResult
vpLoadRawVolume(vpc, fd)
vpContext *vpc;
int fd;
vpResult
vpLoadMinMaxOctree(vpc, fd)
vpContext *vpc;
int fd;
vpResult
vpLoadClassifiedVolume(vpc, fd)
vpContext *vpc;
int fd;
vpResult
vpLoadContext(vpc, fd)
vpContext *vpc;
int fd;
ARGUMENTS
vpc VolPack context from vpCreateContext.
fd File descriptor from open(2), open for reading.
DESCRIPTION
These functions are used to load volume data structures into a
rendering context from files in the format written by the VolPack file
storing routines (see vpStoreRawVolume(3)).
vpLoadRawVolume loads a 3D voxel array file. The file includes
information about the size of the volume and the layout of the voxels
as well as the volume data itself. A new voxel array is allocated, the
data is read into the array, and the array is stored in the rendering
context. Note that the array will not be freed automatically when the
context is destroyed; the application is responsible for freeing the
array when appropriate (by using vpGetp with the VP_VOXEL_DATA state
variable code to retrieve the array pointer), or for unmapping the
voxel array if it has been memory mapped (see below).
Any existing min-max octree or preclassified volume data is destroyed
when vpLoadRawVolume is called. The information loaded from the file
includes all of the parameters set with vpSetVolumeSize,
vpSetVoxelSize, vpSetVoxelField and vpSetRawVoxels. The data in the
file is automatically byte-swapped if the file was written on an
architecture with different byte ordering than the current
architecture. A magic constant in the file is used to determine if
byte-swapping is necessary. Volume fields that have not been
explicitly declared (by calling vpSetVoxelField before storing the
voxel array file) cannot be byte-swapped.
vpLoadMinMaxOctree loads a min-max octree file. The current 3D voxel
array size and voxel layout must match the data in the octree file
before the file is loaded; consistency checks are performed. Any
existing octree is destroyed and the new octree is stored in the
rendering context. Byte-swapping is performed if necessary.
vpLoadClassifiedVolume loads a preclassified volume data file. The
file includes information about the size of the volume and the layout
of the voxels as well as the volume data itself. If the volume matches
the size and layout of any existing volume data in the rendering
context then the data in the file replaces only the current
preclassified volume; otherwise, the old octree is destroyed, the 3D
voxel array parameters are zeroed out, and the new size and layout
parameters are loaded. The information loaded from the file includes
all of the parameters set with vpSetVolumeSize, vpSetVoxelSize and
vpSetVoxelField. Byte-swapping is performed if necessary.
vpLoadContext loads a rendering context file. The file includes all
rendering parameters except volume data and callback functions. The
contents of any lookup tables for shading and classification are also
loaded. Any existing preclassified volume data or octree are destroyed
and the 3D voxel array parameters pointer is zeroed out. The lookup
tables are loaded into dynamically allocated arrays, and the
application is responsible for freeing those array when necessary; the
arrays are not automatically freed when vpDestroyContext is called. In
the current implementation byte swapping is not performed so context
files from other architectures cannot be read.
The function used to read data from the files can be set by calling
vpSetCallback with the VP_READ_FUNC option. This could be used to
implement a file-compression system, for example. It is also possible
to memory-map data from files by setting the VP_MMAP_FUNC option. If
this function is set then large data structures are memory mapped from
files instead of being copied into memory, when possible. Data that
must be byte-swapped cannot be memory mapped. Memory mapping has the
advantages that less swap space is required and data is loaded into
memory only as it is used.
STATE VARIABLES
The current file I/O parameters can be retrieved with the following
state variable codes (see vpGeti(3)): VP_READ_FUNC, VP_MMAP_FUNC.
ERRORS
The normal return value is VP_OK. The following error return values
are possible:
VPERROR_IO
The file reading or memory mapping function returned an error
value (in which case the external variable errno should contain
an operating-system specific error code), or the end of the file
was reached prematurely.
VPERROR_BAD_FILE
The data in the file is invalid, usually meaning that it isn’t a
file written by the appropriate VolPack function.
VPERROR_BAD_VOLUME
The data in a min-max octree file does not match the current
volume size (vpLoadMinMaxOctree only).
VPERROR_BAD_VOXEL
The data in a min-max octree file does not match the current
voxel layout parameters (vpLoadMinMaxOctree only).
SEE ALSO
VolPack(3), vpCreateContext(3), vpStoreRawVolume(3)