VistaIOSelectDestImage(3)

💖 VistaIOSelectDestImage 💖

okay so bestie, welcome to VistaIOSelectDestImage(3) — it's a Library Functions Manual situation and honestly it's giving "quietly essential" because this little function is the one that picks where your image operation is gonna dump its output. 🎀

---

✨ NAME ✨

VistaIOSelectDestImage — select a destination for an image operation

---

🌸 SYNOPSIS 🌸

#include <vistaio.h>

VistaIOImage VistaIOSelectDestImage (routine, dest, nbands, nrows, ncolumns, pixel_repn)
       VistaIOStringConst routine;
       VistaIOImage dest;
       int nbands, nrows, ncolumns;
       VistaIORepnKind pixel_repn;

---

🦋 ARGUMENTS 🦋

• routine — the name of the routine that's calling VistaIOSelectDestImage to check its arguments. Like, it's a whole vibe check for your args. This name gets stuffed into any error messages that VistaIOSelectDestImage produces, so if something's wrong, you know who did it. 💅
• dest — the destination image that was specified for the operation. If dest is NULL, a suitable destination image gets created for you (main character energy, honestly). Otherwise, the image dest gets checked to make sure it has all the right properties. 🔥
• nbands — how many bands the destination image should have.
• nrows — how many rows the destination image should have.
• ncolumns — how many columns the destination image should have.
• pixel_repn — the pixel representation that the destination image should have.

---

💫 DESCRIPTION 💫

VistaIOSelectDestImage establishes a destination for an image operation. Periodt.

If a destination image is supplied to VistaIOSelectDestImage, it checks that the image has the properties specified by nbands, nrows, ncolumns, and pixel_repn. Otherwise, it creates a suitable destination image. In both cases, the destination image is returned. no cap, that's literally the whole thing. 🫶

---

👑 RETURN VALUES 👑

VistaIOSelectDestImage returns the destination image if an appropriate one exists or can be created; it returns NULL otherwise. 😭

---

🌈 EXAMPLES 🌈

There are two recipes for using VistaIOSelectDestImage in a routine that performs an image processing operation. Pick your fighter. 🥊

🍓 Recipe One: the same image does both jobs

One is suitable for operations that can be carried out with the same image serving as both the source and destination images (e.g., thresholding each pixel value). A routine performing such an operation has the form:

VistaIOImage ProcessImage (src, dest, ...)
VistaIOImage src, dest;
{
     VistaIOImage result;

     /* Establish a destination image, result: */
     result = VistaIOSelectDestImage ("ProcessImage", dest, ...);
     if (! result)
          return NULL;       /* dest has wrong properties */

     Perform the operation

     /* On successful completion: */
     VistaIOCopyImageAttrs (src, result);
     return result;

     /* On failure: */
     if (result != dest)
          VistaIODestroyImage (result);
     return NULL;
}

🧚 Recipe Two: source and dest gotta be different

Another recipe is needed if the source and destination images must differ — i.e., if the operation's results cannot be stored directly back into the source image as they are being computed. (This might be the case, for example, if several source pixel values are needed to compute each destination pixel value.) The routine must ensure that a separate image is used to store the operation's result even when a single image is supplied as both the source and destination of the operation. It has this form:

VistaIOImage ProcessImage (src, dest, ...)
VistaIOImage src, dest;
{
     VistaIOImage result;

     /* Establish a destination image, result: */
     result = VistaIOSelectDestImage ("ProcessImage", dest, ...);
     if (! result)
          return NULL;       /* dest has wrong properties */
     if (src == dest)
          result = VistaIOCreateImage (...);

     Perform the operation

     /* On successful completion: */
     if (src == dest) {
          VistaIOCopyImagePixels (result, dest, VistaIOAllBands);
          VistaIODestroyImage (result);
          return dest;
     } else {
          VistaIOCopyImageAttrs (src, result);
          return result;
     }

     /* On failure: */
     if (result != dest)
          VistaIODestroyImage (result);
     return NULL;
}

---

🔍 SEE ALSO 🔍

• VistaIOImage(3),

---

🚨 DIAGNOSTICS 🚨

• Routine: Destination image has actual property; reqd expected.'' — Property is one of bands, rows, columns, or pixels. The destination image does not have the correct size or pixel representation. Routine will be the name supplied by the routine argument.

not me getting an error message because dest was the wrong shape 🙈 at least it tells you exactly which property was off and which routine was being messy.

---

💜 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, and it's still out here selecting destinations like the icon it is. VistaIOSelectDestImage(3) — slay, honestly. 🎀🦋💖