vpSetImage(3)

💖 vpSetImage(3) 💖

okay bestie, gather round, because this is the one that tells VolPack where to actually put your pretty pictures. it's a Library Functions Manual entry, it's from VolPack, and it's lowkey one of the most important calls you'll make. no cap.

---

✨ 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 — the VolPack context you got from vpCreateContext. your main character, basically.
• image — a 2D array where the result images get stored. this is the canvas, bestie. 🎨
• width — how wide the image is, in pixels.
• height — how tall the image is, in pixels.
• scan_bytes — how many bytes each scanline takes up in the image array.
• pixel_type — a code that says what format every pixel in the array is in.

---

💅 DESCRIPTION 💅

vpSetImage is the call that hands VolPack a buffer to stash the result image in while it's rendering. the width and height params set the size of that result image, and — this is the part that matters — the clipping window (peep vpWindow(3) or vpWindowPHIGS(3)) gets scaled to match that size exactly. so like, whatever you set here is the vibe the clip window is gonna serve. ✨

the scan_bytes argument is the size of a scanline in the image array, measured in bytes. why would you want that separate from width? padding, babe. you can add padding to the end of each scanline to satisfy alignment restrictions — like, raster operations sometimes need the start of every scanline to land on a word boundary, and this is how you make that happen. 😌

the pixel_type argument says what format a pixel is in. here are the formats that are supported, and yes, we're doing all of them:

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

now, the shader tea ☕ — this part is a whole vibe check:

• VP_LUMINANCE and VP_LUMINANCEA can only be used with grayscale shaders. that means the color_channels argument to vpSetLookupShader has to be 1, or, if you're shading with a callback function, you gotta use the VP_GRAY_SHADE_FUNC argument to vpSetCallback.
• VP_RGB, VP_RGBA, VP_BGR and VP_ABGR can only be used with color shaders.
• VP_ALPHA is the flexible icon and can be used with either type of shader. 👑

the size of the image array has to be:

unsigned char image[height][scan_bytes];

and the scan_bytes argument must be at least width times the number of bytes per pixel. pixels in 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 are not modified — so don't come for them, they're minding their business. 🙈

the alpha channel is what lets you composite the rendered image against a background image. alpha is the fraction of the background that's visible through the rendered image — 0 means fully visible, 255 means fully obscured. for example, to change the background color of the image to a solid color C, you modify the color of each pixel in the image using this formula:

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

---

⭐ STATE VARIABLES ⭐

you can retrieve the current image array properties with these state variable codes (check vpGeti(3) for the deets): VP_IMAGE, VP_IMAGE_WIDTH, VP_IMAGE_HEIGHT, VP_IMAGE_SCAN_SIZE, VP_PIXEL_TYPE.

---

😭 ERRORS 😭

the return value is always VP_OK. literally always. it's giving unbothered. it's giving no notes. 💀

---

🫶 SEE ALSO 🫶

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

---

and that's the whole page, bestie!! 🌈 you now know exactly how to hand VolPack an image buffer, so go forth and render something iconic. this has been a VolPack manual moment, courtesy of VolPack itself — mwah, slay, periodt. 💖✨🎀🦋