.\" Copyright (c) 1994 The Board of Trustees of The Leland Stanford .\" Junior University. All rights reserved. .\" .\" Permission to use, copy, modify and distribute this software and its .\" documentation for any purpose is hereby granted without fee, provided .\" that the above copyright notice and this permission notice appear in .\" all copies of this software and that you do not sell the software. .\" Commercial licensing is available by contacting the author. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTY OF ANY KIND, .\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY .\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. .\" .\" Author: .\" Phil Lacroute .\" Computer Systems Laboratory .\" Electrical Engineering Dept. .\" Stanford University .\" .\" $Date: 1994/12/31 19:49:53 $ .\" $Revision: 1.1 $ .\" .\" Macros .\" .FS -- function start .\" is return type of function .\" name and arguments follow on next line .de FS .PD 0v .PP \\$1 .HP 8 .. .\" .FA -- function arguments .\" one argument declaration follows on next line .de FA .IP " " 4 .. .\" .FE -- function end .\" end of function declaration .de FE .PD .. .\" .DS -- display start .de DS .IP " " 4 .. .\" .DE -- display done .de DE .LP .. .TH vpScanlineNormals 3 "" VolPack .SH NAME vpScanlineNormals \- compute surface normal vectors and gradient magnitudes for a scanline .SH SYNOPSIS #include .sp .FS vpResult \fBvpScanlineNormals(\fIvpc, length, scalar_data, scalar_minus_y, scalar_plus_y, scalar_minus_z, scalar_plus_z, voxel_data, scalar_field, grad_field, norm_field\fB)\fR .FA vpContext *\fIvpc;\fR .FA int \fIlength;\fR .FA unsigned char *\fIscalar_data;\fR .FA unsigned char *\fIscalar_minus_y,\fR *\fIscalar_plus_y;\fR .FA unsigned char *\fIscalar_minus_z,\fR *\fIscalar_plus_z;\fR .FA void *\fIvoxel_data;\fR .FA int \fIscalar_field;\fR .FA int \fIgrad_field;\fR .FA int \fInorm_field;\fR .FE .SH ARGUMENTS .IP \fIvpc\fR VolPack context from \fBvpCreateContext.\fR .IP \fIlength\fR Size of \fIscalar_data\fR array in bytes. .IP \fIscalar_data\fR 1D array of scalar samples. .IP \fIscalar_minus_y\fR 1D array of scalar samples adjacent to \fIscalar_data\fR in the -Y direction. .IP \fIscalar_plus_y\fR 1D array of scalar samples adjacent to \fIscalar_data\fR in the +Y direction. .IP \fIscalar_minus_z\fR 1D array of scalar samples adjacent to \fIscalar_data\fR in the -Z direction. .IP \fIscalar_plus_z\fR 1D array of scalar samples adjacent to \fIscalar_data\fR in the +Z direction. .IP \fIvoxel_data\fR 1D array of voxels for storing results. .IP \fIscalar_field\fR Voxel field number indicating the field in which to store the scalar samples. .IP \fIgrad_field\fR Voxel field number indicating the field in which to store the gradient magnitudes of the scalar samples. .IP \fInorm_field\fR Voxel field number indicating the field in which to store encoded surface normal vectors. .SH DESCRIPTION \fBvpScanlineNormals\fR 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)). \fBvpScanlineNormals\fR 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 \fBvpVolumeNormals\fR. .PP The 1D scalar arrays must be arrays of 8-bit values (other sizes are not currently supported). The \fIlength\fR parameter indicates both the size and the number of elements in each of the scalar arrays. \fBvpScanlineNormals\fR performs the computation described in vpVolumeNormals(3), but only for the single scanline specified by \fIscalar_data\fR. The other four scanline arguments must be the immediately adjacent scanlines and are used to compute the gradient. .PP The results are stored in the \fIvoxel_data\fR 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 \fBvpSetVoxelSize\fR before calling \fBvpScanlineNormals,\fR but it is not necessary to call \fBvpSetRawVoxels.\fR The arguments \fIscalar_field, grad_field\fR and \fInorm_field\fR specify which voxel fields the computed quantities should be stored into. The field numbers must correspond to appropriately-sized voxel fields previously specified with \fBvpSetVoxelField\fR. 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). .SH ERRORS The normal return value is VP_OK. The following error return values are possible: .IP VPERROR_BAD_VALUE One or more of the voxel fields specified is invalid, or the corresponding voxel field has the wrong size. .IP VPERROR_BAD_VOXEL The voxel size or the voxel fields have not been specified or have been incorrectly specified. .SH SEE ALSO VolPack(3), vpCreateContext(3), vpNormalIndex(3), vpVolumeNormals(3), vpSetClassifierTable(3), vpSetLookupShader(3)