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>