oracular (3) Load.3.gz

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)