---
name: "Image"
section: "3"
platform: "linux"
package: "libvolpack1-dev"
version: "1.0b3-10"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Image"
---

# Image(3)

specify an image array

## 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)](/VolPack/3.md), vpCreateContext(3), vpRenderRawVolume(3)