.\" 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 vpGetImage 3 "" VolPack
.SH NAME
vpGetImage \- get a field of the intermediate image
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpGetImage(\fIvpc, image, width, height, scan_bytes,
pixel_type, image_type\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
void *\fIimage;\fR
.FA
int \fIwidth, height;\fR
.FA
int \fIscan_bytes;\fR
.FA
int \fIpixel_type, image_type;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIimage\fR
2D array for storing result image.
.IP \fIwidth\fR
Width of array in pixels.
.IP \fIheight\fR
Height of array in pixels.
.IP \fIscan_bytes\fR
Number of bytes per scanline in array.
.IP \fIpixel_type\fR
Code indicating the format of each pixel in the array.
.IP \fIimage_type\fR
Code indicating the source of the image data (VP_IMAGE_BUFFER or
VP_SHADOW_BUFFER).
.SH DESCRIPTION
This is a debugging function.  It is used to retrieve the contents of
one of the temporary rendering buffers used during rendering, namely
the intermediate image or the shadow buffer.  Rendering consists of
two stages: the volume is resampled and composited into the
intermediate image to produce a distorted volume rendering, and then
the intermediate image is warped into the final image.  If shadows are
enabled then the shadow buffer is used during the first stage to
incrementally compute which voxels are illuminated by the light source.
This function returns images produced during the first stage, before
the final warp.
.PP
This function may be called after a call to one of the rendering
routines (see vpRenderRawVolume(3)).  If the \fIimage_type\fR argument
is VP_IMAGE_BUFFER then data will be copied from the intermediate
image.  The \fIpixel_type\fR argument specifies what information to
copy and the format for storing the data in the output array.  The
possible values for \fIpixel_type\fR are the same as for the
\fIpixel_type\fR argument to \fBvpSetImage.\fR  For instance, use
VP_LUMINANCE to extract the grayscale intensity (assuming the current
shader produces grayscale pixels).
.PP
If the \fIimage_type\fR argument is VP_SHADOW_BUFFER then data will be
copied from the shadow buffer.  The only valid option for
\fIpixel_type\fR is VP_ALPHA, since no color information is stored in
the shadow buffer.
.PP
See \fBvpSetImage\fR for details on the pixel formats, the layout of
the output array, and the remaining arguments.
.PP
To find the required size for the result array, use \fBvpGeti\fR with
the VP_INTERMEDIATE_WIDTH and VP_INTERMEDIATE_HEIGHT options (when
\fIimage_type\fR is VP_IMAGE_BUFFER) or the VP_SHADOW_WIDTH and
VP_SHADOW_HEIGHT options (when \fIimage_type\fR is VP_SHADOW_BUFFER).
.SH ERRORS
The normal return value is VP_OK.  The following error return values
are possible:
.IP VPERROR_BAD_SIZE
The destination array size is incorrect or there is no intermediate image.
.IP VPERROR_BAD_OPTION
The \fIfield\fR argument is invalid.
.SH SEE ALSO
VolPack(3), vpRenderRawVolume(3), vpGeti(3)