Blame man/TIFFReadRGBAStrip.3tiff

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