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>

VistaIO Version 1.2.14                            24 April 1993                        VistaIOSelectDestImage(3)