1*25cbff28SJoris Van Damme<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2*25cbff28SJoris Van Damme<html lang="en"> 3*25cbff28SJoris Van Damme<head> 4*25cbff28SJoris Van Damme <title>Using The TIFF Library</title> 5*25cbff28SJoris Van Damme <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"> 6*25cbff28SJoris Van Damme <meta http-equiv="content-language" content="en"> 7*25cbff28SJoris Van Damme <style type="text/css"> 8*25cbff28SJoris Van Damme <!-- 9*25cbff28SJoris Van Damme th {text-align: left; vertical-align: top; font-style: italic; font-weight: normal} 10*25cbff28SJoris Van Damme --> 11*25cbff28SJoris Van Damme </style> 12*25cbff28SJoris Van Damme</head> 13*25cbff28SJoris Van Damme<body lang="en" text="#000000" bgcolor="#ffffff" link="#0000ff" alink="#0000ff" vlink="#0000ff"> 14*25cbff28SJoris Van Damme <table border="0" cellspacing="0" cellpadding="0"> 15*25cbff28SJoris Van Damme <tr> 16*25cbff28SJoris Van Damme <td style="padding-left: 1em; padding-right: 1em"><img src="images/cat.gif" width="113" height="146"></td> 17*25cbff28SJoris Van Damme <td> 18*25cbff28SJoris Van Damme <h1>Using The TIFF Library</h1> 19*25cbff28SJoris Van Damme <p> 20*25cbff28SJoris Van Damme <tt>libtiff</tt> is a set of C functions (a library) that support 210ef31e1fSMike Welles the manipulation of TIFF image files. 220ef31e1fSMike Welles The library requires an ANSI C compilation environment for building 230ef31e1fSMike Welles and presumes an ANSI C environment for use. 24*25cbff28SJoris Van Damme </p> 25*25cbff28SJoris Van Damme </td> 26*25cbff28SJoris Van Damme </tr> 27*25cbff28SJoris Van Damme </table> 28*25cbff28SJoris Van Damme <br> 29*25cbff28SJoris Van Damme <p> 30*25cbff28SJoris Van Damme <tt>libtiff</tt> 310ef31e1fSMike Welles provides interfaces to image data at several layers of abstraction (and cost). 320ef31e1fSMike Welles At the highest level image data can be read into an 8-bit/sample, 330ef31e1fSMike Welles ABGR pixel raster format without regard for the underlying data organization, 340ef31e1fSMike Welles colorspace, or compression scheme. Below this high-level interface 350ef31e1fSMike Welles the library provides scanline-, strip-, and tile-oriented interfaces that 360ef31e1fSMike Welles return data decompressed but otherwise untransformed. These interfaces 370ef31e1fSMike Welles require that the application first identify the organization of stored 380ef31e1fSMike Welles data and select either a strip-based or tile-based API for manipulating 390ef31e1fSMike Welles data. At the lowest level the library 400ef31e1fSMike Welles provides access to the raw uncompressed strips or tiles, 410ef31e1fSMike Welles returning the data exactly as it appears in the file. 42*25cbff28SJoris Van Damme </p> 43*25cbff28SJoris Van Damme <p> 440ef31e1fSMike Welles The material presented in this chapter is a basic introduction 450ef31e1fSMike Welles to the capabilities of the library; it is not an attempt to describe 460ef31e1fSMike Welles everything a developer needs to know about the library or about TIFF. 470ef31e1fSMike Welles Detailed information on the interfaces to the library are given in 48*25cbff28SJoris Van Damme the <a href="http://www.remotesensing.org/libtiff/man/index.html">UNIX 49*25cbff28SJoris Van Damme manual pages</a> that accompany this software. 50*25cbff28SJoris Van Damme </p> 51*25cbff28SJoris Van Damme <p> 52*25cbff28SJoris Van Damme Michael Still has also written a useful introduction to libtiff for the 53c7486651SFrank Warmerdam IBM DeveloperWorks site available at 54*25cbff28SJoris Van Damme <a href="http://www.ibm.com/developerworks/linux/library/l-libtiff">http://www.ibm.com/developerworks/linux/library/l-libtiff</a>. 55*25cbff28SJoris Van Damme </p> 56*25cbff28SJoris Van Damme <p> 570ef31e1fSMike Welles The following sections are found in this chapter: 58*25cbff28SJoris Van Damme </p> 59*25cbff28SJoris Van Damme <ul> 60*25cbff28SJoris Van Damme <li><a href="#version">How to tell which version you have</a></li> 61*25cbff28SJoris Van Damme <li><a href="#typedefs">Library Datatypes</a></li> 62*25cbff28SJoris Van Damme <li><a href="#mman">Memory Management</a></li> 63*25cbff28SJoris Van Damme <li><a href="#errors">Error Handling</a></li> 64*25cbff28SJoris Van Damme <li><a href="#fio">Basic File Handling</a></li> 65*25cbff28SJoris Van Damme <li><a href="#dirs">TIFF Directories</a></li> 66*25cbff28SJoris Van Damme <li><a href="#tags">TIFF Tags</a></li> 67*25cbff28SJoris Van Damme <li><a href="#compression">TIFF Compression Schemes</a></li> 68*25cbff28SJoris Van Damme <li><a href="#byteorder">Byte Order</a></li> 69*25cbff28SJoris Van Damme <li><a href="#dataplacement">Data Placement</a></li> 70*25cbff28SJoris Van Damme <li><a href="#tiffrgbaimage">TIFFRGBAImage Support</a></li> 71*25cbff28SJoris Van Damme <li><a href="#scanlines">Scanline-based Image I/O</a></li> 72*25cbff28SJoris Van Damme <li><a href="#strips">Strip-oriented Image I/O</a></li> 73*25cbff28SJoris Van Damme <li><a href="#tiles">Tile-oriented Image I/O</a></li> 74*25cbff28SJoris Van Damme <li><a href="#other">Other Stuff</a></li> 75*25cbff28SJoris Van Damme </ul> 76*25cbff28SJoris Van Damme <hr> 77*25cbff28SJoris Van Damme <h2 id="version">How to tell which version you have</h2> 78*25cbff28SJoris Van Damme <p> 790ef31e1fSMike Welles The software version can be found by looking at the file named 80*25cbff28SJoris Van Damme <tt>VERSION</tt> 810ef31e1fSMike Welles that is located at the top of the source tree; the precise alpha number 82*25cbff28SJoris Van Damme is given in the file <tt>dist/tiff.alpha</tt>. 830ef31e1fSMike Welles If you have need to refer to this 840ef31e1fSMike Welles specific software, you should identify it as: 85*25cbff28SJoris Van Damme </p> 86*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 87*25cbff28SJoris Van Damme <tt>TIFF <<i>version</i>> <<i>alpha</i>></tt> 88*25cbff28SJoris Van Damme </p> 89*25cbff28SJoris Van Damme <p> 90*25cbff28SJoris Van Damme where <tt><<i>version</i>></tt> is whatever you get from 91*25cbff28SJoris Van Damme <tt>"cat VERSION"</tt> and <tt><<i>alpha</i>></tt> is 92*25cbff28SJoris Van Damme what you get from <tt>"cat dist/tiff.alpha"</tt>. 93*25cbff28SJoris Van Damme </p> 94*25cbff28SJoris Van Damme <p> 95*25cbff28SJoris Van Damme Within an application that uses <tt>libtiff</tt> the <tt>TIFFGetVersion</tt> 960ef31e1fSMike Welles routine will return a pointer to a string that contains software version 970ef31e1fSMike Welles information. 98*25cbff28SJoris Van Damme The library include file <tt><tiffio.h></tt> contains a C pre-processor 99*25cbff28SJoris Van Damme define <tt>TIFFLIB_VERSION</tt> that can be used to check library 1000ef31e1fSMike Welles version compatiblity at compile time. 101*25cbff28SJoris Van Damme </p> 102*25cbff28SJoris Van Damme <hr> 103*25cbff28SJoris Van Damme <h2 id="typedefs">Library Datatypes</h2> 104*25cbff28SJoris Van Damme <p> 105*25cbff28SJoris Van Damme <tt>libtiff</tt> defines a portable programming interface through the 1060ef31e1fSMike Welles use of a set of C type definitions. 107*25cbff28SJoris Van Damme These definitions, defined in in the files <b>tiff.h</b> and 108*25cbff28SJoris Van Damme <b>tiffio.h</b>, 109*25cbff28SJoris Van Damme isolate the <tt>libtiff</tt> API from the characteristics 1100ef31e1fSMike Welles of the underlying machine. 1110ef31e1fSMike Welles To insure portable code and correct operation, applications that use 112*25cbff28SJoris Van Damme <tt>libtiff</tt> should use the typedefs and follow the function 1130ef31e1fSMike Welles prototypes for the library API. 114*25cbff28SJoris Van Damme </p> 115*25cbff28SJoris Van Damme <hr> 116*25cbff28SJoris Van Damme <h2 id="mman">Memory Management</h2> 117*25cbff28SJoris Van Damme <p> 118*25cbff28SJoris Van Damme <tt>libtiff</tt> uses a machine-specific set of routines for managing 1190ef31e1fSMike Welles dynamically allocated memory. 120*25cbff28SJoris Van Damme <tt>_TIFFmalloc</tt>, <tt>_TIFFrealloc</tt>, and <tt>_TIFFfree</tt> 1210ef31e1fSMike Welles mimic the normal ANSI C routines. 1220ef31e1fSMike Welles Any dynamically allocated memory that is to be passed into the library 1230ef31e1fSMike Welles should be allocated using these interfaces in order to insure pointer 1240ef31e1fSMike Welles compatibility on machines with a segmented architecture. 125*25cbff28SJoris Van Damme (On 32-bit UNIX systems these routines just call the normal <tt>malloc</tt>, 126*25cbff28SJoris Van Damme <tt>realloc</tt>, and <tt>free</tt> routines in the C library.) 127*25cbff28SJoris Van Damme </p> 128*25cbff28SJoris Van Damme <p> 129*25cbff28SJoris Van Damme To deal with segmented pointer issues <tt>libtiff</tt> also provides 130*25cbff28SJoris Van Damme <tt>_TIFFmemcpy</tt>, <tt>_TIFFmemset</tt>, and <tt>_TIFFmemmove</tt> 1310ef31e1fSMike Welles routines that mimic the equivalent ANSI C routines, but that are 132*25cbff28SJoris Van Damme intended for use with memory allocated through <tt>_TIFFmalloc</tt> 133*25cbff28SJoris Van Damme and <tt>_TIFFrealloc</tt>. 134*25cbff28SJoris Van Damme </p> 135*25cbff28SJoris Van Damme <hr> 136*25cbff28SJoris Van Damme <h2 id="errors">Error Handling</h2> 137*25cbff28SJoris Van Damme <p> 138*25cbff28SJoris Van Damme <tt>libtiff</tt> handles most errors by returning an invalid/erroneous 1390ef31e1fSMike Welles value when returning from a function call. 1400ef31e1fSMike Welles Various diagnostic messages may also be generated by the library. 1410ef31e1fSMike Welles All error messages are directed to a single global error handler 142*25cbff28SJoris Van Damme routine that can be specified with a call to <tt>TIFFSetErrorHandler</tt>. 1430ef31e1fSMike Welles Likewise warning messages are directed to a single handler routine 144*25cbff28SJoris Van Damme that can be specified with a call to <tt>TIFFSetWarningHandler</tt> 145*25cbff28SJoris Van Damme </p> 146*25cbff28SJoris Van Damme <hr> 147*25cbff28SJoris Van Damme <h2 id="fio">Basic File Handling</h2> 148*25cbff28SJoris Van Damme <p> 1490ef31e1fSMike Welles The library is modeled after the normal UNIX stdio library. 1500ef31e1fSMike Welles For example, to read from an existing TIFF image the 1510ef31e1fSMike Welles file must first be opened: 152*25cbff28SJoris Van Damme </p> 153*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 154*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 155*25cbff28SJoris Van Damme main()<br> 156*25cbff28SJoris Van Damme {<br> 157*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("foo.tif", "r");<br> 158*25cbff28SJoris Van Damme ... do stuff ...<br> 159*25cbff28SJoris Van Damme TIFFClose(tif);<br> 160*25cbff28SJoris Van Damme }</tt> 161*25cbff28SJoris Van Damme </p> 162*25cbff28SJoris Van Damme <p> 163*25cbff28SJoris Van Damme The handle returned by <tt>TIFFOpen</tt> is <i>opaque</i>, that is 1640ef31e1fSMike Welles the application is not permitted to know about its contents. 1650ef31e1fSMike Welles All subsequent library calls for this file must pass the handle 1660ef31e1fSMike Welles as an argument. 167*25cbff28SJoris Van Damme </p> 168*25cbff28SJoris Van Damme <p> 1690ef31e1fSMike Welles To create or overwrite a TIFF image the file is also opened, but with 170*25cbff28SJoris Van Damme a <tt>"w"</tt> argument: 171*25cbff28SJoris Van Damme <p> 172*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 173*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 174*25cbff28SJoris Van Damme main()<br> 175*25cbff28SJoris Van Damme {<br> 176*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("foo.tif", "w");<br> 177*25cbff28SJoris Van Damme ... do stuff ...<br> 178*25cbff28SJoris Van Damme TIFFClose(tif);<br> 179*25cbff28SJoris Van Damme }</tt> 180*25cbff28SJoris Van Damme </p> 181*25cbff28SJoris Van Damme <p> 1820ef31e1fSMike Welles If the file already exists it is first truncated to zero length. 183*25cbff28SJoris Van Damme </p> 184*25cbff28SJoris Van Damme <table> 185*25cbff28SJoris Van Damme <tr> 186*25cbff28SJoris Van Damme <td valign=top><img src="images/warning.gif" width="40" height="40"></td> 187*25cbff28SJoris Van Damme <td><i>Note that unlike the stdio library TIFF image files may not be 1880ef31e1fSMike Welles opened for both reading and writing; 189*25cbff28SJoris Van Damme there is no support for altering the contents of a TIFF file.</i></td> 190*25cbff28SJoris Van Damme </tr> 191*25cbff28SJoris Van Damme </table> 192*25cbff28SJoris Van Damme <p> 193*25cbff28SJoris Van Damme <tt>libtiff</tt> buffers much information associated with writing a 1940ef31e1fSMike Welles valid TIFF image. Consequently, when writing a TIFF image it is necessary 195*25cbff28SJoris Van Damme to always call <tt>TIFFClose</tt> or <tt>TIFFFlush</tt> to flush any 196*25cbff28SJoris Van Damme buffered information to a file. Note that if you call <tt>TIFFClose</tt> 197*25cbff28SJoris Van Damme you do not need to call <tt>TIFFFlush</tt>. 198*25cbff28SJoris Van Damme </p> 199*25cbff28SJoris Van Damme <hr> 200*25cbff28SJoris Van Damme <h2 id="dirs">TIFF Directories</h2> 201*25cbff28SJoris Van Damme <p> 2020ef31e1fSMike Welles TIFF supports the storage of multiple images in a single file. 203*25cbff28SJoris Van Damme Each image has an associated data structure termed a <i>directory</i> 2040ef31e1fSMike Welles that houses all the information about the format and content of the 2050ef31e1fSMike Welles image data. 2060ef31e1fSMike Welles Images in a file are usually related but they do not need to be; it 2070ef31e1fSMike Welles is perfectly alright to store a color image together with a black and 2080ef31e1fSMike Welles white image. 2090ef31e1fSMike Welles Note however that while images may be related their directories are 2100ef31e1fSMike Welles not. 2110ef31e1fSMike Welles That is, each directory stands on its own; their is no need to read 2120ef31e1fSMike Welles an unrelated directory in order to properly interpret the contents 2130ef31e1fSMike Welles of an image. 214*25cbff28SJoris Van Damme </p> 215*25cbff28SJoris Van Damme <p> 216*25cbff28SJoris Van Damme <tt>libtiff</tt> provides several routines for reading and writing 2170ef31e1fSMike Welles directories. In normal use there is no need to explicitly 2180ef31e1fSMike Welles read or write a directory: the library automatically reads the first 2190ef31e1fSMike Welles directory in a file when opened for reading, and directory information 2200ef31e1fSMike Welles to be written is automatically accumulated and written when writing 221*25cbff28SJoris Van Damme (assuming <tt>TIFFClose</tt> or <tt>TIFFFlush</tt> are called). 222*25cbff28SJoris Van Damme </p> 223*25cbff28SJoris Van Damme <p> 224*25cbff28SJoris Van Damme For a file open for reading the <tt>TIFFSetDirectory</tt> routine can 2250ef31e1fSMike Welles be used to select an arbitrary directory; directories are referenced by 2260ef31e1fSMike Welles number with the numbering starting at 0. Otherwise the 227*25cbff28SJoris Van Damme <tt>TIFFReadDirectory</tt> and <tt>TIFFWriteDirectory</tt> routines can 2280ef31e1fSMike Welles be used for sequential access to directories. 2290ef31e1fSMike Welles For example, to count the number of directories in a file the following 2300ef31e1fSMike Welles code might be used: 231*25cbff28SJoris Van Damme </p> 232*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 233*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 234*25cbff28SJoris Van Damme main(int argc, char* argv[])<br> 235*25cbff28SJoris Van Damme {<br> 236*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen(argv[1], "r");<br> 237*25cbff28SJoris Van Damme if (tif) {<br> 238*25cbff28SJoris Van Damme int dircount = 0;<br> 239*25cbff28SJoris Van Damme do {<br> 240*25cbff28SJoris Van Damme dircount++;<br> 241*25cbff28SJoris Van Damme } while (TIFFReadDirectory(tif));<br> 242*25cbff28SJoris Van Damme printf("%d directories in %s\n", dircount, argv[1]);<br> 243*25cbff28SJoris Van Damme TIFFClose(tif);<br> 244*25cbff28SJoris Van Damme }<br> 245*25cbff28SJoris Van Damme exit(0);<br> 246*25cbff28SJoris Van Damme }</tt> 247*25cbff28SJoris Van Damme </p> 248*25cbff28SJoris Van Damme <p> 2490ef31e1fSMike Welles Finally, note that there are several routines for querying the 2500ef31e1fSMike Welles directory status of an open file: 251*25cbff28SJoris Van Damme <tt>TIFFCurrentDirectory</tt> returns the index of the current 2520ef31e1fSMike Welles directory and 253*25cbff28SJoris Van Damme <tt>TIFFLastDirectory</tt> returns an indication of whether the 2540ef31e1fSMike Welles current directory is the last directory in a file. 255*25cbff28SJoris Van Damme There is also a routine, <tt>TIFFPrintDirectory</tt>, that can 2560ef31e1fSMike Welles be called to print a formatted description of the contents of 2570ef31e1fSMike Welles the current directory; consult the manual page for complete details. 258*25cbff28SJoris Van Damme </p> 259*25cbff28SJoris Van Damme <hr> 260*25cbff28SJoris Van Damme <h2 id="tags">TIFF Tags</h2> 261*25cbff28SJoris Van Damme <p> 2620ef31e1fSMike Welles Image-related information such as the image width and height, number 2630ef31e1fSMike Welles of samples, orientation, colorimetric information, etc. 2640ef31e1fSMike Welles are stored in each image 265*25cbff28SJoris Van Damme directory in <i>fields</i> or <i>tags</i>. 2660ef31e1fSMike Welles Tags are identified by a number that is usually a value registered 2670ef31e1fSMike Welles with the Aldus (now Adobe) Corporation. 2680ef31e1fSMike Welles Beware however that some vendors write 2690ef31e1fSMike Welles TIFF images with tags that are unregistered; in this case interpreting 2700ef31e1fSMike Welles their contents is usually a waste of time. 271*25cbff28SJoris Van Damme </p> 272*25cbff28SJoris Van Damme <p> 273*25cbff28SJoris Van Damme <tt>libtiff</tt> reads the contents of a directory all at once 2740ef31e1fSMike Welles and converts the on-disk information to an appropriate in-memory 2750ef31e1fSMike Welles form. While the TIFF specification permits an arbitrary set of 2760ef31e1fSMike Welles tags to be defined and used in a file, the library only understands 2770ef31e1fSMike Welles a limited set of tags. 2780ef31e1fSMike Welles Any unknown tags that are encountered in a file are ignored. 2790ef31e1fSMike Welles There is a mechanism to extend the set of tags the library handles 2800ef31e1fSMike Welles without modifying the library itself; 281*25cbff28SJoris Van Damme this is described <a href="addingtags.html">elsewhere</a>. 282*25cbff28SJoris Van Damme </p> 283*25cbff28SJoris Van Damme <p> 284*25cbff28SJoris Van Damme <tt>libtiff</tt> provides two interfaces for getting and setting tag 285*25cbff28SJoris Van Damme values: <tt>TIFFGetField</tt> and <tt>TIFFSetField</tt>. 2860ef31e1fSMike Welles These routines use a variable argument list-style interface to pass 2870ef31e1fSMike Welles parameters of different type through a single function interface. 288*25cbff28SJoris Van Damme The <i>get interface</i> takes one or more pointers to memory locations 2890ef31e1fSMike Welles where the tag values are to be returned and also returns one or 2900ef31e1fSMike Welles zero according to whether the requested tag is defined in the directory. 291*25cbff28SJoris Van Damme The <i>set interface</i> takes the tag values either by-reference or 2920ef31e1fSMike Welles by-value. 2930ef31e1fSMike Welles The TIFF specification defines 294*25cbff28SJoris Van Damme <i>default values</i> for some tags. 2950ef31e1fSMike Welles To get the value of a tag, or its default value if it is undefined, 296*25cbff28SJoris Van Damme the <tt>TIFFGetFieldDefaulted</tt> interface may be used. 297*25cbff28SJoris Van Damme </p> 298*25cbff28SJoris Van Damme <p> 2990ef31e1fSMike Welles The manual pages for the tag get and set routines specifiy the exact data types 3000ef31e1fSMike Welles and calling conventions required for each tag supported by the library. 301*25cbff28SJoris Van Damme </p> 302*25cbff28SJoris Van Damme <hr> 303*25cbff28SJoris Van Damme <h2 id="compression">TIFF Compression Schemes</h2> 304*25cbff28SJoris Van Damme <p> 305*25cbff28SJoris Van Damme <tt>libtiff</tt> includes support for a wide variety of 3060ef31e1fSMike Welles data compression schemes. 3070ef31e1fSMike Welles In normal operation a compression scheme is automatically used when 308*25cbff28SJoris Van Damme the TIFF <tt>Compression</tt> tag is set, either by opening a file 3090ef31e1fSMike Welles for reading, or by setting the tag when writing. 310*25cbff28SJoris Van Damme </p> 311*25cbff28SJoris Van Damme <p> 312*25cbff28SJoris Van Damme Compression schemes are implemented by software modules termed <i>codecs</i> 3130ef31e1fSMike Welles that implement decoder and encoder routines that hook into the 3140ef31e1fSMike Welles core library i/o support. 3150ef31e1fSMike Welles Codecs other than those bundled with the library can be registered 316*25cbff28SJoris Van Damme for use with the <tt>TIFFRegisterCODEC</tt> routine. 3170ef31e1fSMike Welles This interface can also be used to override the core-library 3180ef31e1fSMike Welles implementation for a compression scheme. 319*25cbff28SJoris Van Damme </p> 320*25cbff28SJoris Van Damme <hr> 321*25cbff28SJoris Van Damme <h2 id="byteorder">Byte Order</h2> 322*25cbff28SJoris Van Damme <p> 3230ef31e1fSMike Welles The TIFF specification says, and has always said, that 324*25cbff28SJoris Van Damme <em>a correct TIFF 325*25cbff28SJoris Van Damme reader must handle images in big-endian and little-endian byte order</em>. 326*25cbff28SJoris Van Damme <tt>libtiff</tt> conforms in this respect. 3270ef31e1fSMike Welles Consequently there is no means to force a specific 3280ef31e1fSMike Welles byte order for the data written to a TIFF image file (data is 3290ef31e1fSMike Welles written in the native order of the host CPU unless appending to 3300ef31e1fSMike Welles an existing file, in which case it is written in the byte order 3310ef31e1fSMike Welles specified in the file). 332*25cbff28SJoris Van Damme </p> 333*25cbff28SJoris Van Damme <hr> 334*25cbff28SJoris Van Damme <h2 id="dataplacement">Data Placement</h2> 335*25cbff28SJoris Van Damme <p> 3360ef31e1fSMike Welles The TIFF specification requires that all information except an 3370ef31e1fSMike Welles 8-byte header can be placed anywhere in a file. 3380ef31e1fSMike Welles In particular, it is perfectly legitimate for directory information 3390ef31e1fSMike Welles to be written after the image data itself. 3400ef31e1fSMike Welles Consequently TIFF is inherently not suitable for passing through a 3410ef31e1fSMike Welles stream-oriented mechanism such as UNIX pipes. 3420ef31e1fSMike Welles Software that require that data be organized in a file in a particular 3430ef31e1fSMike Welles order (e.g. directory information before image data) does not 3440ef31e1fSMike Welles correctly support TIFF. 345*25cbff28SJoris Van Damme <tt>libtiff</tt> provides no mechanism for controlling the placement 3460ef31e1fSMike Welles of data in a file; image data is typically written before directory 3470ef31e1fSMike Welles information. 348*25cbff28SJoris Van Damme </p> 349*25cbff28SJoris Van Damme <hr> 350*25cbff28SJoris Van Damme <h2 id="tiffrgbaimage">TIFFRGBAImage Support</h2> 351*25cbff28SJoris Van Damme <p> 352*25cbff28SJoris Van Damme <tt>libtiff</tt> provides a high-level interface for reading image 3530ef31e1fSMike Welles data from a TIFF file. This interface handles the details of 3540ef31e1fSMike Welles data organization and format for a wide variety of TIFF files; 3550ef31e1fSMike Welles at least the large majority of those files that one would normally 3560ef31e1fSMike Welles encounter. Image data is, by default, returned as ABGR 3570ef31e1fSMike Welles pixels packed into 32-bit words (8 bits per sample). Rectangular 3580ef31e1fSMike Welles rasters can be read or data can be intercepted at an intermediate 3590ef31e1fSMike Welles level and packed into memory in a format more suitable to the 3600ef31e1fSMike Welles application. 3610ef31e1fSMike Welles The library handles all the details of the format of data stored on 3620ef31e1fSMike Welles disk and, in most cases, if any colorspace conversions are required: 3630ef31e1fSMike Welles bilevel to RGB, greyscale to RGB, CMYK to RGB, YCbCr to RGB, 16-bit 3640ef31e1fSMike Welles samples to 8-bit samples, associated/unassociated alpha, etc. 365*25cbff28SJoris Van Damme </p> 366*25cbff28SJoris Van Damme <p> 3670ef31e1fSMike Welles There are two ways to read image data using this interface. If 3680ef31e1fSMike Welles all the data is to be stored in memory and manipulated at once, 369*25cbff28SJoris Van Damme then the routine <tt>TIFFReadRGBAImage</tt> can be used: 370*25cbff28SJoris Van Damme </p> 371*25cbff28SJoris Van Damme <p> 372*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 373*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 374*25cbff28SJoris Van Damme main(int argc, char* argv[])<br> 375*25cbff28SJoris Van Damme {<br> 376*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen(argv[1], "r");<br> 377*25cbff28SJoris Van Damme if (tif) {<br> 378*25cbff28SJoris Van Damme uint32 w, h;<br> 379*25cbff28SJoris Van Damme size_t npixels;<br> 380*25cbff28SJoris Van Damme uint32* raster;<br> 381*25cbff28SJoris Van Damme <br> 382*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_IMAGEWIDTH, &w);<br> 383*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &h);<br> 384*25cbff28SJoris Van Damme npixels = w * h;<br> 385*25cbff28SJoris Van Damme raster = (uint32*) _TIFFmalloc(npixels * sizeof (uint32));<br> 386*25cbff28SJoris Van Damme if (raster != NULL) {<br> 387*25cbff28SJoris Van Damme if (TIFFReadRGBAImage(tif, w, h, raster, 0)) {<br> 388*25cbff28SJoris Van Damme ...process raster data...<br> 389*25cbff28SJoris Van Damme }<br> 390*25cbff28SJoris Van Damme _TIFFfree(raster);<br> 391*25cbff28SJoris Van Damme }<br> 392*25cbff28SJoris Van Damme TIFFClose(tif);<br> 393*25cbff28SJoris Van Damme }<br> 394*25cbff28SJoris Van Damme exit(0);<br> 395*25cbff28SJoris Van Damme }</tt> 396*25cbff28SJoris Van Damme </p> 397*25cbff28SJoris Van Damme <p> 398*25cbff28SJoris Van Damme Note above that <tt>_TIFFmalloc</tt> is used to allocate memory for 399*25cbff28SJoris Van Damme the raster passed to <tt>TIFFReadRGBAImage</tt>; this is important 4000ef31e1fSMike Welles to insure the ``appropriate type of memory'' is passed on machines 4010ef31e1fSMike Welles with segmented architectures. 402*25cbff28SJoris Van Damme </p> 403*25cbff28SJoris Van Damme <p> 404*25cbff28SJoris Van Damme Alternatively, <tt>TIFFReadRGBAImage</tt> can be replaced with a 4050ef31e1fSMike Welles more low-level interface that permits an application to have more 4060ef31e1fSMike Welles control over this reading procedure. The equivalent to the above 4070ef31e1fSMike Welles is: 408*25cbff28SJoris Van Damme </p> 409*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 410*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 411*25cbff28SJoris Van Damme main(int argc, char* argv[])<br> 412*25cbff28SJoris Van Damme {<br> 413*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen(argv[1], "r");<br> 414*25cbff28SJoris Van Damme if (tif) {<br> 415*25cbff28SJoris Van Damme TIFFRGBAImage img;<br> 416*25cbff28SJoris Van Damme char emsg[1024];<br> 417*25cbff28SJoris Van Damme <br> 418*25cbff28SJoris Van Damme if (TIFFRGBAImageBegin(&img, tif, 0, emsg)) {<br> 419*25cbff28SJoris Van Damme size_t npixels;<br> 420*25cbff28SJoris Van Damme uint32* raster;<br> 421*25cbff28SJoris Van Damme <br> 422*25cbff28SJoris Van Damme npixels = img.width * img.height;<br> 423*25cbff28SJoris Van Damme raster = (uint32*) _TIFFmalloc(npixels * sizeof (uint32));<br> 424*25cbff28SJoris Van Damme if (raster != NULL) {<br> 425*25cbff28SJoris Van Damme if (TIFFRGBAImageGet(&img, raster, img.width, img.height)) {<br> 426*25cbff28SJoris Van Damme ...process raster data...<br> 427*25cbff28SJoris Van Damme }<br> 428*25cbff28SJoris Van Damme _TIFFfree(raster);<br> 429*25cbff28SJoris Van Damme }<br> 430*25cbff28SJoris Van Damme TIFFRGBAImageEnd(&img);<br> 431*25cbff28SJoris Van Damme } else<br> 432*25cbff28SJoris Van Damme TIFFError(argv[1], emsg);<br> 433*25cbff28SJoris Van Damme TIFFClose(tif);<br> 434*25cbff28SJoris Van Damme }<br> 435*25cbff28SJoris Van Damme exit(0);<br> 436*25cbff28SJoris Van Damme }</tt> 437*25cbff28SJoris Van Damme </p> 438*25cbff28SJoris Van Damme <p> 4390ef31e1fSMike Welles However this usage does not take advantage of the more fine-grained 4400ef31e1fSMike Welles control that's possible. That is, by using this interface it is 4410ef31e1fSMike Welles possible to: 442*25cbff28SJoris Van Damme </p> 443*25cbff28SJoris Van Damme <ul> 444*25cbff28SJoris Van Damme <li>repeatedly fetch (and manipulate) an image without opening 445*25cbff28SJoris Van Damme and closing the file</li> 446*25cbff28SJoris Van Damme <li>interpose a method for packing raster pixel data according to 447*25cbff28SJoris Van Damme application-specific needs (or write the data at all)</li> 448*25cbff28SJoris Van Damme <li>interpose methods that handle TIFF formats that are not already 449*25cbff28SJoris Van Damme handled by the core library</li> 450*25cbff28SJoris Van Damme </ul> 451*25cbff28SJoris Van Damme <p> 4520ef31e1fSMike Welles The first item means that, for example, image viewers that want to 4530ef31e1fSMike Welles handle multiple files can cache decoding information in order to 4540ef31e1fSMike Welles speedup the work required to display a TIFF image. 455*25cbff28SJoris Van Damme </p> 456*25cbff28SJoris Van Damme <p> 4570ef31e1fSMike Welles The second item is the main reason for this interface. By interposing 458*25cbff28SJoris Van Damme a "put method" (the routine that is called to pack pixel data in 4590ef31e1fSMike Welles the raster) it is possible share the core logic that understands how 4600ef31e1fSMike Welles to deal with TIFF while packing the resultant pixels in a format that 4610ef31e1fSMike Welles is optimized for the application. This alternate format might be very 4620ef31e1fSMike Welles different than the 8-bit per sample ABGR format the library writes by 4630ef31e1fSMike Welles default. For example, if the application is going to display the image 4640ef31e1fSMike Welles on an 8-bit colormap display the put routine might take the data and 4650ef31e1fSMike Welles convert it on-the-fly to the best colormap indices for display. 466*25cbff28SJoris Van Damme </p> 467*25cbff28SJoris Van Damme <p> 4680ef31e1fSMike Welles The last item permits an application to extend the library 4690ef31e1fSMike Welles without modifying the core code. 4700ef31e1fSMike Welles By overriding the code provided an application might add support 4710ef31e1fSMike Welles for some esoteric flavor of TIFF that it needs, or it might 4720ef31e1fSMike Welles substitute a packing routine that is able to do optimizations 4730ef31e1fSMike Welles using application/environment-specific information. 474*25cbff28SJoris Van Damme </p> 475*25cbff28SJoris Van Damme <p> 476*25cbff28SJoris Van Damme The TIFF image viewer found in <b>tools/sgigt.c</b> is an example 477*25cbff28SJoris Van Damme of an application that makes use of the <tt>TIFFRGBAImage</tt> 4780ef31e1fSMike Welles support. 479*25cbff28SJoris Van Damme </p> 480*25cbff28SJoris Van Damme <hr> 481*25cbff28SJoris Van Damme <h2 id="scanlines">Scanline-based Image I/O</h2> 482*25cbff28SJoris Van Damme <p> 483*25cbff28SJoris Van Damme The simplest interface provided by <tt>libtiff</tt> is a 4840ef31e1fSMike Welles scanline-oriented interface that can be used to read TIFF 4850ef31e1fSMike Welles images that have their image data organized in strips 4860ef31e1fSMike Welles (trying to use this interface to read data written in tiles 4870ef31e1fSMike Welles will produce errors.) 4880ef31e1fSMike Welles A scanline is a one pixel high row of image data whose width 4890ef31e1fSMike Welles is the width of the image. 4900ef31e1fSMike Welles Data is returned packed if the image data is stored with samples 4910ef31e1fSMike Welles packed together, or as arrays of separate samples if the data 4920ef31e1fSMike Welles is stored with samples separated. 4930ef31e1fSMike Welles The major limitation of the scanline-oriented interface, other 4940ef31e1fSMike Welles than the need to first identify an existing file as having a 4950ef31e1fSMike Welles suitable organization, is that random access to individual 4960ef31e1fSMike Welles scanlines can only be provided when data is not stored in a 4970ef31e1fSMike Welles compressed format, or when the number of rows in a strip 498*25cbff28SJoris Van Damme of image data is set to one (<tt>RowsPerStrip</tt> is one). 499*25cbff28SJoris Van Damme </p> 500*25cbff28SJoris Van Damme <p> 5010ef31e1fSMike Welles Two routines are provided for scanline-based i/o: 502*25cbff28SJoris Van Damme <tt>TIFFReadScanline</tt> 5030ef31e1fSMike Welles and 504*25cbff28SJoris Van Damme <tt>TIFFWriteScanline</tt>. 5050ef31e1fSMike Welles For example, to read the contents of a file that 5060ef31e1fSMike Welles is assumed to be organized in strips, the following might be used: 507*25cbff28SJoris Van Damme </p> 508*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 509*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 510*25cbff28SJoris Van Damme main()<br> 511*25cbff28SJoris Van Damme {<br> 512*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("myfile.tif", "r");<br> 513*25cbff28SJoris Van Damme if (tif) {<br> 514*25cbff28SJoris Van Damme uint32 imagelength;<br> 515*25cbff28SJoris Van Damme tdata_t buf;<br> 516*25cbff28SJoris Van Damme uint32 row;<br> 517*25cbff28SJoris Van Damme <br> 518*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imagelength);<br> 519*25cbff28SJoris Van Damme buf = _TIFFmalloc(TIFFScanlineSize(tif));<br> 520*25cbff28SJoris Van Damme for (row = 0; row < imagelength; row++)<br> 521*25cbff28SJoris Van Damme tiffreadscanline(tif, buf, row);<br> 522*25cbff28SJoris Van Damme _tifffree(buf);<br> 523*25cbff28SJoris Van Damme tiffclose(tif);<br> 524*25cbff28SJoris Van Damme }<br> 525*25cbff28SJoris Van Damme }</tt> 526*25cbff28SJoris Van Damme </p> 527*25cbff28SJoris Van Damme <p> 528*25cbff28SJoris Van Damme <tt>TIFFScanlineSize</tt> returns the number of bytes in 529*25cbff28SJoris Van Damme a decoded scanline, as returned by <tt>TIFFReadScanline</tt>. 5300ef31e1fSMike Welles Note however that if the file had been create with samples 5310ef31e1fSMike Welles written in separate planes, then the above code would only 5320ef31e1fSMike Welles read data that contained the first sample of each pixel; 5330ef31e1fSMike Welles to handle either case one might use the following instead: 534*25cbff28SJoris Van Damme </p> 535*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 536*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 537*25cbff28SJoris Van Damme main()<br> 538*25cbff28SJoris Van Damme {<br> 539*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("myfile.tif", "r");<br> 540*25cbff28SJoris Van Damme if (tif) {<br> 541*25cbff28SJoris Van Damme uint32 imagelength;<br> 542*25cbff28SJoris Van Damme tdata_t buf;<br> 543*25cbff28SJoris Van Damme uint32 row;<br> 544*25cbff28SJoris Van Damme <br> 545*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imagelength);<br> 546*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_PLANARCONFIG, &config);<br> 547*25cbff28SJoris Van Damme buf = _TIFFmalloc(TIFFScanlineSize(tif));<br> 548*25cbff28SJoris Van Damme if (config == PLANARCONFIG_CONTIG) {<br> 549*25cbff28SJoris Van Damme for (row = 0; row < imagelength; row++)<br> 550*25cbff28SJoris Van Damme tiffreadscanline(tif, buf, row);<br> 551*25cbff28SJoris Van Damme } else if (config == planarconfig_separate) {<br> 552*25cbff28SJoris Van Damme uint16 s, nsamples;<br> 553*25cbff28SJoris Van Damme <br> 554*25cbff28SJoris Van Damme tiffgetfield(tif, tifftag_samplesperpixel, &nsamples);<br> 555*25cbff28SJoris Van Damme for (s = 0; s < nsamples; s++)<br> 556*25cbff28SJoris Van Damme for (row = 0; row < imagelength; row++)<br> 557*25cbff28SJoris Van Damme tiffreadscanline(tif, buf, row, s);<br> 558*25cbff28SJoris Van Damme }<br> 559*25cbff28SJoris Van Damme _tifffree(buf);<br> 560*25cbff28SJoris Van Damme tiffclose(tif);<br> 561*25cbff28SJoris Van Damme }<br> 562*25cbff28SJoris Van Damme }</tt> 563*25cbff28SJoris Van Damme </p> 564*25cbff28SJoris Van Damme <p> 5650ef31e1fSMike Welles Beware however that if the following code were used instead to 566*25cbff28SJoris Van Damme read data in the case <tt>PLANARCONFIG_SEPARATE</tt>,... 567*25cbff28SJoris Van Damme </p> 568*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 569*25cbff28SJoris Van Damme <tt> for (row = 0; row < imagelength; row++)<br> 570*25cbff28SJoris Van Damme for (s = 0; s < nsamples; s++)<br> 571*25cbff28SJoris Van Damme tiffreadscanline(tif, buf, row, s);</tt> 572*25cbff28SJoris Van Damme </p> 573*25cbff28SJoris Van Damme <p> 574*25cbff28SJoris Van Damme ...then problems would arise if <tt>RowsPerStrip</tt> was not one 5750ef31e1fSMike Welles because the order in which scanlines are requested would require 5760ef31e1fSMike Welles random access to data within strips (something that is not supported 5770ef31e1fSMike Welles by the library when strips are compressed). 578*25cbff28SJoris Van Damme </p> 579*25cbff28SJoris Van Damme <hr> 580*25cbff28SJoris Van Damme <h2 id="strips">Strip-oriented Image I/O</h2> 581*25cbff28SJoris Van Damme <p> 5820ef31e1fSMike Welles The strip-oriented interfaces provided by the library provide 5830ef31e1fSMike Welles access to entire strips of data. Unlike the scanline-oriented 5840ef31e1fSMike Welles calls, data can be read or written compressed or uncompressed. 5850ef31e1fSMike Welles Accessing data at a strip (or tile) level is often desirable 5860ef31e1fSMike Welles because there are no complications with regard to random access 5870ef31e1fSMike Welles to data within strips. 588*25cbff28SJoris Van Damme </p> 589*25cbff28SJoris Van Damme <p> 5900ef31e1fSMike Welles A simple example of reading an image by strips is: 591*25cbff28SJoris Van Damme </p> 592*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 593*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 594*25cbff28SJoris Van Damme main()<br> 595*25cbff28SJoris Van Damme {<br> 596*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("myfile.tif", "r");<br> 597*25cbff28SJoris Van Damme if (tif) {<br> 598*25cbff28SJoris Van Damme tdata_t buf;<br> 599*25cbff28SJoris Van Damme tstrip_t strip;<br> 600*25cbff28SJoris Van Damme <br> 601*25cbff28SJoris Van Damme buf = _TIFFmalloc(TIFFStripSize(tif));<br> 602*25cbff28SJoris Van Damme for (strip = 0; strip < tiffnumberofstrips(tif); strip++)<br> 603*25cbff28SJoris Van Damme tiffreadencodedstrip(tif, strip, buf, (tsize_t) -1);<br> 604*25cbff28SJoris Van Damme _tifffree(buf);<br> 605*25cbff28SJoris Van Damme tiffclose(tif);<br> 606*25cbff28SJoris Van Damme }<br> 607*25cbff28SJoris Van Damme }</tt> 608*25cbff28SJoris Van Damme </p> 609*25cbff28SJoris Van Damme <p> 610*25cbff28SJoris Van Damme Notice how a strip size of <tt>-1</tt> is used; <tt>TIFFReadEncodedStrip</tt> 6110ef31e1fSMike Welles will calculate the appropriate size in this case. 612*25cbff28SJoris Van Damme </p> 613*25cbff28SJoris Van Damme <p> 6140ef31e1fSMike Welles The above code reads strips in the order in which the 6150ef31e1fSMike Welles data is physically stored in the file. If multiple samples 616*25cbff28SJoris Van Damme are present and data is stored with <tt>PLANARCONFIG_SEPARATE</tt> 6170ef31e1fSMike Welles then all the strips of data holding the first sample will be 6180ef31e1fSMike Welles read, followed by strips for the second sample, etc. 619*25cbff28SJoris Van Damme </p> 620*25cbff28SJoris Van Damme <p> 6210ef31e1fSMike Welles Finally, note that the last strip of data in an image may have fewer 622*25cbff28SJoris Van Damme rows in it than specified by the <tt>RowsPerStrip</tt> tag. A 6230ef31e1fSMike Welles reader should not assume that each decoded strip contains a full 6240ef31e1fSMike Welles set of rows in it. 625*25cbff28SJoris Van Damme </p> 626*25cbff28SJoris Van Damme <p> 6270ef31e1fSMike Welles The following is an example of how to read raw strips of data from 6280ef31e1fSMike Welles a file: 629*25cbff28SJoris Van Damme </p> 630*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 631*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 632*25cbff28SJoris Van Damme main()<br> 633*25cbff28SJoris Van Damme {<br> 634*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("myfile.tif", "r");<br> 635*25cbff28SJoris Van Damme if (tif) {<br> 636*25cbff28SJoris Van Damme tdata_t buf;<br> 637*25cbff28SJoris Van Damme tstrip_t strip;<br> 638*25cbff28SJoris Van Damme uint32* bc;<br> 639*25cbff28SJoris Van Damme uint32 stripsize;<br> 640*25cbff28SJoris Van Damme <br> 641*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_STRIPBYTECOUNTS, &bc);<br> 642*25cbff28SJoris Van Damme stripsize = bc[0];<br> 643*25cbff28SJoris Van Damme buf = _TIFFmalloc(stripsize);<br> 644*25cbff28SJoris Van Damme for (strip = 0; strip < tiffnumberofstrips(tif); strip++) {<br> 645*25cbff28SJoris Van Damme if (bc[strip] > stripsize) {<br> 646*25cbff28SJoris Van Damme buf = _TIFFrealloc(buf, bc[strip]);<br> 647*25cbff28SJoris Van Damme stripsize = bc[strip];<br> 648*25cbff28SJoris Van Damme }<br> 649*25cbff28SJoris Van Damme TIFFReadRawStrip(tif, strip, buf, bc[strip]);<br> 650*25cbff28SJoris Van Damme }<br> 651*25cbff28SJoris Van Damme _TIFFfree(buf);<br> 652*25cbff28SJoris Van Damme TIFFClose(tif);<br> 653*25cbff28SJoris Van Damme }<br> 654*25cbff28SJoris Van Damme }</tt> 655*25cbff28SJoris Van Damme </p> 656*25cbff28SJoris Van Damme <p> 6570ef31e1fSMike Welles As above the strips are read in the order in which they are 6580ef31e1fSMike Welles physically stored in the file; this may be different from the 6590ef31e1fSMike Welles logical ordering expected by an application. 660*25cbff28SJoris Van Damme </p> 661*25cbff28SJoris Van Damme <hr> 662*25cbff28SJoris Van Damme <h2 id="tiles">Tile-oriented Image I/O</h2> 663*25cbff28SJoris Van Damme <p> 6640ef31e1fSMike Welles Tiles of data may be read and written in a manner similar to strips. 6650ef31e1fSMike Welles With this interface, an image is 6660ef31e1fSMike Welles broken up into a set of rectangular areas that may have dimensions 6670ef31e1fSMike Welles less than the image width and height. All the tiles 6680ef31e1fSMike Welles in an image have the same size, and the tile width and length must each 6690ef31e1fSMike Welles be a multiple of 16 pixels. Tiles are ordered left-to-right and 6700ef31e1fSMike Welles top-to-bottom in an image. As for scanlines, samples can be packed 6710ef31e1fSMike Welles contiguously or separately. When separated, all the tiles for a sample 6720ef31e1fSMike Welles are colocated in the file. That is, all the tiles for sample 0 appear 6730ef31e1fSMike Welles before the tiles for sample 1, etc. 674*25cbff28SJoris Van Damme </p> 675*25cbff28SJoris Van Damme <p> 6760ef31e1fSMike Welles Tiles and strips may also be extended in a z dimension to form 6770ef31e1fSMike Welles volumes. Data volumes are organized as "slices". That is, all the 6780ef31e1fSMike Welles data for a slice is colocated. Volumes whose data is organized in 6790ef31e1fSMike Welles tiles can also have a tile depth so that data can be organized in 6800ef31e1fSMike Welles cubes. 681*25cbff28SJoris Van Damme </p> 682*25cbff28SJoris Van Damme <p> 6830ef31e1fSMike Welles There are actually two interfaces for tiles. 6840ef31e1fSMike Welles One interface is similar to scanlines, to read a tiled image, 6850ef31e1fSMike Welles code of the following sort might be used: 686*25cbff28SJoris Van Damme </p> 687*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 688*25cbff28SJoris Van Damme <tt>main()<br> 689*25cbff28SJoris Van Damme {<br> 690*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("myfile.tif", "r");<br> 691*25cbff28SJoris Van Damme if (tif) {<br> 692*25cbff28SJoris Van Damme uint32 imageWidth, imageLength;<br> 693*25cbff28SJoris Van Damme uint32 tileWidth, tileLength;<br> 694*25cbff28SJoris Van Damme uint32 x, y;<br> 695*25cbff28SJoris Van Damme tdata_t buf;<br> 696*25cbff28SJoris Van Damme <br> 697*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_IMAGEWIDTH, &imageWidth);<br> 698*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_IMAGELENGTH, &imageLength);<br> 699*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_TILEWIDTH, &tileWidth);<br> 700*25cbff28SJoris Van Damme TIFFGetField(tif, TIFFTAG_TILELENGTH, &tileLength);<br> 701*25cbff28SJoris Van Damme buf = _TIFFmalloc(TIFFTileSize(tif));<br> 702*25cbff28SJoris Van Damme for (y = 0; y < imagelength; y += tilelength)<br> 703*25cbff28SJoris Van Damme for (x = 0; x < imagewidth; x += tilewidth)<br> 704*25cbff28SJoris Van Damme tiffreadtile(tif, buf, x, y, 0);<br> 705*25cbff28SJoris Van Damme _tifffree(buf);<br> 706*25cbff28SJoris Van Damme tiffclose(tif);<br> 707*25cbff28SJoris Van Damme }<br> 708*25cbff28SJoris Van Damme }</tt> 709*25cbff28SJoris Van Damme </p> 710*25cbff28SJoris Van Damme <p> 7110ef31e1fSMike Welles (once again, we assume samples are packed contiguously.) 712*25cbff28SJoris Van Damme </p> 713*25cbff28SJoris Van Damme <p> 7140ef31e1fSMike Welles Alternatively a direct interface to the low-level data is provided 7150ef31e1fSMike Welles a la strips. Tiles can be read with 716*25cbff28SJoris Van Damme <tt>TIFFReadEncodedTile</tt> or <tt>TIFFReadRawTile</tt>, 717*25cbff28SJoris Van Damme and written with <tt>TIFFWriteEncodedTile</tt> or 718*25cbff28SJoris Van Damme <tt>TIFFWriteRawTile</tt>. For example, to read all the tiles in an image: 719*25cbff28SJoris Van Damme </p> 720*25cbff28SJoris Van Damme <p style="margin-left: 40px"> 721*25cbff28SJoris Van Damme <tt>#include "tiffio.h"<br> 722*25cbff28SJoris Van Damme main()<br> 723*25cbff28SJoris Van Damme {<br> 724*25cbff28SJoris Van Damme TIFF* tif = TIFFOpen("myfile.tif", "r");<br> 725*25cbff28SJoris Van Damme if (tif) {<br> 726*25cbff28SJoris Van Damme tdata_t buf;<br> 727*25cbff28SJoris Van Damme ttile_t tile;<br> 728*25cbff28SJoris Van Damme <br> 729*25cbff28SJoris Van Damme buf = _TIFFmalloc(TIFFTileSize(tif));<br> 730*25cbff28SJoris Van Damme for (tile = 0; tile < tiffnumberoftiles(tif); tile++)<br> 731*25cbff28SJoris Van Damme tiffreadencodedtile(tif, tile, buf, (tsize_t) -1);<br> 732*25cbff28SJoris Van Damme _tifffree(buf);<br> 733*25cbff28SJoris Van Damme tiffclose(tif);<br> 734*25cbff28SJoris Van Damme }<br> 735*25cbff28SJoris Van Damme }</tt> 736*25cbff28SJoris Van Damme </p> 737*25cbff28SJoris Van Damme <hr> 738*25cbff28SJoris Van Damme <h2 id="other">Other Stuff</h2> 739*25cbff28SJoris Van Damme <p> 740*25cbff28SJoris Van Damme Some other stuff will almost certainly go here... 741*25cbff28SJoris Van Damme </p> 742*25cbff28SJoris Van Damme <hr> 743*25cbff28SJoris Van Damme <p> 744*25cbff28SJoris Van Damme Last updated: $Date: 2005-12-28 06:47:50 $ 745*25cbff28SJoris Van Damme </p> 746*25cbff28SJoris Van Damme</body> 747*25cbff28SJoris Van Damme</html> 748
