1TIFFRGBAImage(3TIFF) TIFFRGBAImage(3TIFF)
2
6 TIFFRGBAImageOK, TIFFRGBAImageBegin, TIFFRGBAImageGet, TIFFRGBAImageEnd
7 - read and decode an image into a raster
8
10 #include <tiffio.h>
11 typedef unsigned char TIFFRGBValue; typedef struct _TIFFRGBAImage
13 TIFFRGBAImage;
14 int TIFFRGBAImageOK(TIFF *tif, char emsg[1024])
16 int TIFFRGBAImageBegin(TIFFRGBAImage *img, TIFF* tif, int stopOnError,
17 char emsg[1024])
18 int TIFFRGBAImageGet(TIFFRGBAImage *img, uint32* raster, uint32 width ,
19 uint32 height)
20 void TIFFRGBAImageEnd(TIFFRGBAImage *img)
21
23 The routines described here provide a high-level interface through
24 which TIFF images may be read into memory. Images may be strip- or
25 tile-based and have a variety of different characteristics: bits/sam‐
26 ple, samples/pixel, photometric, etc. Decoding state is encapsulated
27 in a TIFFRGBAImage structure making it possible to capture state for
28 multiple images and quickly switch between them. The target raster
29 format can be customized to a particular application's needs by
30 installing custom routines that manipulate image data according to
31 application requirements.
32 The default usage for these routines is: check if an image can be pro‐
34 cessed using TIFFRGBAImageOK, construct a decoder state block using
35 TIFFRGBAImageBegin, read and decode an image into a target raster using
36 TIFFRGBAImageGet, and then release resources using TIFFRGBAImageEnd.
37 TIFFRGBAImageGet can be called multiple times to decode an image using
38 different state parameters. If multiple images are to be displayed and
39 there is not enough space for each of the decoded rasters, multiple
40 state blocks can be managed and then calls can be made to TIFFRGBAIm‐
41 ageGet as needed to display an image.
42 The generated raster is assumed to be an array of width times height
44 32-bit entries, where width must be less than or equal to the width of
45 the image (height may be any non-zero size). If the raster dimensions
46 are smaller than the image, the image data is cropped to the raster
47 bounds. If the raster height is greater than that of the image, then
48 the image data are placed in the lower part of the raster. (Note that
49 the raster is assume to be organized such that the pixel at location
50 (x,y) is raster[y*width+x]; with the raster origin in the lower-left
51 hand corner.)
52 Raster pixels are 8-bit packed red, green, blue, alpha samples. The
54 macros TIFFGetR, TIFFGetG, TIFFGetB, and TIFFGetA should be used to
55 access individual samples. Images without Associated Alpha matting
56 information have a constant Alpha of 1.0 (255).
57 TIFFRGBAImageGet converts non-8-bit images by scaling sample values.
59 Palette, grayscale, bilevel, CMYK, and YCbCr images are converted to
60 RGB transparently. Raster pixels are returned uncorrected by any col‐
61 orimetry information present in the directory.
62 The parameter stopOnError specifies how to act if an error is encoun‐
64 tered while reading the image. If stopOnError is non-zero, then an
65 error will terminate the operation; otherwise TIFFRGBAImageGet will
66 continue processing data until all the possible data in the image have
67 been requested.
68
70 To use the core support for reading and processing TIFF images, but
71 write the resulting raster data in a different format one need only
72 override the ``put methods'' used to store raster data. These methods
73 are are defined in the TIFFRGBAImage structure and initially setup by
74 TIFFRGBAImageBegin to point to routines that pack raster data in the
75 default ABGR pixel format. Two different routines are used according
76 to the physical organization of the image data in the file: PlanarCon‐
77 figuration=1 (packed samples), and PlanarConfiguration=2 (separated
78 samples). Note that this mechanism can be used to transform the data
79 before storing it in the raster. For example one can convert data to
80 colormap indices for display on a colormap display.
81
83 It is simple to display an image as it is being read into memory by
84 overriding the put methods as described above for supporting alternate
85 raster formats. Simply keep a reference to the default put methods
86 setup by TIFFRGBAImageBegin and then invoke them before or after each
87 display operation. For example, the tiffgt(1) utility uses the follow‐
88 ing put method to update the display as the raster is being filled:
89 static void
91 putContigAndDraw(TIFFRGBAImage* img, uint32* raster,
92 uint32 x, uint32 y, uint32 w, uint32 h,
93 int32 fromskew, int32 toskew,
94 unsigned char* cp)
95 {
96 (*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp);
97 if (x+w == width) {
98 w = width;
99 if (img->orientation == ORIENTATION_TOPLEFT)
100 lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w);
101 else
102 lrectwrite(0, y, w-1, y+h-1, raster);
103 }
104 }
105 (the original routine provided by the library is saved in the variable
107 putContig.)
108
110 The TIFFRGBAImage routines support the most commonly encountered fla‐
111 vors of TIFF. It is possible to extend this support by overriding the
112 ``get method'' invoked by TIFFRGBAImageGet to read TIFF image data.
113 Details of doing this are a bit involved, it is best to make a copy of
114 an existing get method and modify it to suit the needs of an applica‐
115 tion.
116
118 Samples must be either 1, 2, 4, 8, or 16 bits. Colorimetric sam‐
119 ples/pixel must be either 1, 3, or 4 (i.e. SamplesPerPixel minus
120 ExtraSamples).
121 Palette image colormaps that appear to be incorrectly written as 8-bit
123 values are automatically scaled to 16-bits.
124
126 All routines return 1 if the operation was successful. Otherwise, 0 is
127 returned if an error was encountered and stopOnError is zero.
128
130 All error messages are directed to the TIFFError(3TIFF) routine.
131 Sorry, can not handle %d-bit pictures. The image had BitsPerSample
133 other than 1, 2, 4, 8, or 16.
134 Sorry, can not handle %d-channel images. The image had SamplesPerPixel
136 other than 1, 3, or 4.
137 Missing needed "PhotometricInterpretation" tag. The image did not have
139 a tag that describes how to display the data.
140 No "PhotometricInterpretation" tag, assuming RGB. The image was miss‐
142 ing a tag that describes how to display it, but because it has 3 or 4
143 samples/pixel, it is assumed to be RGB.
144 No "PhotometricInterpretation" tag, assuming min-is-black. The image
146 was missing a tag that describes how to display it, but because it has
147 1 sample/pixel, it is assumed to be a grayscale or bilevel image.
148 No space for photometric conversion table. There was insufficient mem‐
150 ory for a table used to convert image samples to 8-bit RGB.
151 Missing required "Colormap" tag. A Palette image did not have a
153 required Colormap tag.
154 No space for tile buffer. There was insufficient memory to allocate an
156 i/o buffer.
157 No space for strip buffer. There was insufficient memory to allocate
159 an i/o buffer.
160 Can not handle format. The image has a format (combination of BitsPer‐
162 Sample, SamplesPerPixel, and PhotometricInterpretation) that can not be
163 handled.
164 No space for B&W mapping table. There was insufficient memory to allo‐
166 cate a table used to map grayscale data to RGB.
167 No space for Palette mapping table. There was insufficient memory to
169 allocate a table used to map data to 8-bit RGB.
170
172 TIFFOpen(3TIFF), TIFFReadRGBAImage(3TIFF), TIFFReadRGBAImageOri‐
173 ented(3TIFF), TIFFReadRGBAStrip(3TIFF), TIFFReadRGBATile(3TIFF),
174 libtiff(3TIFF)
175 Libtiff library home page: http://www.simplesystems.org/libtiff/
177libtiff October 29, 2004 TIFFRGBAImage(3TIFF)