NAME

       vpScanlineNormals - compute surface normal vectors and gradient magnitudes for a scanline

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpScanlineNormals(vpc, length, scalar_data, scalar_minus_y, scalar_plus_y, scalar_minus_z,
               scalar_plus_z, voxel_data, scalar_field, grad_field, norm_field)
           vpContext *vpc;
           int length;
           unsigned char *scalar_data;
           unsigned char *scalar_minus_y, *scalar_plus_y;
           unsigned char *scalar_minus_z, *scalar_plus_z;
           void *voxel_data;
           int scalar_field;
           int grad_field;
           int norm_field;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       length Size of scalar_data array in bytes.

       scalar_data
              1D array of scalar samples.

       scalar_minus_y
              1D array of scalar samples adjacent to scalar_data in the -Y direction.

       scalar_plus_y
              1D array of scalar samples adjacent to scalar_data in the +Y direction.

       scalar_minus_z
              1D array of scalar samples adjacent to scalar_data in the -Z direction.

       scalar_plus_z
              1D array of scalar samples adjacent to scalar_data in the +Z direction.

       voxel_data
              1D array of voxels for storing results.

       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

       vpScanlineNormals is used to precompute values for voxel fields used in classification and
       shading algorithms.  The input is a collection of 5 adjacent 1D arrays of scalar values; a
       separate routine  is  provided  for  processing  a  full  3D  array  of  voxel  data  (see
       vpVolumeNormals(3)).   vpScanlineNormals  is  useful for loading large volumes into memory
       scanline-by-scanline and precomputing voxel fields incrementally,  instead  of  loading  a
       complete  copy  of  the  3D  scalar  array  in  addition to the voxel array.  In all other
       respects this routine is identical in function to vpVolumeNormals.

       The 1D scalar arrays must be arrays  of  8-bit  values  (other  sizes  are  not  currently
       supported).   The  length  parameter indicates both the size and the number of elements in
       each of the scalar  arrays.   vpScanlineNormals  performs  the  computation  described  in
       vpVolumeNormals(3),  but only for the single scanline specified by scalar_data.  The other
       four scanline arguments must be the immediately adjacent scanlines and are used to compute
       the gradient.

       The  results  are stored in the voxel_data array which must have space for the same number
       of voxels as the length of one scalar scanline.  The size of a  voxel  must  be  specified
       with  vpSetVoxelSize  before  calling  vpScanlineNormals,  but it is not necessary to call
       vpSetRawVoxels.  The arguments scalar_field, grad_field and norm_field specify which voxel
       fields  the  computed quantities should be stored into.  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_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.

SEE ALSO

       VolPack(3),        vpCreateContext(3),        vpNormalIndex(3),        vpVolumeNormals(3),
       vpSetClassifierTable(3), vpSetLookupShader(3)