src/tiff/man/TIFFReadRGBAImage.3tiff

.\" $Id: TIFFReadRGBAImage.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 TIFFReadRGBAImage 3TIFF "October 29, 2004" "libtiff"
.SH NAME
TIFFReadRGBAImage, TIFFReadRGBAImageOriented \- read and decode an image
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 TIFFReadRGBAImage(TIFF *" tif ", u_long " width ", u_long " height ", u_long *" raster ", int " stopOnError ")"
.br
.BI "int TIFFReadRGBAImageOriented(TIFF *" tif ", u_long " width ", u_long " height ", u_long *" raster ", int " orientation ", int " stopOnError ")"
.br
.SH DESCRIPTION
.IR TIFFReadRGBAImage
reads a strip- or tile-based image into memory, storing the
result in the user supplied
.IR raster .
The raster is assumed to be an array of
.I width
times
.I height
32-bit entries, where
.I width
must be less than or equal to the width of the image (\c
.I 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 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 lower-left hand corner.)
.PP
.IR TIFFReadRGBAImageOriented
works like
.IR TIFFReadRGBAImage
with except of that user can specify the raster origin position with the
.I orientation
parameter. Four orientations supported:
.TP
.B ORIENTATION_TOPLEFT
origin in top-left corner,
.TP
.B ORIENTATION_TOPRIGHT
origin in top-right corner,
.TP
.B ORIENTATION_BOTLEFT
origin in bottom-left corner
and
.TP
.B ORIENTATION_BOTRIGHT
origin in bottom-right corner.
.LP
If you choose
.B ORIENTATION_BOTLEFT
result will be the same as returned by the
.IR TIFFReadRGBAImage.
.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
.I TIFFReadRGBAImage
converts non-8-bit images by scaling sample values.
Palette, grayscale, bilevel,
.SM CMYK\c
, and YCbCr images are converted to
.SM RGB
transparently.
Raster pixels are returned uncorrected by any colorimetry information
present in the directory.
.PP
The paramater
.I stopOnError
specifies how to act if an error is encountered while reading
the image.
If
.I stopOnError
is non-zero, then an error will terminate the operation; otherwise
.I TIFFReadRGBAImage
will continue processing data until all the possible data in the
image have been requested.
.SH NOTES
In C++ the
.I stopOnError
parameter defaults to 0.
.PP
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
Palettte image colormaps that appear to be incorrectly written
as 8-bit values are automatically scaled to 16-bits.
.PP
.I TIFFReadRGBAImage
is just a wrapper around the more general
.IR TIFFRGBAImage (3TIFF)
facilities.
.SH "RETURN VALUES"
1 is returned if the image was successfully read and converted.
Otherwise, 0 is returned if an error was encountered and
.I stopOnError
is zero.
.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 TIFFReadRGBAStrip (3TIFF),
.BR TIFFReadRGBATile (3TIFF),
.BR libtiff (3TIFF)
.PP
Libtiff library home page:
.BR http://www.remotesensing.org/libtiff/
Commit	Line	Data
	1	.\" $Id: TIFFReadRGBAImage.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 TIFFReadRGBAImage 3TIFF "October 29, 2004" "libtiff"
	27	.SH NAME
	28	TIFFReadRGBAImage, TIFFReadRGBAImageOriented \- read and decode an image
	29	into a fixed-format raster
	30	.SH SYNOPSIS
	31	.B "#include <tiffio.h>"
	32	.sp
	33	.B "#define TIFFGetR(abgr) ((abgr) & 0xff)"
	34	.br
	35	.B "#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)"
	36	.br
	37	.B "#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)"
	38	.br
	39	.B "#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)"
	40	.sp
	41	.BI "int TIFFReadRGBAImage(TIFF " tif ", u_long " width ", u_long " height ", u_long " raster ", int " stopOnError ")"
	42	.br
	43	.BI "int TIFFReadRGBAImageOriented(TIFF " tif ", u_long " width ", u_long " height ", u_long " raster ", int " orientation ", int " stopOnError ")"
	44	.br
	45	.SH DESCRIPTION
	46	.IR TIFFReadRGBAImage
	47	reads a strip- or tile-based image into memory, storing the
	48	result in the user supplied
	49	.IR raster .
	50	The raster is assumed to be an array of
	51	.I width
	52	times
	53	.I height
	54	32-bit entries, where
	55	.I width
	56	must be less than or equal to the width of the image (\c
	57	.I height
	58	may be any non-zero size).
	59	If the raster dimensions are smaller than the image, the image data
	60	is cropped to the raster bounds.
	61	If the raster height is greater than that of the image, then the
	62	image data are placed in the lower part of the raster.
	63	(Note that the raster is assume to be organized such that the pixel
	64	at location (\fIx\fP,\fIy\fP) is \fIraster\fP[\fIy\fP*\fIwidth\fP+\fIx\fP];
	65	with the raster origin in the lower-left hand corner.)
	66	.PP
	67	.IR TIFFReadRGBAImageOriented
	68	works like
	69	.IR TIFFReadRGBAImage
	70	with except of that user can specify the raster origin position with the
	71	.I orientation
	72	parameter. Four orientations supported:
	73	.TP
	74	.B ORIENTATION_TOPLEFT
	75	origin in top-left corner,
	76	.TP
	77	.B ORIENTATION_TOPRIGHT
	78	origin in top-right corner,
	79	.TP
	80	.B ORIENTATION_BOTLEFT
	81	origin in bottom-left corner
	82	and
	83	.TP
	84	.B ORIENTATION_BOTRIGHT
	85	origin in bottom-right corner.
	86	.LP
	87	If you choose
	88	.B ORIENTATION_BOTLEFT
	89	result will be the same as returned by the
	90	.IR TIFFReadRGBAImage.
	91	.PP
	92	Raster pixels are 8-bit packed red, green, blue, alpha samples.
	93	The macros
	94	.IR TIFFGetR ,
	95	.IR TIFFGetG ,
	96	.IR TIFFGetB ,
	97	and
	98	.I TIFFGetA
	99	should be used to access individual samples.
	100	Images without Associated Alpha matting information have a constant
	101	Alpha of 1.0 (255).
	102	.PP
	103	.I TIFFReadRGBAImage
	104	converts non-8-bit images by scaling sample values.
	105	Palette, grayscale, bilevel,
	106	.SM CMYK\c
	107	, and YCbCr images are converted to
	108	.SM RGB
	109	transparently.
	110	Raster pixels are returned uncorrected by any colorimetry information
	111	present in the directory.
	112	.PP
	113	The paramater
	114	.I stopOnError
	115	specifies how to act if an error is encountered while reading
	116	the image.
	117	If
	118	.I stopOnError
	119	is non-zero, then an error will terminate the operation; otherwise
	120	.I TIFFReadRGBAImage
	121	will continue processing data until all the possible data in the
	122	image have been requested.
	123	.SH NOTES
	124	In C++ the
	125	.I stopOnError
	126	parameter defaults to 0.
	127	.PP
	128	Samples must be either 1, 2, 4, 8, or 16 bits.
	129	Colorimetric samples/pixel must be either 1, 3, or 4 (i.e.
	130	.I SamplesPerPixel
	131	minus
	132	.IR ExtraSamples ).
	133	.PP
	134	Palettte image colormaps that appear to be incorrectly written
	135	as 8-bit values are automatically scaled to 16-bits.
	136	.PP
	137	.I TIFFReadRGBAImage
	138	is just a wrapper around the more general
	139	.IR TIFFRGBAImage (3TIFF)
	140	facilities.
	141	.SH "RETURN VALUES"
	142	1 is returned if the image was successfully read and converted.
	143	Otherwise, 0 is returned if an error was encountered and
	144	.I stopOnError
	145	is zero.
	146	.SH DIAGNOSTICS
	147	All error messages are directed to the
	148	.IR TIFFError (3TIFF)
	149	routine.
	150	.PP
	151	.BR "Sorry, can not handle %d-bit pictures" .
	152	The image had
	153	.I BitsPerSample
	154	other than 1, 2, 4, 8, or 16.
	155	.PP
	156	.BR "Sorry, can not handle %d-channel images" .
	157	The image had
	158	.I SamplesPerPixel
	159	other than 1, 3, or 4.
	160	.PP
	161	\fBMissing needed "PhotometricInterpretation" tag\fP.
	162	The image did not have a tag that describes how to display
	163	the data.
	164	.PP
	165	\fBNo "PhotometricInterpretation" tag, assuming RGB\fP.
	166	The image was missing a tag that describes how to display it,
	167	but because it has 3 or 4 samples/pixel, it is assumed to be
	168	.SM RGB.
	169	.PP
	170	\fBNo "PhotometricInterpretation" tag, assuming min-is-black\fP.
	171	The image was missing a tag that describes how to display it,
	172	but because it has 1 sample/pixel, it is assumed to be a grayscale
	173	or bilevel image.
	174	.PP
	175	.BR "No space for photometric conversion table" .
	176	There was insufficient memory for a table used to convert
	177	image samples to 8-bit
	178	.SM RGB.
	179	.PP
	180	\fBMissing required "Colormap" tag\fP.
	181	A Palette image did not have a required
	182	.I Colormap
	183	tag.
	184	.PP
	185	.BR "No space for tile buffer" .
	186	There was insufficient memory to allocate an i/o buffer.
	187	.PP
	188	.BR "No space for strip buffer" .
	189	There was insufficient memory to allocate an i/o buffer.
	190	.PP
	191	.BR "Can not handle format" .
	192	The image has a format (combination of
	193	.IR BitsPerSample ,
	194	.IR SamplesPerPixel ,
	195	and
	196	.IR PhotometricInterpretation )
	197	that
	198	.I TIFFReadRGBAImage
	199	can not handle.
	200	.PP
	201	.BR "No space for B&W mapping table" .
	202	There was insufficient memory to allocate a table used to map
	203	grayscale data to
	204	.SM RGB.
	205	.PP
	206	.BR "No space for Palette mapping table" .
	207	There was insufficient memory to allocate a table used to map
	208	data to 8-bit
	209	.SM RGB.
	210	.SH "SEE ALSO"
	211	.BR TIFFOpen (3TIFF),
	212	.BR TIFFRGBAImage (3TIFF),
	213	.BR TIFFReadRGBAStrip (3TIFF),
	214	.BR TIFFReadRGBATile (3TIFF),
	215	.BR libtiff (3TIFF)
	216	.PP
	217	Libtiff library home page:
	218	.BR http://www.remotesensing.org/libtiff/