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

       The return value is always VP_OK.

SEE ALSO

       VolPack(3), vpCreateContext(3), vpRenderRawVolume(3)