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>