NAME

       vpSetVoxelSize - define the size of a voxel

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpSetVoxelSize(vpc,       bytes_per_voxel,       num_voxel_fields,       num_shade_fields,
               num_classify_fields)
           vpContext *vpc;
           int bytes_per_voxel;
           int num_voxel_fields;
           int num_shade_fields;
           int num_classify_fields;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       bytes_per_voxel
              Size of one voxel in bytes.

       num_voxel_fields
              Number of fields in a voxel.

       num_shade_fields
              Number of voxel fields that are arguments to the shading function.

       num_classify_fields
              Number of voxel fields that are arguments to the opacity transfer function.

DESCRIPTION

       vpSetVoxelSize is used to define the size in bytes and the number of fields  in  a  voxel.
       Each  voxel  field is analogous to a field in a C structure and the contents of each field
       is user-defined.  See the vpSetVoxelField function (vpSetVoxelField(3))  for  setting  the
       size and offset of each field.  vpSetVoxelSize should be called before vpSetVoxelField and
       before any functions that access the contents of a voxel.

       Typically, some of the voxel fields are used as arguments to a shading function  and  some
       (possibly  the  same)  fields  are  used as arguments to an opacity transfer function (for
       classification).  The fields that are used for shading should come first, i.e. they should
       have  the  smallest offsets, followed by any fields that are only used for classification.
       The classification fields can then be stripped off to save space during the precomputation
       stage  for  the  fast  rendering  algorithm.  The parameter num_shade_fields indicates the
       number of fields (starting from the first) that must not be stripped off.

       The parameter num_clsfy_fields indicates the total number  of  fields  that  are  used  as
       parameters  to  the opacity transfer function.  These fields do not necessarily have to be
       contiguous, although any fields that are not also used for  shading  should  be  the  last
       fields in the voxel.

       If the call to vpSetVoxelSize succeeds, any existing precomputed volume data structures in
       the context are destroyed.

STATE VARIABLES

       The current voxel size parameters can be retrieved with the following state variable codes
       (see    vpGeti(3)):    VP_BYTES_PER_VOXEL,   VP_VOXEL_FIELD_COUNT,   VP_SHADE_FIELD_COUNT,
       VP_CLASSIFY_FIELD_COUNT.

ERRORS

       The normal return value is VP_OK.  The following error return values are possible:

       VPERROR_LIMIT_EXCEEDED
              The number of voxel fields exceeds the implementation limit.   This  limit  can  be
              increased by editing volpack.h and recompiling the library.

       VPERROR_BAD_VALUE
              Either num_clsfy_fields or num_shade_fields is out of range.

SEE ALSO

       VolPack(3), vpCreateContext(3), vpSetVoxelField(3)