# vpScanlineNormals man page

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)

## Referenced By

VolPack(3), vpNormalIndex(3), vpSetVoxelField(3), vpVolumeNormals(3).