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)