bionic (3) VistaIOSelectDestImage.3.gz

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>