Ubuntu Manpage: vpSetImage - specify an image array

Provided by: libvolpack1-dev_1.0b3-9_amd64

NAME

       vpSetImage - specify an image array

SYNOPSIS

       #include <volpack.h>

       vpResult
       vpSetImage(vpc, image, width, height, scan_bytes, pixel_type)
           vpContext *vpc;
           unsigned char *image;
           int width, height;
           int scan_bytes;
           int pixel_type;

ARGUMENTS

       vpc    VolPack context from vpCreateContext.

       image  2D array for storing result images.

       width  Width of image in pixels.

       height Height of image in pixels.

       scan_bytes
              Number of bytes per scanline in image array.

       pixel_type
              Code indicating the format of each pixel in the array.

DESCRIPTION

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:

VP_ALPHA
Each pixel is one byte and contains an 8-bit alpha channel (containing an opacity
or coverage value for the pixel).

VP_LUMINANCE
Each pixel is one byte and contains an 8-bit grayscale intensity.

VP_LUMINANCEA
Each pixel is two bytes and contains an 8-bit grayscale intensity followed by an
8-bit alpha channel.

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.

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.

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.

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.

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)

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.

ERRORS