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   Names  the  routine that is using VistaIOSelectDestImage to check its arguments.
                 This name is included in any error messages produced by VistaIOSelectDestImage.

       dest      Is the destination image specified  for  the  operation.   If  dest  is  NULL  a
                 suitable  destination  image  will be created.  Otherwise the image dest will be
                 checked to ensure it has the appropriate properties.

       nbands    Specifies the number of bands the destination image should have.

       nrows     Specifies the number of rows the destination image should have.

       ncolumns  Specifies the number of columns the destination image should have.

       pixel_repn
                 Specifies the pixel representation that the destination image should have.

DESCRIPTION

       VistaIOSelectDestImage establishes a destination for an image operation. 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.

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. 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;
       }

       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.

AUTHOR

       Art Pope <pope@cs.ubc.ca>

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