[wxWidgets.git] / 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
8414a40c VZ	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/