|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
<html>
|
|
Packit |
85355f |
<head>
|
|
Packit |
85355f |
<meta name="generator" content="groff -Thtml, see www.gnu.org">
|
|
Packit |
85355f |
<meta name="Content-Style" content="text/css">
|
|
Packit |
85355f |
<title>TIFFRGBAImage</title>
|
|
Packit |
85355f |
</head>
|
|
Packit |
85355f |
<body>
|
|
Packit |
85355f |
|
|
Packit |
85355f |
TIFFRGBAImage
|
|
Packit |
85355f |
NAME
|
|
Packit |
85355f |
SYNOPSIS
|
|
Packit |
85355f |
DESCRIPTION
|
|
Packit |
85355f |
ALTERNATE RASTER FORMATS
|
|
Packit |
85355f |
SIMULTANEOUS RASTER STORE AND DISPLAY
|
|
Packit |
85355f |
SUPPORTING ADDITIONAL TIFF FORMATS
|
|
Packit |
85355f |
NOTES
|
|
Packit |
85355f |
RETURN VALUES
|
|
Packit |
85355f |
DIAGNOSTICS
|
|
Packit |
85355f |
SEE ALSO
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
NAME
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
TIFFRGBAImageOK, TIFFRGBAImageBegin, TIFFRGBAImageGet,
|
|
Packit |
85355f |
TIFFRGBAImageEnd − read and decode an image into a
|
|
Packit |
85355f |
raster
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
SYNOPSIS
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
#include <tiffio.h>
|
|
Packit |
85355f |
|
|
Packit |
85355f |
typedef unsigned char TIFFRGBValue; typedef struct
|
|
Packit |
85355f |
_TIFFRGBAImage TIFFRGBAImage;
|
|
Packit |
85355f |
|
|
Packit |
85355f |
int TIFFRGBAImageOK(TIFF *tif, char
|
|
Packit |
85355f |
emsg[1024])
|
|
Packit |
85355f |
int TIFFRGBAImageBegin(TIFFRGBAImage *img,
|
|
Packit |
85355f |
TIFF* tif, int stopOnError,
|
|
Packit |
85355f |
char emsg[1024])
|
|
Packit |
85355f |
int TIFFRGBAImageGet(TIFFRGBAImage *img,
|
|
Packit |
85355f |
uint32* raster, uint32 width ,
|
|
Packit |
85355f |
uint32 height)
|
|
Packit |
85355f |
void TIFFRGBAImageEnd(TIFFRGBAImage
|
|
Packit |
85355f |
*img)
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
DESCRIPTION
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
The routines described here provide a high-level
|
|
Packit |
85355f |
interface through which <small>TIFF</small> images may be
|
|
Packit |
85355f |
read into memory. Images may be strip- or tile-based and
|
|
Packit |
85355f |
have a variety of different characteristics: bits/sample,
|
|
Packit |
85355f |
samples/pixel, photometric, etc. Decoding state is
|
|
Packit |
85355f |
encapsulated in a TIFFRGBAImage structure making it
|
|
Packit |
85355f |
possible to capture state for multiple images and quickly
|
|
Packit |
85355f |
switch between them. The target raster format can be
|
|
Packit |
85355f |
customized to a particular application’s needs by
|
|
Packit |
85355f |
installing custom routines that manipulate image data
|
|
Packit |
85355f |
according to application requirements.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
The default usage for these routines is: check if an
|
|
Packit |
85355f |
image can be processed using TIFFRGBAImageOK,
|
|
Packit |
85355f |
construct a decoder state block using
|
|
Packit |
85355f |
TIFFRGBAImageBegin, read and decode an image into a
|
|
Packit |
85355f |
target raster using TIFFRGBAImageGet, and then
|
|
Packit |
85355f |
release resources using TIFFRGBAImageEnd.
|
|
Packit |
85355f |
TIFFRGBAImageGet can be called multiple times to
|
|
Packit |
85355f |
decode an image using different state parameters. If
|
|
Packit |
85355f |
multiple images are to be displayed and there is not enough
|
|
Packit |
85355f |
space for each of the decoded rasters, multiple state blocks
|
|
Packit |
85355f |
can be managed and then calls can be made to
|
|
Packit |
85355f |
TIFFRGBAImageGet as needed to display an image.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
The generated raster is assumed to be an array of
|
|
Packit |
85355f |
width times height 32-bit entries, where
|
|
Packit |
85355f |
width must be less than or equal to the width of the
|
|
Packit |
85355f |
image (height may be any non-zero size). If the
|
|
Packit |
85355f |
raster dimensions are smaller than the image, the image data
|
|
Packit |
85355f |
is cropped to the raster bounds. If the raster height is
|
|
Packit |
85355f |
greater than that of the image, then the image data are
|
|
Packit |
85355f |
placed in the lower part of the raster. (Note that the
|
|
Packit |
85355f |
raster is assume to be organized such that the pixel at
|
|
Packit |
85355f |
location (x,y) is
|
|
Packit |
85355f |
raster[y*width+x]; with the
|
|
Packit |
85355f |
raster origin in the lower-left hand corner.)
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Raster pixels are 8-bit packed red, green, blue, alpha
|
|
Packit |
85355f |
samples. The macros TIFFGetR, TIFFGetG,
|
|
Packit |
85355f |
TIFFGetB, and TIFFGetA should be used to
|
|
Packit |
85355f |
access individual samples. Images without Associated Alpha
|
|
Packit |
85355f |
matting information have a constant Alpha of 1.0 (255).
|
|
Packit |
85355f |
|
|
Packit |
85355f |
TIFFRGBAImageGet converts non-8-bit images by
|
|
Packit |
85355f |
scaling sample values. Palette, grayscale, bilevel,
|
|
Packit |
85355f |
<small>CMYK</small> , and YCbCr images are converted to
|
|
Packit |
85355f |
<small>RGB</small> transparently. Raster pixels are returned
|
|
Packit |
85355f |
uncorrected by any colorimetry information present in the
|
|
Packit |
85355f |
directory.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
The parameter stopOnError specifies how to act if
|
|
Packit |
85355f |
an error is encountered while reading the image. If
|
|
Packit |
85355f |
stopOnError is non-zero, then an error will terminate
|
|
Packit |
85355f |
the operation; otherwise TIFFRGBAImageGet will
|
|
Packit |
85355f |
continue processing data until all the possible data in the
|
|
Packit |
85355f |
image have been requested.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
ALTERNATE RASTER FORMATS
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
To use the core support for reading and processing
|
|
Packit |
85355f |
<small>TIFF</small> images, but write the resulting raster
|
|
Packit |
85355f |
data in a different format one need only override the
|
|
Packit |
85355f |
‘‘put methods’’ used to store
|
|
Packit |
85355f |
raster data. These methods are are defined in the
|
|
Packit |
85355f |
TIFFRGBAImage structure and initially setup by
|
|
Packit |
85355f |
TIFFRGBAImageBegin to point to routines that pack
|
|
Packit |
85355f |
raster data in the default <small>ABGR</small> pixel format.
|
|
Packit |
85355f |
Two different routines are used according to the physical
|
|
Packit |
85355f |
organization of the image data in the file:
|
|
Packit |
85355f |
PlanarConfiguration=1 (packed samples), and
|
|
Packit |
85355f |
PlanarConfiguration=2 (separated samples). Note that
|
|
Packit |
85355f |
this mechanism can be used to transform the data before
|
|
Packit |
85355f |
storing it in the raster. For example one can convert data
|
|
Packit |
85355f |
to colormap indices for display on a colormap display.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
SIMULTANEOUS RASTER STORE AND DISPLAY
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
It is simple to display an image as it is being read into
|
|
Packit |
85355f |
memory by overriding the put methods as described above for
|
|
Packit |
85355f |
supporting alternate raster formats. Simply keep a reference
|
|
Packit |
85355f |
to the default put methods setup by
|
|
Packit |
85355f |
TIFFRGBAImageBegin and then invoke them before or
|
|
Packit |
85355f |
after each display operation. For example, the
|
|
Packit |
85355f |
tiffgt(1) utility uses the following put method to
|
|
Packit |
85355f |
update the display as the raster is being filled:
|
|
Packit |
85355f |
|
|
Packit |
85355f |
static void
|
|
Packit |
85355f |
putContigAndDraw(TIFFRGBAImage* img, uint32* raster,
|
|
Packit |
85355f |
uint32 x, uint32 y, uint32 w, uint32 h,
|
|
Packit |
85355f |
int32 fromskew, int32 toskew,
|
|
Packit |
85355f |
unsigned char* cp)
|
|
Packit |
85355f |
{
|
|
Packit |
85355f |
(*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp);
|
|
Packit |
85355f |
if (x+w == width) {
|
|
Packit |
85355f |
w = width;
|
|
Packit |
85355f |
if (img->orientation == ORIENTATION_TOPLEFT)
|
|
Packit |
85355f |
lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w);
|
|
Packit |
85355f |
else
|
|
Packit |
85355f |
lrectwrite(0, y, w-1, y+h-1, raster);
|
|
Packit |
85355f |
}
|
|
Packit |
85355f |
}
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
(the original routine provided by the library is saved in
|
|
Packit |
85355f |
the variable putContig.)
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
SUPPORTING ADDITIONAL TIFF FORMATS
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
The TIFFRGBAImage routines support the most
|
|
Packit |
85355f |
commonly encountered flavors of <small>TIFF.</small> It is
|
|
Packit |
85355f |
possible to extend this support by overriding the
|
|
Packit |
85355f |
‘‘get method’’ invoked by
|
|
Packit |
85355f |
TIFFRGBAImageGet to read <small>TIFF</small> image
|
|
Packit |
85355f |
data. Details of doing this are a bit involved, it is best
|
|
Packit |
85355f |
to make a copy of an existing get method and modify it to
|
|
Packit |
85355f |
suit the needs of an application.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
NOTES
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Samples must be either 1, 2, 4, 8, or 16 bits.
|
|
Packit |
85355f |
Colorimetric samples/pixel must be either 1, 3, or 4 (i.e.
|
|
Packit |
85355f |
SamplesPerPixel minus ExtraSamples).
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Palette image colormaps that appear to be incorrectly
|
|
Packit |
85355f |
written as 8-bit values are automatically scaled to
|
|
Packit |
85355f |
16-bits.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
RETURN VALUES
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
All routines return 1 if the operation was successful.
|
|
Packit |
85355f |
Otherwise, 0 is returned if an error was encountered and
|
|
Packit |
85355f |
stopOnError is zero.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
DIAGNOSTICS
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
All error messages are directed to the
|
|
Packit |
85355f |
TIFFError(3TIFF) routine.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Sorry, can not handle %d-bit pictures. The image
|
|
Packit |
85355f |
had BitsPerSample other than 1, 2, 4, 8, or 16.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Sorry, can not handle %d-channel images. The image
|
|
Packit |
85355f |
had SamplesPerPixel other than 1, 3, or 4.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Missing needed "PhotometricInterpretation"
|
|
Packit |
85355f |
tag. The image did not have a tag that describes how to
|
|
Packit |
85355f |
display the data.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
No "PhotometricInterpretation" tag, assuming
|
|
Packit |
85355f |
RGB. The image was missing a tag that describes how to
|
|
Packit |
85355f |
display it, but because it has 3 or 4 samples/pixel, it is
|
|
Packit |
85355f |
assumed to be <small>RGB.</small>
|
|
Packit |
85355f |
|
|
Packit |
85355f |
No "PhotometricInterpretation" tag, assuming
|
|
Packit |
85355f |
min-is-black. The image was missing a tag that describes
|
|
Packit |
85355f |
how to display it, but because it has 1 sample/pixel, it is
|
|
Packit |
85355f |
assumed to be a grayscale or bilevel image.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
No space for photometric conversion table. There
|
|
Packit |
85355f |
was insufficient memory for a table used to convert image
|
|
Packit |
85355f |
samples to 8-bit <small>RGB.</small>
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Missing required "Colormap" tag. A
|
|
Packit |
85355f |
Palette image did not have a required Colormap
|
|
Packit |
85355f |
tag.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
No space for tile buffer. There was insufficient
|
|
Packit |
85355f |
memory to allocate an i/o buffer.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
No space for strip buffer. There was insufficient
|
|
Packit |
85355f |
memory to allocate an i/o buffer.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Can not handle format. The image has a format
|
|
Packit |
85355f |
(combination of BitsPerSample,
|
|
Packit |
85355f |
SamplesPerPixel, and
|
|
Packit |
85355f |
PhotometricInterpretation) that can not be
|
|
Packit |
85355f |
handled.
|
|
Packit |
85355f |
|
|
Packit |
85355f |
No space for B&W mapping table. There was
|
|
Packit |
85355f |
insufficient memory to allocate a table used to map
|
|
Packit |
85355f |
grayscale data to <small>RGB.</small>
|
|
Packit |
85355f |
|
|
Packit |
85355f |
No space for Palette mapping table. There was
|
|
Packit |
85355f |
insufficient memory to allocate a table used to map data to
|
|
Packit |
85355f |
8-bit <small>RGB.</small>
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
SEE ALSO
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
cols="2" cellspacing="0" cellpadding="0">
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
TIFFOpen(3TIFF), TIFFReadRGBAImage(3TIFF),
|
|
Packit |
85355f |
TIFFReadRGBAImageOriented(3TIFF),
|
|
Packit |
85355f |
TIFFReadRGBAStrip(3TIFF),
|
|
Packit |
85355f |
TIFFReadRGBATile(3TIFF), libtiff(3TIFF)
|
|
Packit |
85355f |
|
|
Packit |
85355f |
Libtiff library home page:
|
|
Packit |
85355f |
http://www.simplesystems.org/libtiff/
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
|
|
Packit |
85355f |
</body>
|
|
Packit |
85355f |
</html>
|