NAME

       VistaIOCombineBands, VistaIOCombineBandsVa - copy a series of image bands

SYNOPSIS

       #include <vistaio.h>

       VistaIOImage VistaIOCombineBands (nels, src_images, src_bands, dest)
              int nels;
              VistaIOImage src_images[], dest;
              VistaIOBand src_bands[];

       VistaIOImage VistaIOCombineBandsVa (dest, src_image1, src_band1, ..., NULL)
              VistaIOImage dest, src_image1;
              VistaIOBand src_band1;

ARGUMENTS

       nels      Specifies the number of elements in the src_images and src_bands arrays.

       src_images
                 Specifies an array of images containing the bands to be copied (i.e., the source images).

       src_bands Specifies  an  array identifying the bands to be copied.  Each element may specify a particular
                 band of the corresponding source image, or it may be the constant VistaIOAllBands  to  indicate
                 that all bands of the corresponding source image should be copied.

       dest      May  specify an image to copy to (i.e., the destination image), or may be NULL to indicate that
                 a new destination image should be created.

       src_image1
                 Specifies the first image containing a band or bands to  be  copied  (i.e.,  the  first  source
                 image).

       src_band1 May  specify  a  particular  band  of  src_image1  to  be  copied,  or  it  may be the constant
                 VistaIOAllBands to indicate that all bands of src_image1 should be copied.

DESCRIPTION

       VistaIOCombineBands copies bands of pixel values from various source images to a destination  image.  The
       source images are listed in the array src_images, and the band(s) to be copied from each is listed in the
       array src_bands. Both arrays must have nels  elements.   A  src_bands  element  may  be  VistaIOAllBands,
       indicating  that  all bands of the corresponding source image are to be copied, or it may be a particular
       band number, indicating that only that band of the corresponding source image is to be copied.

       VistaIOCombineBandsVa is similar except that the source images  and  band  numbers  are  specified  by  a
       variable-length  argument  list.  The  argument  list  contains one or more pairs of the form src_image1,
       src_band1, and it is terminated by the value NULL

       All source images must have have the same pixel representation, number of rows, and number of columns.

       If dest is NULL, a destination image is created with the same pixel representation, number of  rows,  and
       number  of  columns  as the source images. The image is created with a number of bands equal to the total
       number of bands to be copied.

       Otherwise dest specifies an image to which pixel values are to be copied. It must  have  the  same  pixel
       representation,  number  of rows, and number of columns as the source image, and it must have a number of
       bands equal to the total number bands to be copied.

       Source image bands, taken in the sequence specified, are copied to consecutive destination image bands.

RETURN VALUES

       Both routines return the destination image if they are successful and NULL otherwise.

SEE ALSO

       VistaIOCopyBand(3), VistaIOCopyImage(3), VistaIOImage(3),

NOTES

       No attributes are copied from any source images to the destination image.

DIAGNOSTICS

       ``Band band referenced in image of nbands band(s).''
              Band band is to be copied from a source image having nbands bands.  However band is outside of the
              range [0, nbands - 1].

       ``Destination image has dest_nbands bands; src_nbands expected.''
              A destination image was specified but it has the wrong number of bands.

       ``Destination image has dest_prop property; src_prop expected.''
              Property is one of ``pixels'', ``rows'', or ``columns''.  A destination image was specified but it
              does not have the same pixel representation, number of rows, and number of columns as  the  source
              images.

AUTHOR

       Art Pope <pope@cs.ubc.ca>

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