1<!-- Creator : groff version 1.19.2 --> 2<!-- CreationDate: Mon Jan 2 17:41:44 2006 --> 3<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 4"http://www.w3.org/TR/html4/loose.dtd"> 5<html> 6<head> 7<meta name="generator" content="groff -Thtml, see www.gnu.org"> 8<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 9<meta name="Content-Style" content="text/css"> 10<style type="text/css"> 11 p { margin-top: 0; margin-bottom: 0; } 12 pre { margin-top: 0; margin-bottom: 0; } 13 table { margin-top: 0; margin-bottom: 0; } 14</style> 15<title>TIFFRGBAImage</title> 16 17</head> 18<body> 19 20<h1 align=center>TIFFRGBAImage</h1> 21 22<a href="#NAME">NAME</a><br> 23<a href="#SYNOPSIS">SYNOPSIS</a><br> 24<a href="#DESCRIPTION">DESCRIPTION</a><br> 25<a href="#ALTERNATE RASTER FORMATS">ALTERNATE RASTER FORMATS</a><br> 26<a href="#SIMULTANEOUS RASTER STORE AND DISPLAY">SIMULTANEOUS RASTER STORE AND DISPLAY</a><br> 27<a href="#SUPPORTING ADDITIONAL TIFF FORMATS">SUPPORTING ADDITIONAL TIFF FORMATS</a><br> 28<a href="#NOTES">NOTES</a><br> 29<a href="#RETURN VALUES">RETURN VALUES</a><br> 30<a href="#DIAGNOSTICS">DIAGNOSTICS</a><br> 31<a href="#SEE ALSO">SEE ALSO</a><br> 32 33<hr> 34 35 36<a name="NAME"></a> 37<h2>NAME</h2> 38 39 40 41<p style="margin-left:11%; margin-top: 1em">TIFFRGBAImageOK, 42TIFFRGBAImageBegin, TIFFRGBAImageGet, TIFFRGBAImageEnd 43− read and decode an image into a raster</p> 44 45<a name="SYNOPSIS"></a> 46<h2>SYNOPSIS</h2> 47 48 49<p style="margin-left:11%; margin-top: 1em"><b>#include 50<tiffio.h></b></p> 51 52<p style="margin-left:11%; margin-top: 1em"><b>typedef 53unsigned char TIFFRGBValue; typedef struct _TIFFRGBAImage 54TIFFRGBAImage;</b></p> 55 56<p style="margin-left:11%; margin-top: 1em"><b>int 57TIFFRGBAImageOK(TIFF *</b><i>tif</i><b>, char</b> 58<i>emsg[1024]</i><b>) <br> 59int TIFFRGBAImageBegin(TIFFRGBAImage *</b><i>img</i><b>, 60TIFF*</b> <i>tif</i><b>, int</b> <i>stopOnError</i><b>, 61char</b> <i>emsg[1024]</i><b>) <br> 62int TIFFRGBAImageGet(TIFFRGBAImage *</b><i>img</i><b>, 63uint32*</b> <i>raster</i><b>, uint32</b> <i>width</i> <b>, 64uint32</b> <i>height</i><b>) <br> 65void TIFFRGBAImageEnd(TIFFRGBAImage 66*</b><i>img</i><b>)</b></p> 67 68<a name="DESCRIPTION"></a> 69<h2>DESCRIPTION</h2> 70 71 72<p style="margin-left:11%; margin-top: 1em">The routines 73described here provide a high-level interface through which 74<small>TIFF</small> images may be read into memory. Images 75may be strip- or tile-based and have a variety of different 76characteristics: bits/sample, samples/pixel, photometric, 77etc. Decoding state is encapsulated in a 78<i>TIFFRGBAImage</i> structure making it possible to capture 79state for multiple images and quickly switch between them. 80The target raster format can be customized to a particular 81application’s needs by installing custom routines that 82manipulate image data according to application 83requirements.</p> 84 85<p style="margin-left:11%; margin-top: 1em">The default 86usage for these routines is: check if an image can be 87processed using <i>TIFFRGBAImageOK</i>, construct a decoder 88state block using <i>TIFFRGBAImageBegin</i>, read and decode 89an image into a target raster using <i>TIFFRGBAImageGet</i>, 90and then release resources using <i>TIFFRGBAImageEnd</i>. 91<i>TIFFRGBAImageGet</i> can be called multiple times to 92decode an image using different state parameters. If 93multiple images are to be displayed and there is not enough 94space for each of the decoded rasters, multiple state blocks 95can be managed and then calls can be made to 96<i>TIFFRGBAImageGet</i> as needed to display an image.</p> 97 98<p style="margin-left:11%; margin-top: 1em">The generated 99raster is assumed to be an array of <i>width</i> times 100<i>height</i> 32-bit entries, where <i>width</i> must be 101less than or equal to the width of the image (<i>height</i> 102may be any non-zero size). If the raster dimensions are 103smaller than the image, the image data is cropped to the 104raster bounds. If the raster height is greater than that of 105the image, then the image data are placed in the lower part 106of the raster. (Note that the raster is assume to be 107organized such that the pixel at location 108(<i>x</i>,<i>y</i>) is 109<i>raster</i>[<i>y</i>*<i>width</i>+<i>x</i>]; with the 110raster origin in the <b>lower-left</b> hand corner.)</p> 111 112<p style="margin-left:11%; margin-top: 1em">Raster pixels 113are 8-bit packed red, green, blue, alpha samples. The macros 114<i>TIFFGetR</i>, <i>TIFFGetG</i>, <i>TIFFGetB</i>, and 115<i>TIFFGetA</i> should be used to access individual samples. 116Images without Associated Alpha matting information have a 117constant Alpha of 1.0 (255).</p> 118 119 120<p style="margin-left:11%; margin-top: 1em"><i>TIFFRGBAImageGet</i> 121converts non-8-bit images by scaling sample values. Palette, 122grayscale, bilevel, <small>CMYK</small> , and YCbCr images 123are converted to <small>RGB</small> transparently. Raster 124pixels are returned uncorrected by any colorimetry 125information present in the directory.</p> 126 127<p style="margin-left:11%; margin-top: 1em">The parameter 128<i>stopOnError</i> specifies how to act if an error is 129encountered while reading the image. If <i>stopOnError</i> 130is non-zero, then an error will terminate the operation; 131otherwise <i>TIFFRGBAImageGet</i> will continue processing 132data until all the possible data in the image have been 133requested.</p> 134 135<a name="ALTERNATE RASTER FORMATS"></a> 136<h2>ALTERNATE RASTER FORMATS</h2> 137 138 139<p style="margin-left:11%; margin-top: 1em">To use the core 140support for reading and processing <small>TIFF</small> 141images, but write the resulting raster data in a different 142format one need only override the ‘‘<i>put 143methods</i>’’ used to store raster data. These 144methods are are defined in the <i>TIFFRGBAImage</i> 145structure and initially setup by <i>TIFFRGBAImageBegin</i> 146to point to routines that pack raster data in the default 147<small>ABGR</small> pixel format. Two different routines are 148used according to the physical organization of the image 149data in the file: <i>PlanarConfiguration</i>=1 (packed 150samples), and <i>PlanarConfiguration</i>=2 (separated 151samples). Note that this mechanism can be used to transform 152the data before storing it in the raster. For example one 153can convert data to colormap indices for display on a 154colormap display.</p> 155 156<a name="SIMULTANEOUS RASTER STORE AND DISPLAY"></a> 157<h2>SIMULTANEOUS RASTER STORE AND DISPLAY</h2> 158 159 160<p style="margin-left:11%; margin-top: 1em">It is simple to 161display an image as it is being read into memory by 162overriding the put methods as described above for supporting 163alternate raster formats. Simply keep a reference to the 164default put methods setup by <i>TIFFRGBAImageBegin</i> and 165then invoke them before or after each display operation. For 166example, the <i>tiffgt</i>(1) utility uses the following put 167method to update the display as the raster is being 168filled:</p> 169 170<pre style="margin-left:11%; margin-top: 1em">static void 171putContigAndDraw(TIFFRGBAImage* img, uint32* raster, 172 uint32 x, uint32 y, uint32 w, uint32 h, 173 int32 fromskew, int32 toskew, 174 unsigned char* cp) 175{ 176 (*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp); 177 if (x+w == width) { 178 w = width; 179 if (img->orientation == ORIENTATION_TOPLEFT) 180 lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w); 181 else 182 lrectwrite(0, y, w-1, y+h-1, raster); 183 } 184}</pre> 185 186 187<p style="margin-left:11%; margin-top: 1em">(the original 188routine provided by the library is saved in the variable 189<i>putContig</i>.)</p> 190 191<a name="SUPPORTING ADDITIONAL TIFF FORMATS"></a> 192<h2>SUPPORTING ADDITIONAL TIFF FORMATS</h2> 193 194 195<p style="margin-left:11%; margin-top: 1em">The 196<i>TIFFRGBAImage</i> routines support the most commonly 197encountered flavors of <small>TIFF.</small> It is possible 198to extend this support by overriding the 199‘‘<i>get method</i>’’ invoked by 200<i>TIFFRGBAImageGet</i> to read <small>TIFF</small> image 201data. Details of doing this are a bit involved, it is best 202to make a copy of an existing get method and modify it to 203suit the needs of an application.</p> 204 205<a name="NOTES"></a> 206<h2>NOTES</h2> 207 208 209<p style="margin-left:11%; margin-top: 1em">Samples must be 210either 1, 2, 4, 8, or 16 bits. Colorimetric samples/pixel 211must be either 1, 3, or 4 (i.e. <i>SamplesPerPixel</i> minus 212<i>ExtraSamples</i>).</p> 213 214<p style="margin-left:11%; margin-top: 1em">Palette image 215colormaps that appear to be incorrectly written as 8-bit 216values are automatically scaled to 16-bits.</p> 217 218<a name="RETURN VALUES"></a> 219<h2>RETURN VALUES</h2> 220 221 222<p style="margin-left:11%; margin-top: 1em">All routines 223return 1 if the operation was successful. Otherwise, 0 is 224returned if an error was encountered and <i>stopOnError</i> 225is zero.</p> 226 227<a name="DIAGNOSTICS"></a> 228<h2>DIAGNOSTICS</h2> 229 230 231<p style="margin-left:11%; margin-top: 1em">All error 232messages are directed to the <i>TIFFError</i>(3TIFF) 233routine.</p> 234 235<p style="margin-left:11%; margin-top: 1em"><b>Sorry, can 236not handle %d-bit pictures</b>. The image had 237<i>BitsPerSample</i> other than 1, 2, 4, 8, or 16.</p> 238 239<p style="margin-left:11%; margin-top: 1em"><b>Sorry, can 240not handle %d-channel images</b>. The image had 241<i>SamplesPerPixel</i> other than 1, 3, or 4.</p> 242 243<p style="margin-left:11%; margin-top: 1em"><b>Missing 244needed "PhotometricInterpretation" tag</b>. The 245image did not have a tag that describes how to display the 246data.</p> 247 248<p style="margin-left:11%; margin-top: 1em"><b>No 249"PhotometricInterpretation" tag, assuming RGB</b>. 250The image was missing a tag that describes how to display 251it, but because it has 3 or 4 samples/pixel, it is assumed 252to be <small>RGB.</small></p> 253 254<p style="margin-left:11%; margin-top: 1em"><b>No 255"PhotometricInterpretation" tag, assuming 256min-is-black</b>. The image was missing a tag that describes 257how to display it, but because it has 1 sample/pixel, it is 258assumed to be a grayscale or bilevel image.</p> 259 260<p style="margin-left:11%; margin-top: 1em"><b>No space for 261photometric conversion table</b>. There was insufficient 262memory for a table used to convert image samples to 8-bit 263<small>RGB.</small></p> 264 265<p style="margin-left:11%; margin-top: 1em"><b>Missing 266required "Colormap" tag</b>. A Palette image did 267not have a required <i>Colormap</i> tag.</p> 268 269<p style="margin-left:11%; margin-top: 1em"><b>No space for 270tile buffer</b>. There was insufficient memory to allocate 271an i/o buffer.</p> 272 273<p style="margin-left:11%; margin-top: 1em"><b>No space for 274strip buffer</b>. There was insufficient memory to allocate 275an i/o buffer.</p> 276 277<p style="margin-left:11%; margin-top: 1em"><b>Can not 278handle format</b>. The image has a format (combination of 279<i>BitsPerSample</i>, <i>SamplesPerPixel</i>, and 280<i>PhotometricInterpretation</i>) that can not be 281handled.</p> 282 283<p style="margin-left:11%; margin-top: 1em"><b>No space for 284B&W mapping table</b>. There was insufficient memory to 285allocate a table used to map grayscale data to 286<small>RGB.</small></p> 287 288<p style="margin-left:11%; margin-top: 1em"><b>No space for 289Palette mapping table</b>. There was insufficient memory to 290allocate a table used to map data to 8-bit 291<small>RGB.</small></p> 292 293<a name="SEE ALSO"></a> 294<h2>SEE ALSO</h2> 295 296 297 298<p style="margin-left:11%; margin-top: 1em"><b>TIFFOpen</b>(3TIFF), 299<b>TIFFReadRGBAImage</b>(3TIFF), 300<b>TIFFReadRGBAImageOriented</b>(3TIFF), 301<b>TIFFReadRGBAStrip</b>(3TIFF), 302<b>TIFFReadRGBATile</b>(3TIFF), <b>libtiff</b>(3TIFF)</p> 303 304<p style="margin-left:11%; margin-top: 1em">Libtiff library 305home page: <b>http://www.remotesensing.org/libtiff/</b></p> 306<hr> 307</body> 308</html> 309