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)

VolPack                                                                                       vpLoadRawVolume(3)