.\" 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 vpSetImage 3 "" VolPack
.SH NAME
vpSetImage \- specify an image array
.SH SYNOPSIS
#include <volpack.h>
.sp
.FS vpResult
\fBvpSetImage(\fIvpc, image, width, height, scan_bytes, pixel_type\fB)\fR
.FA
vpContext *\fIvpc;\fR
.FA
unsigned char *\fIimage;\fR
.FA
int \fIwidth, height;\fR
.FA
int \fIscan_bytes;\fR
.FA
int \fIpixel_type;\fR
.FE
.SH ARGUMENTS
.IP \fIvpc\fR
VolPack context from \fBvpCreateContext.\fR
.IP \fIimage\fR
2D array for storing result images.
.IP \fIwidth\fR
Width of image in pixels.
.IP \fIheight\fR
Height of image in pixels.
.IP \fIscan_bytes\fR
Number of bytes per scanline in image array.
.IP \fIpixel_type\fR
Code indicating the format of each pixel in the array.
.SH DESCRIPTION
\fBvpSetImage\fR is used to specify a buffer for storing the result
image during rendering.  The \fIwidth\fR and \fIheight\fR parameters
specify the size of the result image.  The clipping window (see
vpWindow(3) or vpWindowPHIGS(3)) is scaled to exactly match the specified
size.  The \fIscan_bytes\fR argument specifies the size of a scanline
in the image array, in bytes.  This argument can be used to add
padding to the end of each scanline to satisfy alignment
restrictions (e.g.\ raster operations sometimes require the beginning
of each scanline to lie on a word boundary).  The \fIpixel_type\fR
argument specifies the format of a pixel.  The following formats are
supported:
.IP VP_ALPHA
Each pixel is one byte and contains an 8-bit alpha channel (containing
an opacity or coverage value for the pixel).
.IP VP_LUMINANCE
Each pixel is one byte and contains an 8-bit grayscale intensity.
.IP VP_LUMINANCEA
Each pixel is two bytes and contains an 8-bit grayscale intensity
followed by an 8-bit alpha channel.
.IP VP_RGB
Each pixel is three bytes and contains an RGB color (8 bits/channel).
The R channel is stored first, followed by G and then B.
.IP VP_RGBA
Each pixel is four bytes and contains an RGBA color with an alpha
channel (8 bits/channel).  The R channel is stored first, followed by
G, B and A.
.IP VP_BGR
Each pixel is three bytes and contains an RGB color (8 bits/channel).
The B channel is stored first, follow by G and then R.
.IP VP_ABGR
Each pixel is four bytes and contains an RGBA color with an alpha
channel (8 bits/channel).  The A channel is stored first, followed by
B, G and R.
.PP
The formats VP_LUMINANCE and VP_LUMINANCEA may only be used with
grayscale shaders (the \fIcolor_channels\fR argument to
\fBvpSetLookupShader\fR must be 1, or if you are using a callback
function for shading you must use the VP_GRAY_SHADE_FUNC argument to
\fBvpSetCallback\fR).  The formats VP_RGB, VP_RGBA, VP_BGR and VP_ABGR
may only be used with color shaders.  The format VP_ALPHA may be used
with either type of shader.
.PP
The size of the \fIimage\fR array must be:
.DS
unsigned char \fIimage[height][scan_bytes];\fR
.DE
The \fIscan_bytes\fR argument must be at least \fIwidth\fR times the
number of bytes per pixel.  Pixels in a horizontal scanline are packed
next to each other, regardless of the size of the pixel.  Any extra
padding bytes at the end of a scanline are not modified.
.PP
The alpha channel may be used to composite the rendered image against
a background image.  Alpha gives the fraction of the background that
is visible through the rendered image (0 for fully visible, 255
for fully obscured).  As an example, to change the background color of
the image to a solid color C, modify the color of each pixel in the
image according to the formula:
.DS
color(x,y) += C * (1 - alpha(x,y)/255)
.DE
.SH "STATE VARIABLES"
The current image array properties can be retrieved with the following
state variable codes (see vpGeti(3)): VP_IMAGE, VP_IMAGE_WIDTH,
VP_IMAGE_HEIGHT, VP_IMAGE_SCAN_SIZE, VP_PIXEL_TYPE.
.SH ERRORS
The return value is always VP_OK.
.SH SEE ALSO
VolPack(3), vpCreateContext(3), vpRenderRawVolume(3)