bionic (3) VistaIOCopyImage.3.gz

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>