Current File : //usr/share/man/man3tiff/TIFFReadRGBAImage.3tiff

'\" te
.TH TIFFReadRGBAImage 3tiff "05 Apr 2004" "" ""
.SH "NAME"
TIFFReadRGBAImage \- read and decode an image into a fixed-format raster
.SH "SYNOPSIS"
.sp
.nf
\f(CW#include <tiffio\&.h>
#define TIFFGetR(abgr) ((abgr) & 0xff)
#define TIFFGetG(abgr) (((abgr) >> 8) & 0xff)
#define TIFFGetB(abgr) (((abgr) >> 16) & 0xff)
#define TIFFGetA(abgr) (((abgr) >> 24) & 0xff)
int TIFFReadRGBAImage(TIFF* tif, u_long width, u_long height, u_long* raster, int stopOnError)\fR
.fi
.sp
.SH ""
.PP
\fBTIFFReadRGBAImage\fR reads a strip- or tile-based image
into memory, storing the result in the user-supplied raster\&. The raster is
assumed to be an array of \fIwidth\fR times \fIheight\fR 32-bit entries, where \fIwidth\fR must be less than or equal to the width of the image, and \fIheight\fR 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 is
placed in the lower part of the raster\&. Note that the raster is assumed to
be organized such that the pixel at location (\fIx,y\fR)
is \fIraster[y*width+x]\fR, with the raster origin in
the bottom-left corner\&.
.SH "EXTENDED DESCRIPTION"
.PP
Raster pixels are 8-bit packed red, green, blue, alpha samples\&. The
macros \fBTIFFGetR\fR, \fBTIFFGetG\fR, \fBTIFFGetB\fR, and \fBTIFFGetA\fR should be used to access
individual samples\&. Images without Associated Alpha matting information have
a constant Alpha of 1\&.0 (255)\&.
.PP
\fBTIFFReadRGBAImage\fR converts non-8-bit images by scaling
sample values\&. Palette, grayscale, bilevel, CMYK, and YCbCr images are converted
to RGB transparently\&. Raster pixels are returned uncorrected by any colorimetry
information present in the directory\&.
.PP
The parameter \fBstopOnError\fR specifies how to act if
an error is encountered while reading the image\&. If \fBstopOnError\fR
is non-zero, then an error terminates the operation\&. Otherwise, \fBTIFFReadRGBAImage\fR continues to process data until all of the possible
data in the image has been requested\&.
.PP
Samples must be either 1, 2, 4, 8, or 16 bits\&. Colorimetric samples/pixel
must be either 1, 3, or 4 (that is, \fBSamplesPerPixel\fR minus \fBExtraSamples\fR)\&.
.PP
Palette image colormaps that appear to be incorrectly written as 8-bit
values are automatically scaled to 16-bits\&.
.PP
\fBTIFFReadRGBAImage\fR is just a wrapper around the more
general \fBTIFFRGBAImage(3tiff)\fR facilities\&.
.SS "Diagnostics"
.PP
All error messages are directed to the \fBTIFFError(3tiff)\fR
routine\&.
.sp
.ne 2
.mk
\fBSorry, can not handle %d-bit pictures\&.\fR
.sp .6
.in +4
The image has a \fBBitsPerSample\fR value other than 1,
2, 4, 8, or 16\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBSorry, can not handle %d-channel images\&.\fR
.sp .6
.in +4
The image has a \fBSamplesPerPixel\fR value other than
1, 3, or 4\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBMissing needed "PhotometricInterpretation" tag\&.\fR
.sp .6
.in +4
The image does not have a tag that describes how to display
the data\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBNo "PhotometricInterpretation" tag, assuming RGB\&.\fR
.sp .6
.in +4
The image does not have a tag that describes how to display
the data, but is assumed to be RGB because the image has 3 or 4 samples/pixel\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBNo "PhotometricInterpretation" tag, assuming min-is-black\&.\fR
.sp .6
.in +4
The image does not have a tag that describes how to
display the data, but is assumed to be a grayscale or bilevel image because
the image has 1 sample/pixel\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBNo space for photometric conversion table\&.\fR
.sp .6
.in +4
There is insufficient memory for a table needed to convert image samples
to 8-bit RGB\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBMissing required "Colormap" tag\&.\fR
.sp .6
.in +4
A Palette image does not have a required \fBColormap\fR tag\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBNo space for tile buffer\&.\fR
.sp .6
.in +4
There
is insufficient memory to allocate an i/o buffer\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBNo space for strip buffer\&.\fR
.sp .6
.in +4
There
is insufficient memory to allocate an i/o buffer\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBCan not handle format\&.\fR
.sp .6
.in +4
The image
has a format (combination of \fBBitsPerSample\fR, \fBSamplesPerPixel\fR, and \fBPhotometricInterpretation\fR) that \fBTIFFReadRGBAImage\fR cannot process\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBNo space for B&W mapping table\&.\fR
.sp .6
.in +4
There is insufficient memory to allocate a table needed to map grayscale data
to RGB\&.
.sp
.sp 1
.in -4
.sp
.ne 2
.mk
\fBNo space for Palette mapping table\&.\fR
.sp .6
.in +4
There is insufficient memory to allocate a table needed to map data to 8-bit
RGB\&.
.sp
.sp 1
.in -4
.SH ""
.PP
1 is returned if the image was successfully read and converted\&. Otherwise,
0 is returned if an error was encountered and \fBstopOnError\fR
is zero\&.
.SH ""
.PP
See \fBattributes\fR(5)
for descriptions of the following attributes:
.sp
.TS
tab() allbox;
cw(2.750000i)| cw(2.750000i)
lw(2.750000i)| lw(2.750000i).
ATTRIBUTE TYPEATTRIBUTE VALUE
Availabilityimage/library/libtiff
Interface stabilityUncommitted
.TE
.sp
.SH ""
.PP
\fBlibtiff\fR(3), \fBTIFFOpen\fR(3tiff), \fBTIFFRGBAImage\fR(3tiff), \fBTIFFReadRGBAStrip\fR(3tiff), \fBTIFFReadRGBATile\fR(3tiff)
.SH ""
.PP
Orientations other than bottom-left or top-left are not processed correctly\&.
.PP
In C++, the \fBstopOnError\fR parameter defaults to 0\&.
.PP
This man page was originally written by Sam Leffler\&. Updated by Breda McColgan, Sun Microsystems Inc\&., 2004\&.
...\" created by instant / solbook-to-man, Thu 20 Mar 2014, 02:30
...\" LSARC 2003/085 libtiff, libjpeg, and libpng