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://download.osgeo.org/libtiff"> 23http://download.osgeo.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> TIFFRewriteField() renamed into _TIFFRewriteField() and moved out 118 from the public interface (from tiffio.h to tiffiop.h). Type of its 119 'count' parameter changed from uint32 to tmsize_t. 120 121 <LI> TIFFMergeFieldInfo() returns non-void result now. It returns 0 122 if successful and -1 if failed. Though this is now obsoleted function 123 and should not be used in new programs. Use the new tag extension 124 scheme instead. 125 126 <LI> TIFFFieldWithTag() and TIFFFieldWithName() functions now return 127 pointer to TIFFField constant object instead of TIFFFieldInfo. 128 129 <LI> TIFFReassignTagToIgnore() function and TIFFIgnoreSense enumeration 130 have been removed. They was unused and never been used properly. 131 Should be unneeded for high-level applications. 132 133 <LI> TIFFTagValue structure removed from the public tiffio.h 134 to private tif_dir.h and not accessible anymore. It should be unneeded 135 for high-level applications. 136</UL> 137 138<P><HR WIDTH=65% ALIGN=left> 139<!---------------------------------------------------------------------------> 140 141<P><A NAME="configure"><B><FONT SIZE=+3>C</FONT>HANGES IN THE SOFTWARE CONFIGURATION:</B></A></P> 142 143<UL> 144 145</UL> 146 147<P><HR WIDTH=65% ALIGN=left> 148 149<!---------------------------------------------------------------------------> 150 151<P><A NAME="libtiff"><B><FONT SIZE=+3>C</FONT>HANGES IN LIBTIFF:</B></A></P> 152 153<UL> 154 155 <LI>There is considerable change in some files 156 like tif_dirread and tif_dirwrite. These changes don't impact backwards 157 compatibility, they are mostly a clean rewrite that does allow BigTIFF 158 support as well as somewhat more 159 robust reading of the unexpected already and will also serve future API 160 extension but does not impact current API or functionality in a negative way 161 that you need to know about. 162 163 <LI>Although there is still a functional definition for types like toff_t 164 (file offset), tstrip_t (strip index number), etc, we recommend against 165 using these in newer code. We have learned that it is next to impossible to 166 use these consistently and make real abstraction of the binary format of 167 these types. Instead, at a certain level we always end up doing casts 168 anyway, and taking the exact binary format into account, so these types are 169 nothing but dangerously misleading and obfuscating. You do not need to 170 update calling code that uses them, as 99.9% of such code will continue to 171 work. But we recommend against using them in newer calling code, and we 172 started replacing them with binary clear types like uint16, uint32 and such 173 in the library. 174 175 <LI>We do use and will continue to use one functional type that is an 176 exception to the above rule, being tmsize_t. This is a signed memory size 177 type, i.e. it is int32 on 32bit machines, or int64 on 64bit machines. 178 179</UL> 180 181<P><HR WIDTH=65% ALIGN=left> 182 183<!--------------------------------------------------------------------------> 184 185<P><A NAME="tools"><B><FONT SIZE=+3>C</FONT>HANGES IN THE TOOLS:</B></A></P> 186 187<UL> 188 189</UL> 190 191<P><HR WIDTH=65% ALIGN=left> 192 193<!---------------------------------------------------------------------------> 194 195<P><A NAME="contrib"><B><FONT SIZE=+3>C</FONT>HANGES IN THE CONTRIB AREA:</B></A></P> 196 197<UL> 198</UL> 199 200Last updated $Date: 2008-05-18 16:25:50 $. 201 202</BODY> 203</HTML> 204