VistaIOCombineBands(3)

💖 VistaIOCombineBands — bestie edition 💖

okay so you're in the VistaIOCombineBands(3) zone of the Library Functions Manual, and honestly? iconic. this is the page that teaches you how to ✨combine bands✨ — like, grab bands from a bunch of source images and stack them into one destination image. two functions do the job: VistaIOCombineBands and VistaIOCombineBandsVa, and they both literally just copy a series of image bands. no cap. 🎀

---

🌈 SYNOPSIS 🌈

#include <vistaio.h>

VistaIOImage VistaIOCombineBands (nels, src_images, src_bands, dest)
       int nels;
       VistaIOImage src_images[], dest;
       VistaIOBand src_bands[];

VistaIOImage VistaIOCombineBandsVa (dest, src_image1, src_band1, ..., NULL)
       VistaIOImage dest, src_image1;
       VistaIOBand src_band1;

---

🦋 ARGUMENTS 🦋

• nels — the number of elements hanging out in the src_images and src_bands arrays. that's it, that's the count. 💅
• src_images — an array of images that hold the bands you wanna copy. aka the source images, the ones doing the giving. 🫶
• src_bands — an array that says which bands get copied. each element is either one specific band of the matching source image, or the constant VistaIOAllBands, which is the "give me EVERYTHING from this image" option. 👑
• dest — either an image you already have that you wanna copy into (the destination image), or NULL if you want a shiny new destination image created for you. ✨
• src_image1 — the first image holding a band (or bands) to be copied. the first source image, the opener, the main character. 🌟
• src_band1 — either one particular band of src_image1 to copy, or the constant VistaIOAllBands to say "yeah take all of src_image1's bands, idc." 💫

---

🌸 DESCRIPTION 🌸

VistaIOCombineBands copies bands of pixel values from various source images into a destination image. the source images are listed in the array src_images, and the band(s) to copy from each one are listed in the array src_bands. both arrays must have nels elements — no more, no less, periodt.

a src_bands element can be VistaIOAllBands, which means all bands of that corresponding source image get copied, or it can be a particular band number, which means only that one band of the corresponding source image gets copied. lowkey simple, highkey powerful. 💅

VistaIOCombineBandsVa is the same vibe, except the source images and band numbers come in through a variable-length argument list. that list holds one or more pairs shaped like src_image1, src_band1, and it's terminated by the value NULL. 🎀

⚠️ okay important: all source images must have the same pixel representation, number of rows, and number of columns. like, they all gotta match. (the original says "must have have" — typo and all, we keep it real here, bestie 😭)

if dest is NULL, a destination image gets created with the same pixel representation, number of rows, and number of columns as the source images. it's created with a number of bands equal to the total number of bands being copied. slay. ✨

otherwise dest specifies an image to copy pixel values into. it must have the same pixel representation, number of rows, and number of columns as the source image, and it must have a number of bands equal to the total number of bands to be copied. no shortcuts. 🙈

source image bands, taken in the sequence you specified, get copied into consecutive destination image bands. so the order you list them is the order they land. iykyk. 🧚

---

💜 RETURN VALUES 💜

both routines return the destination image if everything works out, and NULL otherwise. simple as that, bestie. 💖

---

🔥 SEE ALSO 🔥

VistaIOCopyBand(3), VistaIOCopyImage(3), VistaIOImage(3),

---

🎀 NOTES 🎀

no attributes are copied from any source images to the destination image. like, zero. none. the vibes stay where they are. 🫶

---

💀 DIAGNOSTICS 💀

• Band band referenced in image of nbands band(s). — band band is supposed to be copied from a source image that has nbands bands. except band is outside the range [0, nbands - 1]. so yeah, out of bounds, we don't do that. 😭
• Destination image has dest_nbands bands; src_nbands expected. — a destination image was specified, but it has the wrong number of bands. mismatch behavior, not cute. 🙈
• Destination image has dest_prop property; src_prop expected. — property is one of pixels'', rows'', or ``columns''. a destination image was specified but it doesn't have the same pixel representation, number of rows, and number of columns as the source images. basically a vibe check that failed. 💅

---

👑 AUTHOR 👑

Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

---

and that's the whole page, bestie!! this was VistaIO Version 1.2.14, dated 24 April 1993 — yeah she's vintage, she's a classic, and she still ate. go combine some bands, you got this 💅✨🦋