1<HTML> 2<HEAD> 3<TITLE> 4 Changes in TIFF v4.0.0 5</TITLE> 6</HEAD> 7 8<BODY BGCOLOR=white> 9<FONT FACE="Helvetica, Arial, Sans"> 10<FONT FACE="Helvetica, Arial, Sans"> 11 12<BASEFONT SIZE=4> 13<B><FONT SIZE=+3>T</FONT>IFF <FONT SIZE=+2>C</FONT>HANGE <FONT SIZE=+2>I</FONT>NFORMATION</B> 14<BASEFONT SIZE=3> 15 16<UL> 17<HR SIZE=4 WIDTH=65% ALIGN=left> 18<B>Current Version</B>: v4.0.0<BR> 19<B>Previous Version</B>: <A HREF=v3.8.2.html>v3.8.2</a><BR> 20<B>Master FTP Site</B>: <A HREF="ftp://ftp.remotesensing.org/pub/libtiff"> 21ftp.remotesensing.org</a>, directory pub/libtiff</A><BR> 22<B>Master HTTP Site</B>: <A HREF="http://www.remotesensing.org/libtiff"> 23http://www.remotesensing.org/libtiff</a> 24<HR SIZE=4 WIDTH=65% ALIGN=left> 25</UL> 26 27<P> 28This document describes the changes made to the software between the 29<I>previous</I> and <I>current</I> versions (see above). 30If you don't find something listed here, then it was not done in this 31timeframe, or it was not considered important enough to be mentioned. 32The following information is located here: 33<UL> 34<LI><A HREF="#hightlights">Major Changes</A> 35<LI><A HREF="#configure">Changes in the software configuration</A> 36<LI><A HREF="#libtiff">Changes in libtiff</A> 37<LI><A HREF="#tools">Changes in the tools</A> 38<LI><A HREF="#contrib">Changes in the contrib area</A> 39</UL> 40<p> 41<P><HR WIDTH=65% ALIGN=left> 42 43<!---------------------------------------------------------------------------> 44 45<P><A NAME="highlights"><B><FONT SIZE=+3>M</FONT>AJOR CHANGES:</B></A></P> 46 47BigTIFF support changes: 48 49<UL> 50 51 <LI>The options parameter in the TIFFOpen and TIFFClientOpen funcs has been 52 extended. When creating new files, you can add option '4' to specify you 53 want to create a ClassicTIFF file, though that is the default and the option 54 is not strictly necessary. (As such, old calling code will continue to 55 function and create ClassicTIFF files.) Or you can add option '8' to specify 56 you want to create a BigTIFF file instead. This new option is also reflected 57 in some of the tools we already upgraded. For instance, you can use the -8 58 option on tiffcp to have tiffcp produce BigTIFF files instead of the default 59 ClassicTIFF. (Whilst on additional option is provided for version selection when 60 creating new files, no such option is necessary when reading TIFF files. 61 LibTiff reads ClassicTIFF and BigTIFF both, and the application does not 62 need to be aware which TIFF version an opened file is.) 63 64 <LI>Allthough the tag count in BigTIFF is 64bit, we restricted the count in 65 the implementation to a much more reasonable size. This is necessary in 66 current implementation, because all tag data gets read automatically in the 67 IFD reading stage, so if there's half a dozen private tags with multiple 68 gigabytes of data that causes considerable overhead even if the application 69 level is never interested in these tags. Our choice to ignore tags with data 70 longer then a certain sanity value is much needed as things stand. We also 71 recommend to step away from writing tiles that are 8 kilobyte in their 72 uncompressed form, or writing single-line strips, in really big files, 73 resulting in mega's of tiles or strips. It's much more efficient to choose 74 bigger tile or strip sizes, up to several megabyte if needed, and have a few 75 kilo of tiles or strips instead. 76 77 <LI>Allthough it's rare, some application code does directly access file 78 offsets. Some of these are automatically upgraded because they used the 79 toff_t type, others need to be aware that the datatype changed and need to 80 start using toff_t or uint64. This impacts access to tags like the EXIF IFD 81 tag, for example, or the SubIfds tag, or to StripOffsets or TileOffsets, 82 the return type of functions like TIFFCurrentDirOffset, and a parameter type to 83 functions like TIFFSetSubDirectory. 84 85 <LI>Allthough it's rare, some application code does use structures like 86 TIFFHeader or TIFFDirEntry that used to be an exact binary representation of 87 TIFF structures. These need to change. The old TIFFHeader structure is 88 replaced by the new TIFFHeaderClassic, TIFFHeaderBig, and TIFFHeaderCommon 89 structures that are an exact binary representation of the ClassicTIFF and 90 BigTIFF header, and of the part that is common to both. There is no new 91 equivalent for the old TIFFDirEntry structure (or more precisely, there is 92 still a TIFFDirEntry structure, but it is changed, moved to library-private 93 definition, and no longer an exact binary representation of the tag 94 structure of either TIFF version). 95 96 <LI>Sizer functions, like TIFFTileSize or TIFFScanlineSize and the like, 97 return a tmsize_t value (tmsize_t is defined as int32 on 32bit machines, 98 and int64 on 64bit machines, and as such it is meant to represent signed 99 memory sizes). This is because we figure 98% of the calling code 100 uses the return value as sizes in allocations and the like. So, any overflow 101 that is theoretically possible with BigTIFF when LibTiff is running on a 102 32bit system, is best detected inside the sizer functions and it is best to 103 return a type that makes sense as a memory size. If your calling code is the 104 exception and is interested in actual file size, you best use the newer 105 TIFFTileSize64 or TIFFScanlineSize64 function that returns an uint64 type. 106 107</UL> 108 109Other important backward incompatible changes in the public API: 110 111<UL> 112 <LI> TIFFReassignTagToIgnore() function and TIFFIgnoreSense enumeration 113 have been removed. They was unused and never been used properly. 114 Should be unneeded for high-level applications. 115 116 <LI> TIFFTagValue structure removed from the public tiffio.h 117 to private tif_dir.h and not accessible anymore. It should be unneeded 118 for high-level applications. 119</UL> 120 121<P><HR WIDTH=65% ALIGN=left> 122<!---------------------------------------------------------------------------> 123 124<P><A NAME="configure"><B><FONT SIZE=+3>C</FONT>HANGES IN THE SOFTWARE CONFIGURATION:</B></A></P> 125 126<UL> 127 128</UL> 129 130<P><HR WIDTH=65% ALIGN=left> 131 132<!---------------------------------------------------------------------------> 133 134<P><A NAME="libtiff"><B><FONT SIZE=+3>C</FONT>HANGES IN LIBTIFF:</B></A></P> 135 136<UL> 137 138 <LI>There is considerable change in some files 139 like tif_dirread and tif_dirwrite. These changes don't impact backwards 140 compatibility, they are mostly a clean rewrite that does allow BigTIFF 141 support as well as somewhat more 142 robust reading of the unexpected already and will also serve future API 143 extension but does not impact current API or functionality in a negative way 144 that you need to know about. 145 146 <LI>Allthough there is still a functional definition for types like toff_t 147 (file offset), tstrip_t (strip index number), etc, we recommend against 148 using these in newer code. We have learned that it is next to impossible to 149 use these consistently and make real abstraction of the binary format of 150 these types. Instead, at a certain level we always end up doing casts 151 anyway, and taking the exact binary format into account, so these types are 152 nothing but dangerously misleading and obfuscating. You do not need to 153 update calling code that uses them, as 99.9% of such code will continue to 154 work. But we recommend against using them in newer calling code, and we 155 started replacing them with binary clear types like uint16, uint32 and such 156 in the library. 157 158 <LI>We do use and will continue to use one functional type that is an 159 exception to the above rule, being tmsize_t. This is a signed memory size 160 type, i.e. it is int32 on 32bit machines, or int64 on 64bit machines. 161 162</UL> 163 164<P><HR WIDTH=65% ALIGN=left> 165 166<!--------------------------------------------------------------------------> 167 168<P><A NAME="tools"><B><FONT SIZE=+3>C</FONT>HANGES IN THE TOOLS:</B></A></P> 169 170<UL> 171 172</UL> 173 174<P><HR WIDTH=65% ALIGN=left> 175 176<!---------------------------------------------------------------------------> 177 178<P><A NAME="contrib"><B><FONT SIZE=+3>C</FONT>HANGES IN THE CONTRIB AREA:</B></A></P> 179 180<UL> 181</UL> 182 183Last updated $Date: 2007-07-05 14:15:30 $. 184 185</BODY> 186</HTML> 187