---
name: "VistaIOSelectDestImage"
section: "3"
platform: "linux"
package: "libvistaio-dev"
version: "1.2.19-3+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/VistaIOSelectDestImage"
---

# VistaIOSelectDestImage(3)

select a destination for an image operation

## 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)](/VistaIOImage/3.md),

## 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\>