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)