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)