TIFFRGBAImage(3tiff)TIFFRGBAImage(3tiff)NAME
TIFFRGBAImage, TIFFRGBAImageBegin, TIFFRGBAImageEnd, TIFFRGBAImageGet,
TIFFRGBAImageOK, TIFFRGBAImageOriented - read and decode an image into
a raster
SYNOPSIS
#include <tiffio.h>
typedef unsigned char TIFFRGBValue;
typedef struct _TIFFRGBAImage TIFFRGBAImage;
int TIFFRGBAImageOK(TIFF* tif, char emsg[1024]);
int TIFFRGBAImageBegin(TIFFRGBAImage* img, TIFF* tif, int stopOnError, char emsg[1024]);
int TIFFRGBAImageGet(TIFFRGBAImage* img, uint32* raster, uint32 width, uint32 height);
void TIFFRGBAImageEnd(TIFFRGBAImage* img);
The routines described here provide a high-level interface through
which TIFF images may be read into memory. Images may be strip- or
tile-based and have a variety of different characteristics: bits/sam‐
ple, samples/pixel, photometric, and so on. Decoding state is encapsu‐
lated in a TIFFRGBAImage structure, which makes it possible to capture
state for multiple images and quickly switch between them. The target
raster format can be customized to the needs of a particular applica‐
tion by installing custom routines that manipulate image data according
to application requirements.
The default usage of these routines is as follows:
1. Use TIFFRGBAImageOK to check whether an image can be processed.
2. Use TIFFRGBAImageBegin to construct a decoder state block.
3. Use TIFFRGBAImageGet to read and decode an image into a target
raster.
4. Use TIFFRGBAImageEnd to release resources.
TIFFRGBAImageGet can be called multiple times to decode an image using
different state parameters. If multiple images are to be displayed and
there is not enough space for each of the decoded rasters, multiple
state blocks can be managed and then calls can be made to TIFFRGBAIm‐
ageGet as needed to display an image.
The generated raster is assumed to be an array of width times height
32-bit entries, where width must be less than or equal to the width of
the image, and height may be any non-zero size. If the raster dimen‐
sions 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 loca‐
tion (x,y) is raster[y*width+x], with the raster origin in the bottom-
left corner.
EXTENDED DESCRIPTION
Raster pixels are 8-bit packed red, green, blue, alpha samples. The
macros TIFFGetR, TIFFGetG, TIFFGetB, and TIFFGetA should be used to
access individual samples. Images without Associated Alpha matting
information have a constant Alpha of 1.0 (255).
TIFFRGBAImageGet 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 col‐
orimetry information present in the directory.
The parameter stopOnError specifies how to act if an error is encoun‐
tered while reading the image. If stopOnError is non-zero, then an
error terminates the operation. Otherwise, TIFFRGBAImageGet continues
to process data until all of the possible data in the image has been
requested.
Alternate Raster Formats
To use the core support for reading and processing TIFF images, but
write the resulting raster data in a different format, you need only
override the "put methods" used to store raster data. These methods are
defined in the TIFFRGBAImage structure and initially set up by TIFFRG‐
BAImageBegin to point to routines that pack raster data in the default
ABGR pixel format.
Two different routines are used according to the physical organization
of the image data in the file:
· PlanarConfiguration=1 (packed samples)
· PlanarConfiguration=2 (separated samples).
Note that this mechanism can be used to transform the data before stor‐
ing the data in the raster. For example, you can convert data to col‐
ormap indices for display on a colormap display.
Simultaneous Raster Store and Display
An image can be displayed as the image is being into memory by overrid‐
ing the put methods as described above to support alternate raster for‐
mats. Simply keep a reference to the default put methods set up by
TIFFRGBAImageBegin and then invoke these methods before or after each
display operation. For example, the tiffgt(1) utility uses the follow‐
ing put method to update the display as the raster is being filled:
static void
putContigAndDraw(TIFFRGBAImage* img, uint32* raster,
uint32 x, uint32 y, uint32 w, uint32 h,
int32 fromskew, int32 toskew,
unsigned char* cp)
{
(*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp);
if (x+w == width) {
w = width;
if (img->orientation == ORIENTATION_TOPLEFT)
lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w);
else
lrectwrite(0, y, w-1, y+h-1, raster);
}
}
The original routine provided by the library is saved in the variable
putContig.
Supporting Additional TIFF Formats
The TIFFRGBAImage routines support the most commonly encountered fla‐
vors of TIFF. You can extend this support by overriding the "get
method" invoked by TIFFRGBAImageGet to read TIFF image data. Details of
how to do this can be quite involved, it is best to make a copy of an
existing get method and modify to suit the needs of an application.
Diagnostics
All error messages are directed to the TIFFError(3tiff) routine.
Sorry, can not handle %d-bit pictures.
The image has a BitsPerSample value other than 1, 2, 4, 8, or 16.
Sorry, can not handle %d-channel images.
The image has a SamplesPerPixel value other than 1, 3, or 4.
Missing needed "PhotometricInterpretation" tag.
The image does not have a tag that describes how to display the
data.
No "PhotometricInterpretation" tag, assuming RGB.
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 sam‐
ples/pixel.
No "PhotometricInterpretation" tag, assuming min-is-black.
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.
No space for photometric conversion table.
There is insufficient memory for a table needed to convert image
samples to 8-bit RGB.
Missing required "Colormap" tag.
A Palette image does not have a required Colormap tag.
No space for tile buffer.
There is insufficient memory to allocate an i/o buffer.
No space for strip buffer.
There is insufficient memory to allocate an i/o buffer.
Can not handle format.
The image has a format (combination of BitsPerSample, SamplesPer‐
Pixel, and PhotometricInterpretation) that TIFFReadRGBAImage cannot
process.
No space for B&W mapping table.
There is insufficient memory to allocate a table needed to map
grayscale data to RGB.
No space for Palette mapping table.
There is insufficient memory to allocate a table needed to map data
to 8-bit RGB.
All routines return 1 if the operation was successful. Otherwise, 0 is
returned if an error was encountered and stopOnError is zero.
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │image/library/libtiff │
├─────────────────────────────┼─────────────────────────────┤
│Interface stability │Uncommitted │
└─────────────────────────────┴─────────────────────────────┘
libtiff(3), TIFFOpen(3tiff), TIFFReadRGBAImage(3tiff), TIFFReadRGBAS‐
trip(3tiff), TIFFReadRGBATile(3tiff)
Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric sam‐
ples/pixel must be either 1, 3, or 4 (that is, SamplesPerPixel minus
ExtraSamples).
Palette image colormaps that appear to be incorrectly written as 8-bit
values are automatically scaled to 16-bits.
Orientations other than bottom-left or top-left are not processed cor‐
rectly.
This man page was originally written by Sam Leffler. Updated by Breda
McColgan, Sun Microsystems Inc., 2004.
05 Apr 2004 TIFFRGBAImage(3tiff)
