.ds Vv 1.2.14
.TH VistaIOSelectDestImage 3 "24 April 1993" "VistaIO Version \*(Vv"
.SH NAME
VistaIOSelectDestImage \- select a destination for an image operation
.SH SYNOPSIS
.nf
.B "#include <vistaio.h>"
.PP
.ft B
VistaIOImage VistaIOSelectDestImage (\fIroutine\fP, \fIdest\fP, \fInbands\fP, \
\fInrows\fP, \fIncolumns\fP, \fIpixel_repn\fP)
.RS
VistaIOStringConst \fIroutine\fP;
VistaIOImage \fIdest\fP;
int \fInbands\fP, \fInrows\fP, \fIncolumns\fP;
VistaIORepnKind \fIpixel_repn\fP;
.RE
.fi
.SH ARGUMENTS
.IP \fIroutine\fP 10n
Names the routine that is using \fBVistaIOSelectDestImage\fP to check its arguments. 
This name is included in any error messages produced by \fBVistaIOSelectDestImage\fP.
.IP \fIdest\fP
Is the destination image specified for the operation. 
If \fIdest\fP is 
.SB NULL
a suitable destination image will be created. 
Otherwise the image \fIdest\fP will be checked to
ensure it has the appropriate properties.
.IP \fInbands\fP
Specifies the number of bands the destination image should have.
.IP \fInrows\fP
Specifies the number of rows the destination image should have.
.IP \fIncolumns\fP
Specifies the number of columns the destination image should have.
.IP \fIpixel_repn\fP
Specifies the pixel representation that the destination image should have.
.SH DESCRIPTION
\fBVistaIOSelectDestImage\fP establishes a destination for an image operation. If 
a destination image is supplied to \fBVistaIOSelectDestImage\fP, it checks that 
the image has the properties specified by \fInbands\fP, \fInrows\fP, 
\fIncolumns\fP, and \fIpixel_repn\fP. Otherwise, it creates a suitable 
destination image. In both cases, the destination image is returned. 
.SH "RETURN VALUES"
\fBVistaIOSelectDestImage\fP returns the destination image if an appropriate one
exists or can be created; it returns 
.SB NULL
otherwise.
.SH EXAMPLES
There are two recipes for using \fBVistaIOSelectDestImage\fP 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: 
.PP
.nf
.ft B
VistaIOImage ProcessImage (src, dest, \fR...\fP)
VistaIOImage src, dest;
{
	VistaIOImage result;

	/* Establish a destination image, result: */
	result = VistaIOSelectDestImage ("ProcessImage", dest, \fR...\fP);
	if (! result)
		return NULL;       /* dest has wrong properties */

	\fRPerform the operation\fP

	/* On successful completion: */
	VistaIOCopyImageAttrs (src, result);
	return result;

	/* On failure: */
	if (result != dest)
		VistaIODestroyImage (result);
	return NULL;
}
.ft
.fi
.PP
Another recipe is needed if the source and destination images must differ
\(em 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:
.PP
.nf
.ft B
VistaIOImage ProcessImage (src, dest, \fR...\fP)
VistaIOImage src, dest;
{
	VistaIOImage result;

	/* Establish a destination image, result: */
	result = VistaIOSelectDestImage ("ProcessImage", dest, \fR...\fP);
	if (! result)
		return NULL;       /* dest has wrong properties */
	if (src == dest)
		result = VistaIOCreateImage (\fR...\fP);

	\fRPerform the operation\fP

	/* 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;
}
.ft
.fi
.SH "SEE ALSO"
.BR VistaIOImage (3),

.SH DIAGNOSTICS
.IP "``\fIRoutine\fP: Destination image has \fIactual\fP \fIproperty\fP; \fIreqd\fP expected.''"
\fIProperty\fP is one of ``bands'', ``rows'', ``columns'', or ``pixels''. 
The destination image does not have the correct size or pixel 
representation. \fIRoutine\fP will be the name supplied by the 
\fIroutine\fP argument. 
.SH AUTHOR
Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>