NAME

       VistaIOCopyImage - copy an image

SYNOPSIS

       #include <vistaio.h>

       VistaIOImage VistaIOCopyImagePixels (src, dest, band)
              VistaIOImage src, dest;
              VistaIOBand band;

       VistaIOImage VistaIOCopyImageAttrs (src, dest)
              VistaIOImage src, dest;

       VistaIOImage VistaIOCopyImage (src, dest, band)
              VistaIOImage src, dest; VistaIOBand band;

ARGUMENTS

       src       Specifies the source image.

       dest      May  specify  a  destination  image;  or  may  be  NULL  to  indicate that a new
                 destination image should be created.

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

DESCRIPTION

       VistaIOCopyImagePixels copies pixel values from the source image to the destination image.
       (No other image properties are copied.)

       VistaIOCopyImageAttrs  copies  attributes  from the source image to the destination image.
       (No pixel values are copied.) If the destination image already has an attribute  list,  it
       is  first  deleted.  Then  the  destination  image  is  given a copy of the source image's
       attribute list. Finally, if the source and destination images do not have the same  number
       of  bands  then  the  destination  image's band interpretation attributes may be edited to
       ensure their validity:

         • if they do not have the  same  number  of  bands  then  (a)  any  band  interpretation
           attributes,  such  as  frame_interp and color_interp, are deleted from the destination
           image's  copy;  (b)  the  size  of  the  destination   image's   component   dimension
           (ncomponents) is set equal to its number of bands; and (c) the sizes of its other band
           interpretation dimensions (nframes, nviewpoints, and ncolors) are set to 1.

         • if they have the same number of bands then (a) all  attributes  are  copied  unchanged
           from  the  source  image  to  the  destination  image;  and  (b) the sizes of the band
           interpretation dimensions are copied as well.

       VistaIOCopyImage copies both pixel values and attributes from one image to the  other.  It
       is equivalent to calling both VistaIOCopyImagePixels and VistaIOCopyImageAttrs.

       You  can  specify  NULL  as  a  destination image to any of these routines; they will then
       create an appropriate destination image, copy to it,  and  return  it.  If  you  supply  a
       destination  image  to  VistaIOCopyImage  or VistaIOCopyImagePixels, it must have the same
       number of rows, number of columns, and pixel representation as the source image; also,  it
       must have a number of bands consistent with src and band.

RETURN VALUES

       Each  of  these  routines  returns  the  destination  image  if  it is successful and NULL
       otherwise.

SEE ALSO

       VistaIOCopyBand(3), VistaIOCombineBands(3) VistaIOImage(3),

NOTES

       VistaIOCopyAttrList(3) is used to copy attributes from the source image to the destination
       image. Thus the destination image's attribute list contains its own copy of each attribute
       value — except that for a VistaIOPointer value, the pointer is copied but not the (opaque)
       data structure to which it points.

DIAGNOSTICS

       ``Band band referenced in image of nbands band(s).''
              The band argument is invalid given the number of bands in src.

       ``Destination image has dest_nbands bands; src_nbands expected.''
              A destination image was specified but it has the wrong number of bands.  If band is
              VistaIOAllBands, the destination image must have the same number of  bands  as  the
              source image. Otherwise, it must have a single band.

       ``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 image.

AUTHOR

       Art Pope <pope@cs.ubc.ca>

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