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  VistaIOAll‐
              Bands, 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>

VistaIO Version 1.2.14                            24 April 1993                              VistaIOCopyImage(3)