ABCDEFGHIJKLMNOPQRSTUVWXYZ

TIFFReadRGBAImage

TIFFReadRGBAImage(3T)                                    TIFFReadRGBAImage(3T)



NAME
       TIFFReadRGBAImage - read and decode an image into a fixed-format raster

SYNOPSIS
       #include <tiffio.h>
       #define TIFFGetR(abgr)   ((abgr) & 0xff)
       #define TIFFGetG(abgr)   (((abgr) >> 8) & 0xff)
       #define TIFFGetB(abgr)   (((abgr) >> 16) & 0xff)
       #define TIFFGetA(abgr)   (((abgr) >> 24) & 0xff)
       int TIFFReadRGBAImage(TIFF* tif, u_long width, u_long height, u_long* raster, int stopOnError)

DESCRIPTION
       TIFFReadRGBAImage reads a strip- or tile-based image into memory, stor-
       ing  the  result in the user supplied raster.  The raster is assumed to
       be an array of width times height 32-bit entries, where width  must  be
       less  than  or  equal to the width of the image (height may be any non-
       zero size).  If the raster dimensions are smaller than the  image,  the
       image  data  is  cropped to the raster bounds.  If the raster height is
       greater than that of the image, then the image data are placed  in  the
       lower  part of the raster.  (Note that the raster is assume to be orga-
       nized such that the pixel at location (x,y) is raster[y*width+x];  with
       the raster origin in the lower-left hand corner.)

       Raster  pixels  are  8-bit packed red, green, blue, alpha samples.  The
       macros TIFFGetR, TIFFGetG, TIFFGetB, and TIFFGetA  should  be  used  to
       access  individual  samples.   Images  without Associated Alpha matting
       information have a constant Alpha of 1.0 (255).

       TIFFReadRGBAImage converts non-8-bit images by scaling  sample  values.
       Palette,  grayscale,  bilevel,  CMYK, and YCbCr images are converted to
       RGB transparently.  Raster pixels are returned uncorrected by any  col-
       orimetry information present in the directory.

       The  paramater  stopOnError specifies how to act if an error is encoun-
       tered while reading the image.  If stopOnError  is  non-zero,  then  an
       error  will  terminate  the operation; otherwise TIFFReadRGBAImage will
       continue processing data until all the possible data in the image  have
       been requested.

NOTES
       In C++ the stopOnError parameter defaults to 0.

       Samples  must  be  either  1,  2,  4, 8, or 16 bits.  Colorimetric sam-
       ples/pixel must be either 1,  3,  or  4  (i.e.   SamplesPerPixel  minus
       ExtraSamples).

       Palettte image colormaps that appear to be incorrectly written as 8-bit
       values are automatically scaled to 16-bits.

       TIFFReadRGBAImage is just a wrapper around the more general TIFFRGBAIm-
       age(3T) facilities.

RETURN VALUES
       1 is returned if the image was successfully read and converted.  Other-
       wise, 0 is returned if an error  was  encountered  and  stopOnError  is
       zero.

DIAGNOSTICS
       All error messages are directed to the TIFFError(3T) routine.

       Sorry,  can  not  handle  %d-bit pictures.  The image had BitsPerSample
       other than 1, 2, 4, 8, or 16.

       Sorry, can not handle %d-channel images.  The image had SamplesPerPixel
       other than 1, 3, or 4.

       Missing needed "PhotometricInterpretation" tag.  The image did not have
       a tag that describes how to display the data.

       No "PhotometricInterpretation" tag, assuming RGB.  The image was  miss-
       ing  a  tag that describes how to display it, but because it has 3 or 4
       samples/pixel, it is assumed to be RGB.

       No "PhotometricInterpretation" tag, assuming min-is-black.   The  image
       was  missing a tag that describes how to display it, but because it has
       1 sample/pixel, it is assumed to be a grayscale or bilevel image.

       No space for photometric conversion table.  There was insufficient mem-
       ory for a table used to convert image samples to 8-bit RGB.

       Missing  required  "Colormap"  tag.   A  Palette  image  did not have a
       required Colormap tag.

       No space for tile buffer.  There was insufficient memory to allocate an
       i/o buffer.

       No  space  for strip buffer.  There was insufficient memory to allocate
       an i/o buffer.

       Can not handle format.  The image has a format (combination of BitsPer-
       Sample,  SamplesPerPixel, and PhotometricInterpretation) that TIFFRead-
       RGBAImage can not handle.

       No space for B&W mapping table.  There was insufficient memory to allo-
       cate a table used to map grayscale data to RGB.

       No  space  for Palette mapping table.  There was insufficient memory to
       allocate a table used to map data to 8-bit RGB.

BUGS
       Orientations other than bottom-left, or top-left are not  handled  cor-
       rectly.

SEE ALSO
       libtiff(3T),  TIFFOpen(3T),  TIFFRGBAImage(3T),  TIFFReadRGBAStrip(3T),
       TIFFReadRGBATile(3T)



                               February 14, 1992         TIFFReadRGBAImage(3T)