Blame man/TIFFReadRGBATile.3tiff

Packit 7838c8
.\" $Id: TIFFReadRGBATile.3tiff,v 1.3 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 TIFFReadRGBATile 3TIFF "December 10, 1998" "libtiff"
Packit 7838c8
.SH NAME
Packit 7838c8
TIFFReadRGBATile \- read and decode an image tile 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 TIFFReadRGBATile(TIFF *" tif ", uint32 " x ", uint32 " y ", uint32 *" raster ")"
Packit 7838c8
.SH DESCRIPTION
Packit 7838c8
.IR TIFFReadRGBATile
Packit 7838c8
reads a single tile of a tile-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 length 32-bit entries,
Packit 7838c8
where width is the width of a tile (TIFFTAG_TILEWIDTH) and length is the
Packit 7838c8
height of a tile (TIFFTAG_TILELENGTH). 
Packit 7838c8
Packit 7838c8
.PP
Packit 7838c8
The 
Packit 7838c8
.IR x
Packit 7838c8
and 
Packit 7838c8
.IR y
Packit 7838c8
values are the offsets from the top left corner to the top left corner of the
Packit 7838c8
tile to be read.  They must be an exact multiple of the tile width and length. 
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 tile. That is bottom to top organization.  Edge tiles which partly fall
Packit 7838c8
off the image will be filled out with appropriate zeroed areas.
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 TIFFReadRGBATile
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 tile.  The 
Packit 7838c8
.IR TIFFReadRGBAStrip() 
Packit 7838c8
function does a similar operation for stripped 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.
Packit 7838c8
The image was missing a tag that describes how to display it,
Packit 7838c8
but because it has 1 sample/pixel, it is assumed to be a grayscale
Packit 7838c8
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
Packit 7838c8
image samples to 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
Packit 7838c8
grayscale data 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 TIFFReadRGBAStrip (3TIFF),
Packit 7838c8
.BR libtiff (3TIFF)
Packit 7838c8
.PP
Packit 7838c8
Libtiff library home page:
Packit 7838c8
.BR http://www.simplesystems.org/libtiff/