vpSetImage(3)

💖 vpSetImage — specify an image array 💖

okay bestie, you're in the vpSetImage(3) page from the Library Functions Manual and honestly? this one is a slay. it's the function that tells VolPack where to put the picture. let's get into it 🎀

---

✨ NAME ✨

vpSetImage — specify an image array. that's it, that's the whole vibe 💅

---

🌸 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 — the VolPack context, the one you got from vpCreateContext. your main character.
• image — a 2D array that's gonna hold the result images. the canvas, the moment, the whole point 🎨
• width — width of the image, in pixels.
• height — height of the image, in pixels.
• scan_bytes — how many bytes there are per scanline in the image array.
• pixel_type — a code that says what the format of each pixel in the array is.

---

👑 DESCRIPTION 👑

vpSetImage is how you hand over a buffer for storing the result image while rendering happens. the width and height params set the size of that result image, and — important — the clipping window (peep vpWindow(3) or vpWindowPHIGS(3)) gets scaled to match that size exactly. no notes. 💯

the scan_bytes argument is the size of a scanline in the image array, in bytes. why would you ever need that, you ask? because you can use it to add padding to the end of each scanline so alignment restrictions are satisfied — like, raster operations sometimes need the beginning of every scanline to land on a word boundary. it's giving "i need my space" 🫶

the pixel_type argument says what format a pixel is in. here are all the formats that are supported, no cap:

• VP_ALPHA — each pixel is one byte and holds an 8-bit alpha channel (so, an opacity or coverage value for that pixel).
• VP_LUMINANCE — each pixel is one byte and holds an 8-bit grayscale intensity.
• VP_LUMINANCEA — each pixel is two bytes: an 8-bit grayscale intensity first, then an 8-bit alpha channel.
• VP_RGB — each pixel is three bytes and holds an RGB color (8 bits/channel). R is stored first, then G, then B.
• VP_RGBA — each pixel is four bytes and holds an RGBA color with an alpha channel (8 bits/channel). R goes first, then G, then B, then A.
• VP_BGR — each pixel is three bytes and holds an RGB color (8 bits/channel). B is stored first, then G, then R.
• VP_ABGR — each pixel is four bytes and holds an RGBA color with an alpha channel (8 bits/channel). A goes first, then B, then G, then R.

now, the rules of who can hang with whom (very much a vibe check situation):

• VP_LUMINANCE and VP_LUMINANCEA are only allowed with grayscale shaders. that means the color_channels argument to vpSetLookupShader has to be 1, or — if you're using a callback function for shading — you have to use the VP_GRAY_SHADE_FUNC argument to vpSetCallback.
• VP_RGB, VP_RGBA, VP_BGR and VP_ABGR are only allowed with color shaders.
• VP_ALPHA is the flexible icon and can be used with either type of shader. she contains multitudes ✨

the size of the image array has to be:

unsigned char image[height][scan_bytes];

and scan_bytes must be at least width times the number of bytes per pixel. pixels inside a horizontal scanline are packed right next to each other, no matter what size the pixel is. any extra padding bytes hanging out at the end of a scanline? not modified. untouched. left alone. 🙈

okay and the alpha channel? she's the moment for compositing your rendered image against a background image. alpha gives you the fraction of the background that's visible through the rendered image — 0 means fully visible, 255 means fully obscured. so like, say you wanna change the background color of the image to a solid color C: you modify the color of every pixel in the image according to this formula:

color(x,y) += C * (1 - alpha(x,y)/255)

slay. math ate. 🔥

---

🌈 STATE VARIABLES 🌈

you can pull the current image array properties back out with these state variable codes (check 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. yes, always. the drama is nonexistent, she's stable, she's unbothered. 👑

---

🎀 SEE ALSO 🎀

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

---

that's the whole page bestie, go render something gorgeous 💖 this one came from the VolPack source, and yeah — it's vpSetImage(3) all the way down. byeee, love u, drink water 🌸