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 52 been extended. When creating new files, you can add option '4' to 53 specify you want to create a ClassicTIFF file, though that is the 54 default and the option is not strictly necessary. (As such, old 55 calling code will continue to function and create ClassicTIFF files.) 56 Or you can add option '8' to specify you want to create a BigTIFF file 57 instead. This new option is also reflected in some of the tools we 58 already upgraded. For instance, you can use the -8 option on tiffcp to 59 have tiffcp produce BigTIFF files instead of the default ClassicTIFF. 60 (Whilst on additional option is provided for version selection when 61 creating new files, no such option is necessary when reading TIFF 62 files. LibTiff reads ClassicTIFF and BigTIFF both, and the application 63 does not need to be aware which TIFF version an opened file is.) 64 65 <LI>Although the tag count in BigTIFF is 64bit, we restricted the 66 count in the implementation to a much more reasonable size. This is 67 necessary in current implementation, because all tag data gets read 68 automatically in the IFD reading stage, so if there's half a dozen 69 private tags with multiple gigabytes of data that causes considerable 70 overhead even if the application level is never interested in these 71 tags. Our choice to ignore tags with data longer then a certain sanity 72 value is much needed as things stand. We also recommend to step away 73 from writing tiles that are 8 kilobyte in their uncompressed form, or 74 writing single-line strips, in really big files, resulting in mega's 75 of tiles or strips. It's much more efficient to choose bigger tile or 76 strip sizes, up to several megabyte if needed, and have a few kilo of 77 tiles or strips instead. 78 79 <LI>Although it's rare, some application code does directly access 80 file offsets. Some of these are automatically upgraded because they 81 used the toff_t type, others need to be aware that the datatype 82 changed and need to start using toff_t or uint64. This impacts access 83 to tags like the EXIF IFD tag, for example, or the SubIfds tag, or to 84 StripOffsets or TileOffsets, the return type of functions like 85 TIFFCurrentDirOffset, and a parameter type to functions like 86 TIFFSetSubDirectory. 87 88 <LI>Although it's rare, some application code does use structures 89 like TIFFHeader or TIFFDirEntry that used to be an exact binary 90 representation of TIFF structures. These need to change. The old 91 TIFFHeader structure is replaced by the new TIFFHeaderClassic, 92 TIFFHeaderBig, and TIFFHeaderCommon structures that are an exact 93 binary representation of the ClassicTIFF and BigTIFF header, and of 94 the part that is common to both. There is no new equivalent for the 95 old TIFFDirEntry structure (or more precisely, there is still a 96 TIFFDirEntry structure, but it is changed, moved to library-private 97 definition, and no longer an exact binary representation of the tag 98 structure of either TIFF version). 99 100 <LI>Sizer functions, like TIFFTileSize or TIFFScanlineSize and the 101 like, return a tmsize_t value (tmsize_t is defined as int32 on 32bit 102 machines, and int64 on 64bit machines, and as such it is meant to 103 represent signed memory sizes). This is because we figure 98% of the 104 calling code uses the return value as sizes in allocations and the 105 like. So, any overflow that is theoretically possible with BigTIFF 106 when LibTiff is running on a 32bit system, is best detected inside the 107 sizer functions and it is best to return a type that makes sense as a 108 memory size. If your calling code is the exception and is interested 109 in actual file size, you best use the newer TIFFTileSize64 or 110 TIFFScanlineSize64 function that returns an uint64 type. 111 112</UL> 113 114Other important backward incompatible changes in the public API: 115 116<UL> 117 <LI> TIFFMergeFieldInfo() returns non-void result now. It returns 0 118 if successful and -1 if failed. Though this is now obsoleted function 119 and should not be used in new programs. Use the new tag extension 120 scheme instead. 121 122 <LI> TIFFFieldWithTag() and TIFFFieldWithName() functions now return 123 pointer to TIFFField constant object instead of TIFFFieldInfo. 124 125 <LI> TIFFReassignTagToIgnore() function and TIFFIgnoreSense enumeration 126 have been removed. They was unused and never been used properly. 127 Should be unneeded for high-level applications. 128 129 <LI> TIFFTagValue structure removed from the public tiffio.h 130 to private tif_dir.h and not accessible anymore. It should be unneeded 131 for high-level applications. 132</UL> 133 134<P><HR WIDTH=65% ALIGN=left> 135<!---------------------------------------------------------------------------> 136 137<P><A NAME="configure"><B><FONT SIZE=+3>C</FONT>HANGES IN THE SOFTWARE CONFIGURATION:</B></A></P> 138 139<UL> 140 141</UL> 142 143<P><HR WIDTH=65% ALIGN=left> 144 145<!---------------------------------------------------------------------------> 146 147<P><A NAME="libtiff"><B><FONT SIZE=+3>C</FONT>HANGES IN LIBTIFF:</B></A></P> 148 149<UL> 150 151 <LI>There is considerable change in some files 152 like tif_dirread and tif_dirwrite. These changes don't impact backwards 153 compatibility, they are mostly a clean rewrite that does allow BigTIFF 154 support as well as somewhat more 155 robust reading of the unexpected already and will also serve future API 156 extension but does not impact current API or functionality in a negative way 157 that you need to know about. 158 159 <LI>Although there is still a functional definition for types like toff_t 160 (file offset), tstrip_t (strip index number), etc, we recommend against 161 using these in newer code. We have learned that it is next to impossible to 162 use these consistently and make real abstraction of the binary format of 163 these types. Instead, at a certain level we always end up doing casts 164 anyway, and taking the exact binary format into account, so these types are 165 nothing but dangerously misleading and obfuscating. You do not need to 166 update calling code that uses them, as 99.9% of such code will continue to 167 work. But we recommend against using them in newer calling code, and we 168 started replacing them with binary clear types like uint16, uint32 and such 169 in the library. 170 171 <LI>We do use and will continue to use one functional type that is an 172 exception to the above rule, being tmsize_t. This is a signed memory size 173 type, i.e. it is int32 on 32bit machines, or int64 on 64bit machines. 174 175</UL> 176 177<P><HR WIDTH=65% ALIGN=left> 178 179<!--------------------------------------------------------------------------> 180 181<P><A NAME="tools"><B><FONT SIZE=+3>C</FONT>HANGES IN THE TOOLS:</B></A></P> 182 183<UL> 184 185</UL> 186 187<P><HR WIDTH=65% ALIGN=left> 188 189<!---------------------------------------------------------------------------> 190 191<P><A NAME="contrib"><B><FONT SIZE=+3>C</FONT>HANGES IN THE CONTRIB AREA:</B></A></P> 192 193<UL> 194</UL> 195 196Last updated $Date: 2007-07-12 14:00:50 $. 197 198</BODY> 199</HTML> 200