src/tiff/man/TIFFReadRGBAStrip.3tiff

.\" $Id: TIFFReadRGBAStrip.3tiff,v 1.3 2005/11/02 11:07:18 dron Exp $
.\"
.\" Copyright (c) 1991-1997 Sam Leffler
.\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
.\"
.\" Permission to use, copy, modify, distribute, and sell this software and
.\" its documentation for any purpose is hereby granted without fee, provided
.\" that (i) the above copyright notices and this permission notice appear in
.\" all copies of the software and related documentation, and (ii) the names of
.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
.\" publicity relating to the software without the specific, prior written
.\" permission of Sam Leffler and Silicon Graphics.
.\"
.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
.\"
.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
.\" OF THIS SOFTWARE.
.\"
.if n .po 0
.TH TIFFReadRGBAStrip 3TIFF "December 10, 1998" "libtiff"
.SH NAME
TIFFReadRGBAStrip \- read and decode an image strip into a fixed-format raster
.SH SYNOPSIS
.B "#include <tiffio.h>"
.sp
.B "#define TIFFGetR(abgr) ((abgr) & 0xff)"
.br
.B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)"
.br
.B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)"
.br
.B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)"
.sp
.BI "int TIFFReadRGBAStrip(TIFF *" tif ", uint32 " row ", uint32 *" raster ")"
.SH DESCRIPTION
.IR TIFFReadRGBAStrip
reads a single strip of a strip-based image into memory, storing the result in
the user supplied RGBA
.IR raster .
The raster is assumed to be an array of width times rowsperstrip 32-bit
entries, where width is the width of the image (TIFFTAG_IMAGEWIDTH) and
rowsperstrip is the maximum lines in a strip (TIFFTAG_ROWSPERSTRIP).

.PP
The
.IR row
value should be the row of the first row in the strip (strip * rowsperstrip,
zero based).

