DragonFly On-Line Manual Pages

vpVolumeNormals(3)    DragonFly Library Functions Manual    vpVolumeNormals(3)

NAME
       vpVolumeNormals - compute surface normal vectors and gradient
       magnitudes for a volume

SYNOPSIS
       #include <volpack.h>

       vpResult
       vpVolumeNormals(vpc, scalar_data, length, scalar_field, grad_field,
               norm_field)
           vpContext *vpc;
           unsigned char *scalar_data;
           int length;
           int scalar_field;
           int grad_field;
           int norm_field;

ARGUMENTS
       vpc    VolPack context from vpCreateContext.

       scalar_data
              3D array of scalar samples.

       length Size of scalar_data array in bytes.

       scalar_field
              Voxel field number indicating the field in which to store the
              scalar samples.

       grad_field
              Voxel field number indicating the field in which to store the
              gradient magnitudes of the scalar samples.

       norm_field
              Voxel field number indicating the field in which to store
              encoded surface normal vectors.

DESCRIPTION
       vpVolumeNormals is used to precompute values for voxel fields used in
       classification and shading algorithms.  The input is a 3D array of
       scalar values; a separate routine is provided for processing scanlines
       of voxel data (see vpScanlineNormals(3)).  For each voxel, the routine
       computes an approximation for the gradient of the scalar field (using a
       central-difference operator).  From this vector the routine can compute
       the magnitude of the gradient, which is useful for some classification
       schemes (see vpSetClassifierTable(3)), and a surface normal vector in
       the direction of the gradient vector, which is used to implement
       lighting models (see vpShadeTable(3)).  The scalar value, gradient
       magnitude and surface normal vector are then stored into the fields of
       the voxel array, which is separate from the array of scalar values.

       The scalar array must be an array of 8-bit values (other sizes are not
       currently supported).  The dimensions of the array must match the
       volume dimensions previously specified with vpSetVolumeSize.  The size
       argument is used to make sure the array has the correct size.  The
       voxel array must also be initialized by calling vpSetRawVoxels prior to
       calling vpVolumeNormals.

       The three voxel field number arguments indicate which voxel fields the
       computed information should be stored into, and which field the scalar
       samples should be copied to.  The field numbers must correspond to
       appropriately-sized voxel fields previously specified with
       vpSetVoxelField.  Any of these arguments can be the constant
       VP_SKIP_FIELD, in which case the corresponding quantity is not computed
       or copied.  The voxel fields for the scalar value and the gradient
       magnitude must be one-byte fields, and the field for the surface normal
       vector must be a two-byte field.  The constants VP_SCALAR_MAX,
       VP_GRAD_MAX and VP_NORM_MAX give the maximum value that might be stored
       in each field, respectively.  The value stored in the surface normal
       vector field is actually an encoded surface normal; see
       vpNormalIndex(3).

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

       VPERROR_BAD_SIZE
              The size of the scalar array does not match the volume
              dimensions.

       VPERROR_BAD_VALUE
              One or more of the voxel fields specified is invalid, or the
              corresponding voxel field has the wrong size.

       VPERROR_BAD_VOXEL
              The voxel size or the voxel fields have not been specified or
              have been incorrectly specified.

       VPERROR_BAD_VOLUME
              The volume array or volume dimensions have not been specified,
              or the size of the volume array does not match the volume
              dimensions.

SEE ALSO
       VolPack(3), vpCreateContext(3), vpNormalIndex(3), vpScanlineNormals(3),
       vpSetClassifierTable(3), vpSetLookupShader(3)

VolPack                                                     vpVolumeNormals(3)