roentgen b75cab
.\" $Id: TIFFReadRGBAStrip.3tiff,v 1.3 2005-11-02 11:07:18 dron Exp $
roentgen b75cab
.\"
roentgen b75cab
.\" Copyright (c) 1991-1997 Sam Leffler
roentgen b75cab
.\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
roentgen b75cab
.\"
roentgen b75cab
.\" Permission to use, copy, modify, distribute, and sell this software and 
roentgen b75cab
.\" its documentation for any purpose is hereby granted without fee, provided
roentgen b75cab
.\" that (i) the above copyright notices and this permission notice appear in
roentgen b75cab
.\" all copies of the software and related documentation, and (ii) the names of
roentgen b75cab
.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
roentgen b75cab
.\" publicity relating to the software without the specific, prior written
roentgen b75cab
.\" permission of Sam Leffler and Silicon Graphics.
roentgen b75cab
.\" 
roentgen b75cab
.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
roentgen b75cab
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
roentgen b75cab
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
roentgen b75cab
.\" 
roentgen b75cab
.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
roentgen b75cab
.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
roentgen b75cab
.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
roentgen b75cab
.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
roentgen b75cab
.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
roentgen b75cab
.\" OF THIS SOFTWARE.
roentgen b75cab
.\"
roentgen b75cab
.if n .po 0
roentgen b75cab
.TH TIFFReadRGBAStrip 3TIFF "December 10, 1998" "libtiff"
roentgen b75cab
.SH NAME
roentgen b75cab
TIFFReadRGBAStrip \- read and decode an image strip into a fixed-format raster
roentgen b75cab
.SH SYNOPSIS
roentgen b75cab
.B "#include <tiffio.h>"</tiffio.h>
roentgen b75cab
.sp
roentgen b75cab
.B "#define TIFFGetR(abgr) ((abgr) & 0xff)"
roentgen b75cab
.br
roentgen b75cab
.B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)"
roentgen b75cab
.br
roentgen b75cab
.B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)"
roentgen b75cab
.br
roentgen b75cab
.B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)"
roentgen b75cab
.sp
roentgen b75cab
.BI "int TIFFReadRGBAStrip(TIFF *" tif ", uint32 " row ", uint32 *" raster ")"
roentgen b75cab
.SH DESCRIPTION
roentgen b75cab
.IR TIFFReadRGBAStrip
roentgen b75cab
reads a single strip of a strip-based image into memory, storing the result in
roentgen b75cab
the user supplied RGBA
roentgen b75cab
.IR raster .
roentgen b75cab
The raster is assumed to be an array of width times rowsperstrip 32-bit
roentgen b75cab
entries, where width is the width of the image (TIFFTAG_IMAGEWIDTH) and
roentgen b75cab
rowsperstrip is the maximum lines in a strip (TIFFTAG_ROWSPERSTRIP). 
roentgen b75cab
roentgen b75cab
.PP
roentgen b75cab
The 
roentgen b75cab
.IR row
roentgen b75cab
value should be the row of the first row in the strip (strip * rowsperstrip,
roentgen b75cab
zero based).
roentgen b75cab
roentgen b75cab
.PP
roentgen b75cab
Note that the raster is assume to be organized such that the pixel at location
roentgen b75cab
(\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; with the
roentgen b75cab
raster origin in the 
roentgen b75cab
.I lower-left hand corner
roentgen b75cab
of the strip. That is bottom to top organization.  When reading a partial last
roentgen b75cab
strip in the file the last line of the image will begin at the beginning of
roentgen b75cab
the buffer.
roentgen b75cab
roentgen b75cab
.PP
roentgen b75cab
Raster pixels are 8-bit packed red, green, blue, alpha samples. The macros
roentgen b75cab
.IR TIFFGetR ,
roentgen b75cab
.IR TIFFGetG ,
roentgen b75cab
.IR TIFFGetB ,
roentgen b75cab
and
roentgen b75cab
.I TIFFGetA
roentgen b75cab
should be used to access individual samples. Images without Associated Alpha
roentgen b75cab
matting information have a constant Alpha of 1.0 (255).
roentgen b75cab
.PP
roentgen b75cab
See the 
roentgen b75cab
.IR TIFFRGBAImage (3TIFF) 
roentgen b75cab
page for more details on how various image types are converted to RGBA values.
roentgen b75cab
.SH NOTES
roentgen b75cab
Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel must
roentgen b75cab
be either 1, 3, or 4 (i.e.
roentgen b75cab
.I SamplesPerPixel
roentgen b75cab
minus
roentgen b75cab
.IR ExtraSamples ).
roentgen b75cab
.PP
roentgen b75cab
Palette image colormaps that appear to be incorrectly written as 8-bit values
roentgen b75cab
are automatically scaled to 16-bits.
roentgen b75cab
.PP
roentgen b75cab
.I TIFFReadRGBAStrip
roentgen b75cab
is just a wrapper around the more general
roentgen b75cab
.IR TIFFRGBAImage (3TIFF)
roentgen b75cab
facilities.  It's main advantage over the similar 
roentgen b75cab
.IR TIFFReadRGBAImage() 
roentgen b75cab
function is that for large images a single buffer capable of holding the whole
roentgen b75cab
image doesn't need to be allocated, only enough for one strip.  The 
roentgen b75cab
.IR TIFFReadRGBATile() 
roentgen b75cab
function does a similar operation for tiled images.
roentgen b75cab
.SH "RETURN VALUES"
roentgen b75cab
1 is returned if the image was successfully read and converted.
roentgen b75cab
Otherwise, 0 is returned if an error was encountered.
roentgen b75cab
.SH DIAGNOSTICS
roentgen b75cab
All error messages are directed to the
roentgen b75cab
.IR TIFFError (3TIFF)
roentgen b75cab
routine.
roentgen b75cab
.PP
roentgen b75cab
.BR "Sorry, can not handle %d-bit pictures" .
roentgen b75cab
The image had
roentgen b75cab
.I BitsPerSample
roentgen b75cab
other than 1, 2, 4, 8, or 16.
roentgen b75cab
.PP
roentgen b75cab
.BR "Sorry, can not handle %d-channel images" .
roentgen b75cab
The image had
roentgen b75cab
.I SamplesPerPixel
roentgen b75cab
other than 1, 3, or 4.
roentgen b75cab
.PP
roentgen b75cab
\fBMissing needed "PhotometricInterpretation" tag\fP.
roentgen b75cab
The image did not have a tag that describes how to display the data.
roentgen b75cab
.PP
roentgen b75cab
\fBNo "PhotometricInterpretation" tag, assuming RGB\fP.
roentgen b75cab
The image was missing a tag that describes how to display it, but because it
roentgen b75cab
has 3 or 4 samples/pixel, it is assumed to be
roentgen b75cab
.SM RGB.
roentgen b75cab
.PP
roentgen b75cab
\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. The image was
roentgen b75cab
missing a tag that describes how to display it, but because it has 1
roentgen b75cab
sample/pixel, it is assumed to be a grayscale or bilevel image.
roentgen b75cab
.PP
roentgen b75cab
.BR "No space for photometric conversion table" .
roentgen b75cab
There was insufficient memory for a table used to convert image samples to
roentgen b75cab
8-bit
roentgen b75cab
.SM RGB.
roentgen b75cab
.PP
roentgen b75cab
\fBMissing required "Colormap" tag\fP.
roentgen b75cab
A Palette image did not have a required
roentgen b75cab
.I Colormap
roentgen b75cab
tag.
roentgen b75cab
.PP
roentgen b75cab
.BR "No space for tile buffer" .
roentgen b75cab
There was insufficient memory to allocate an i/o buffer.
roentgen b75cab
.PP
roentgen b75cab
.BR "No space for strip buffer" .
roentgen b75cab
There was insufficient memory to allocate an i/o buffer.
roentgen b75cab
.PP
roentgen b75cab
.BR "Can not handle format" .
roentgen b75cab
The image has a format (combination of
roentgen b75cab
.IR BitsPerSample ,
roentgen b75cab
.IR SamplesPerPixel ,
roentgen b75cab
and
roentgen b75cab
.IR PhotometricInterpretation )
roentgen b75cab
that
roentgen b75cab
.I TIFFReadRGBAImage
roentgen b75cab
can not handle.
roentgen b75cab
.PP
roentgen b75cab
.BR "No space for B&W mapping table" .
roentgen b75cab
There was insufficient memory to allocate a table used to map grayscale data
roentgen b75cab
to
roentgen b75cab
.SM RGB.
roentgen b75cab
.PP
roentgen b75cab
.BR "No space for Palette mapping table" .
roentgen b75cab
There was insufficient memory to allocate a table used to map data to 8-bit
roentgen b75cab
.SM RGB.
roentgen b75cab
.SH "SEE ALSO"
roentgen b75cab
.BR TIFFOpen (3TIFF),
roentgen b75cab
.BR TIFFRGBAImage (3TIFF),
roentgen b75cab
.BR TIFFReadRGBAImage (3TIFF),
roentgen b75cab
.BR TIFFReadRGBATile (3TIFF),
roentgen b75cab
.BR libtiff (3TIFF)
roentgen b75cab
.PP
roentgen b75cab
Libtiff library home page:
roentgen b75cab
.BR http://www.remotesensing.org/libtiff/
roentgen b75cab