.\" 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 <type>  --  function start
.\"     <type> 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 vpSetRawVoxels 3 "" VolPack
.SH NAME
vpSetRawVoxels \- specify an array of volume data
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpSetRawVoxels(\fIvpc, voxels, size, xstride, ystride, zstride\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
void *\fIvoxels;\fR
.FA
int \fIsize;\fR
.FA
int \fIxstride, ystride, zstride;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIvoxels\fR
3D array of voxels.
.IP \fIsize\fR
Size of the voxel array in bytes.
.IP \fIxstride\fR
Number of bytes from the beginning of one voxel to the beginning of
the next voxel in the first array dimension.
.IP \fIystride\fR
Number of bytes from the beginning of one voxel to the beginning of
the next voxel in the second array dimension.
.IP \fIzstride\fR
Number of bytes from the beginning of one voxel to the beginning of
the next voxel in the third array dimension.
.SH DESCRIPTION
\fBvpSetRawVoxels\fR is used to specify a 3D array that contains the
volume data.  The array must be large enough for the volume dimensions
specified with \fBvpSetVolumeSize\fR and the voxel size specified with
\fBvpSetVoxelSize\fR.  The data in the array may be initialized before
or after calling \fBvpSetRawVoxels\fR.
.PP
Some of the VolPack routines operate faster if the volume is stored in
z-major order (\fIxstride < ystride < zstride\fR) but it is not
strictly necessary.
.PP
The voxel array is not automatically deallocated when the context is
destroyed with \fBvpDestroyContext\fR.  The application is responsible
for managing the memory associated with the volume array.
.PP
The voxel array can be a very large data structure, possibly larger
than available main memory.  It is sometimes possible to precompute
the optimized data structures required for the fast rendering
algorithm without explicitly allocating a voxel array.  See
vpClassifyScalars(3).
.PP
During the call to \fBvpSetRawVoxels\fR, any existing precomputed
volume data structures in the context are destroyed.
.SH "STATE VARIABLES"
The current voxel array parameters can be retrieved with the following
state variable codes (see vpGeti(3)): VP_VOXEL_DATA, VP_VOXEL_DATA_SIZE,
VP_VOXEL_XSTRIDE, VP_VOXEL_YSTRIDE, VP_VOXEL_ZSTRIDE.
.SH ERRORS
The routine always returns VP_OK.
.SH SEE ALSO
VolPack(3), vpCreateContext(3)