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>