.PP
Note that the raster is assume to be organized such that the pixel at location
(\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; with the
raster origin in the
.I lower-left hand corner
of the strip. That is bottom to top organization.  When reading a partial last
strip in the file the last line of the image will begin at the beginning of
the buffer.

.PP
Raster pixels are 8-bit packed red, green, blue, alpha samples. The macros
.IR TIFFGetR ,
.IR TIFFGetG ,
.IR TIFFGetB ,
and
.I TIFFGetA
should be used to access individual samples. Images without Associated Alpha
matting information have a constant Alpha of 1.0 (255).
.PP
See the
.IR TIFFRGBAImage (3TIFF)
page for more details on how various image types are converted to RGBA values.
.SH NOTES
Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel must
be either 1, 3, or 4 (i.e.
.I SamplesPerPixel
minus
.IR ExtraSamples ).
.PP
Palette image colormaps that appear to be incorrectly written as 8-bit values
are automatically scaled to 16-bits.
.PP
.I TIFFReadRGBAStrip
is just a wrapper around the more general
.IR TIFFRGBAImage (3TIFF)
facilities.  It's main advantage over the similar
.IR TIFFReadRGBAImage()
function is that for large images a single buffer capable of holding the whole
image doesn't need to be allocated, only enough for one strip.  The
.IR TIFFReadRGBATile()
function does a similar operation for tiled images.
.SH "RETURN VALUES"
1 is returned if the image was successfully read and converted.
Otherwise, 0 is returned if an error was encountered.
.SH DIAGNOSTICS
All error messages are directed to the
.IR TIFFError (3TIFF)
routine.
.PP
.BR "Sorry, can not handle %d-bit pictures" .
The image had
.I BitsPerSample
other than 1, 2, 4, 8, or 16.
.PP
.BR "Sorry, can not handle %d-channel images" .
The image had
.I SamplesPerPixel
other than 1, 3, or 4.
.PP
\fBMissing needed "PhotometricInterpretation" tag\fP.
The image did not have a tag that describes how to display the data.
.PP
\fBNo "PhotometricInterpretation" tag, assuming RGB\fP.
The image was missing a tag that describes how to display it, but because it
has 3 or 4 samples/pixel, it is assumed to be
.SM RGB.
.PP
\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. 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.
.PP
.BR "No space for photometric conversion table" .
There was insufficient memory for a table used to convert image samples to
8-bit
.SM RGB.
.PP
\fBMissing required "Colormap" tag\fP.
A Palette image did not have a required
.I Colormap
tag.
.PP
.BR "No space for tile buffer" .
There was insufficient memory to allocate an i/o buffer.
.PP
.BR "No space for strip buffer" .
There was insufficient memory to allocate an i/o buffer.
.PP
.BR "Can not handle format" .
The image has a format (combination of
.IR BitsPerSample ,
.IR SamplesPerPixel ,
and
.IR PhotometricInterpretation )
that
.I TIFFReadRGBAImage
can not handle.
.PP
.BR "No space for B&W mapping table" .
There was insufficient memory to allocate a table used to map grayscale data
to
.SM RGB.
.PP
.BR "No space for Palette mapping table" .
There was insufficient memory to allocate a table used to map data to 8-bit
.SM RGB.
.SH "SEE ALSO"
.BR TIFFOpen (3TIFF),
.BR TIFFRGBAImage (3TIFF),
.BR TIFFReadRGBAImage (3TIFF),
.BR TIFFReadRGBATile (3TIFF),
.BR libtiff (3TIFF)
.PP
Libtiff library home page:
.BR http://www.remotesensing.org/libtiff/
Commit	Line	Data
	1	.\" $Id: TIFFReadRGBAStrip.3tiff,v 1.3 2005/11/02 11:07:18 dron Exp $
	2	.\"
	3	.\" Copyright (c) 1991-1997 Sam Leffler
	4	.\" Copyright (c) 1991-1997 Silicon Graphics, Inc.
	5	.\"
	6	.\" Permission to use, copy, modify, distribute, and sell this software and
	7	.\" its documentation for any purpose is hereby granted without fee, provided
	8	.\" that (i) the above copyright notices and this permission notice appear in
	9	.\" all copies of the software and related documentation, and (ii) the names of
	10	.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
	11	.\" publicity relating to the software without the specific, prior written
	12	.\" permission of Sam Leffler and Silicon Graphics.
	13	.\"
	14	.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
	15	.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
	16	.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
	17	.\"
	18	.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
	19	.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
	20	.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
	21	.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
	22	.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
	23	.\" OF THIS SOFTWARE.
	24	.\"
	25	.if n .po 0
	26	.TH TIFFReadRGBAStrip 3TIFF "December 10, 1998" "libtiff"
	27	.SH NAME
	28	TIFFReadRGBAStrip \- read and decode an image strip into a fixed-format raster
	29	.SH SYNOPSIS
	30	.B "#include <tiffio.h>"
	31	.sp
	32	.B "#define TIFFGetR(abgr) ((abgr) & 0xff)"
	33	.br
	34	.B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)"
	35	.br
	36	.B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)"
	37	.br
	38	.B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)"
	39	.sp
	40	.BI "int TIFFReadRGBAStrip(TIFF " tif ", uint32 " row ", uint32 " raster ")"
	41	.SH DESCRIPTION
	42	.IR TIFFReadRGBAStrip
	43	reads a single strip of a strip-based image into memory, storing the result in
	44	the user supplied RGBA
	45	.IR raster .
	46	The raster is assumed to be an array of width times rowsperstrip 32-bit
	47	entries, where width is the width of the image (TIFFTAG_IMAGEWIDTH) and
	48	rowsperstrip is the maximum lines in a strip (TIFFTAG_ROWSPERSTRIP).
	49
	50	.PP
	51	The
	52	.IR row
	53	value should be the row of the first row in the strip (strip * rowsperstrip,
	54	zero based).
	55
	56	.PP
	57	Note that the raster is assume to be organized such that the pixel at location
	58	(\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP]; with the
	59	raster origin in the
	60	.I lower-left hand corner
	61	of the strip. That is bottom to top organization. When reading a partial last
	62	strip in the file the last line of the image will begin at the beginning of
	63	the buffer.
	64
	65	.PP
	66	Raster pixels are 8-bit packed red, green, blue, alpha samples. The macros
	67	.IR TIFFGetR ,
	68	.IR TIFFGetG ,
	69	.IR TIFFGetB ,
	70	and
	71	.I TIFFGetA
	72	should be used to access individual samples. Images without Associated Alpha
	73	matting information have a constant Alpha of 1.0 (255).
	74	.PP
	75	See the
	76	.IR TIFFRGBAImage (3TIFF)
	77	page for more details on how various image types are converted to RGBA values.
	78	.SH NOTES
	79	Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel must
	80	be either 1, 3, or 4 (i.e.
	81	.I SamplesPerPixel
	82	minus
	83	.IR ExtraSamples ).
	84	.PP
	85	Palette image colormaps that appear to be incorrectly written as 8-bit values
	86	are automatically scaled to 16-bits.
	87	.PP
	88	.I TIFFReadRGBAStrip
	89	is just a wrapper around the more general
	90	.IR TIFFRGBAImage (3TIFF)
	91	facilities. It's main advantage over the similar
	92	.IR TIFFReadRGBAImage()
	93	function is that for large images a single buffer capable of holding the whole
	94	image doesn't need to be allocated, only enough for one strip. The
	95	.IR TIFFReadRGBATile()
	96	function does a similar operation for tiled images.
	97	.SH "RETURN VALUES"
	98	1 is returned if the image was successfully read and converted.
	99	Otherwise, 0 is returned if an error was encountered.
	100	.SH DIAGNOSTICS
	101	All error messages are directed to the
	102	.IR TIFFError (3TIFF)
	103	routine.
	104	.PP
	105	.BR "Sorry, can not handle %d-bit pictures" .
	106	The image had
	107	.I BitsPerSample
	108	other than 1, 2, 4, 8, or 16.
	109	.PP
	110	.BR "Sorry, can not handle %d-channel images" .
	111	The image had
	112	.I SamplesPerPixel
	113	other than 1, 3, or 4.
	114	.PP
	115	\fBMissing needed "PhotometricInterpretation" tag\fP.
	116	The image did not have a tag that describes how to display the data.
	117	.PP
	118	\fBNo "PhotometricInterpretation" tag, assuming RGB\fP.
	119	The image was missing a tag that describes how to display it, but because it
	120	has 3 or 4 samples/pixel, it is assumed to be
	121	.SM RGB.
	122	.PP
	123	\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP. The image was
	124	missing a tag that describes how to display it, but because it has 1
	125	sample/pixel, it is assumed to be a grayscale or bilevel image.
	126	.PP
	127	.BR "No space for photometric conversion table" .
	128	There was insufficient memory for a table used to convert image samples to
	129	8-bit
	130	.SM RGB.
	131	.PP
	132	\fBMissing required "Colormap" tag\fP.
	133	A Palette image did not have a required
	134	.I Colormap
	135	tag.
	136	.PP
	137	.BR "No space for tile buffer" .
	138	There was insufficient memory to allocate an i/o buffer.
	139	.PP
	140	.BR "No space for strip buffer" .
	141	There was insufficient memory to allocate an i/o buffer.
	142	.PP
	143	.BR "Can not handle format" .
	144	The image has a format (combination of
	145	.IR BitsPerSample ,
	146	.IR SamplesPerPixel ,
	147	and
	148	.IR PhotometricInterpretation )
	149	that
	150	.I TIFFReadRGBAImage
	151	can not handle.
	152	.PP
	153	.BR "No space for B&W mapping table" .
	154	There was insufficient memory to allocate a table used to map grayscale data
	155	to
	156	.SM RGB.
	157	.PP
	158	.BR "No space for Palette mapping table" .
	159	There was insufficient memory to allocate a table used to map data to 8-bit
	160	.SM RGB.
	161	.SH "SEE ALSO"
	162	.BR TIFFOpen (3TIFF),
	163	.BR TIFFRGBAImage (3TIFF),
	164	.BR TIFFReadRGBAImage (3TIFF),
	165	.BR TIFFReadRGBATile (3TIFF),
	166	.BR libtiff (3TIFF)
	167	.PP
	168	Libtiff library home page:
	169	.BR http://www.remotesensing.org/libtiff/
	170