VistaIOSelectDestImage - select a destination for an image operation

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.

       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)

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.

       ``Routine: Destination image has actualproperty; 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.

       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:

       VistaIOImageProcessImage(src,dest, ...)VistaIOImagesrc,dest;{VistaIOImageresult;/*Establishadestinationimage,result:*/result=VistaIOSelectDestImage("ProcessImage",dest, ...);if(!result)returnNULL;/*desthaswrongproperties*/

            Perform the operation

            /*Onsuccessfulcompletion:*/VistaIOCopyImageAttrs(src,result);returnresult;/*Onfailure:*/if(result!=dest)VistaIODestroyImage(result);returnNULL;}

       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:

       VistaIOImageProcessImage(src,dest, ...)VistaIOImagesrc,dest;{VistaIOImageresult;/*Establishadestinationimage,result:*/result=VistaIOSelectDestImage("ProcessImage",dest, ...);if(!result)returnNULL;/*desthaswrongproperties*/if(src==dest)result=VistaIOCreateImage(...);

            Perform the operation

            /*Onsuccessfulcompletion:*/if(src==dest){VistaIOCopyImagePixels(result,dest,VistaIOAllBands);VistaIODestroyImage(result);returndest;}else{VistaIOCopyImageAttrs(src,result);returnresult;}/*Onfailure:*/if(result!=dest)VistaIODestroyImage(result);returnNULL;}

       VistaIOSelectDestImage - select a destination for an image operation

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

VistaIOImage(3),

#include<vistaio.h>VistaIOImageVistaIOSelectDestImage(routine,dest,nbands,nrows,ncolumns,pixel_repn)VistaIOStringConstroutine;VistaIOImagedest;intnbands,nrows,ncolumns;VistaIORepnKindpixel_repn;