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)

VolPack                                                                                     vpScanlineNormals(3)