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

0v

\\$1

8 .. .FA -- function arguments
one argument declaration follows on next line

.. .FE -- function end
end of function declaration

.. .DS -- display start

.. .DE -- display done

..

vpSetImage - specify an image array #include <volpack.h> .FS vpResult vpSetImage(vpc, image, width, height, scan_bytes, pixel_type) .FA vpContext *vpc; .FA unsigned char *image; .FA int width, height; .FA int scan_bytes; .FA int pixel_type; .FE VolPack context from vpCreateContext. 2D array for storing result images. Width of image in pixels. Height of image in pixels. Number of bytes per scanline in image array. Code indicating the format of each pixel in the array. vpSetImage is used to specify a buffer for storing the result image during rendering. The width and height 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 scan_bytes 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 pixel_type argument specifies the format of a pixel. The following formats are supported: Each pixel is one byte and contains an 8-bit alpha channel (containing an opacity or coverage value for the pixel). Each pixel is one byte and contains an 8-bit grayscale intensity. Each pixel is two bytes and contains an 8-bit grayscale intensity followed by an 8-bit alpha channel. 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. 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. 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. 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.

The formats VP_LUMINANCE and VP_LUMINANCEA may only be used with grayscale shaders (the color_channels argument to vpSetLookupShader must be 1, or if you are using a callback function for shading you must use the VP_GRAY_SHADE_FUNC argument to vpSetCallback). 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.

The size of the image array must be: unsigned char image[height][scan_bytes]; The scan_bytes argument must be at least width 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.

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: color(x,y) += C * (1 - alpha(x,y)/255)

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. The return value is always VP_OK. VolPack(3), vpCreateContext(3), vpRenderRawVolume(3)