src/tiff/html/v4.0.0.html

   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.9.5.html>v3.9.5</a><BR>
  20 <B>Master FTP Site</B>: <A HREF="ftp://ftp.remotesensing.org/pub/libtiff">
  21 ftp.remotesensing.org</a>, directory pub/libtiff</A><BR>
  22 <B>Master HTTP Site</B>: <A HREF="http://download.osgeo.org/libtiff">
  23 http://download.osgeo.org/libtiff</a>
  24 <HR SIZE=4 WIDTH=65% ALIGN=left>
  25 </UL>
  26
  27 <P>
  28 This document describes the changes made to the software between the
  29 <I>previous</I> and <I>current</I> versions (see above).  If you don't
  30 find something listed here, then it was not done in this timeframe, or
  31 it was not considered important enough to be mentioned. Please consult
  32 the ChangeLog file in the source package for full change details.  The
  33 following information is located here:
  34 <UL>
  35 <LI><A HREF="#hightlights">Major Changes</A>
  36 <LI><A HREF="#configure">Changes in the software configuration</A>
  37 <LI><A HREF="#libtiff">Changes in libtiff</A>
  38 <LI><A HREF="#tools">Changes in the tools</A>
  39 <LI><A HREF="#contrib">Changes in the contrib area</A>
  40 </UL>
  41 <p>
  42 <P><HR WIDTH=65% ALIGN=left>
  43
  44 <!--------------------------------------------------------------------------->
  45
  46 <P><A NAME="highlights"><B><FONT SIZE=+3>M</FONT>AJOR CHANGES:</B></A></P>
  47
  48 BigTIFF support changes:
  49
  50 <UL>
  51
  52         <LI>The options parameter in the TIFFOpen and TIFFClientOpen funcs has
  53         been extended. When creating new files, you can add option '4' to
  54         specify you want to create a ClassicTIFF file, though that is the
  55         default and the option is not strictly necessary. (As such, old
  56         calling code will continue to function and create ClassicTIFF files.)
  57         Or you can add option '8' to specify you want to create a BigTIFF file
  58         instead. This new option is also reflected in some of the tools we
  59         already upgraded. For instance, you can use the -8 option on tiffcp to
  60         have tiffcp produce BigTIFF files instead of the default ClassicTIFF.
  61         (Whilst on additional option is provided for version selection when
  62         creating new files, no such option is necessary when reading TIFF
  63         files. LibTiff reads ClassicTIFF and BigTIFF both, and the application
  64         does not need to be aware which TIFF version an opened file is.)
  65
  66         <LI>Although the tag count in BigTIFF is 64bit, we restricted the
  67         count in the implementation to a much more reasonable size. This is
  68         necessary in current implementation, because all tag data gets read
  69         automatically in the IFD reading stage, so if there's half a dozen
  70         private tags with multiple gigabytes of data that causes considerable
  71         overhead even if the application level is never interested in these
  72         tags. Our choice to ignore tags with data longer then a certain sanity
  73         value is much needed as things stand. We also recommend to step away
  74         from writing tiles that are 8 kilobyte in their uncompressed form, or
  75         writing single-line strips, in really big files, resulting in mega's
  76         of tiles or strips. It's much more efficient to choose bigger tile or
  77         strip sizes, up to several megabyte if needed, and have a few kilo of
  78         tiles or strips instead.
  79
  80         <LI>Although it's rare, some application code does directly access
  81         file offsets. Some of these are automatically upgraded because they
  82         used the toff_t type, others need to be aware that the datatype
  83         changed and need to start using toff_t or uint64. This impacts access
  84         to tags like the EXIF IFD tag, for example, or the SubIfds tag, or to
  85         StripOffsets or TileOffsets, the return type of functions like
  86         TIFFCurrentDirOffset, and a parameter type to functions like
  87         TIFFSetSubDirectory.
  88
  89         <LI>Although it's rare, some application code does use structures
  90         like TIFFHeader or TIFFDirEntry that used to be an exact binary
  91         representation of TIFF structures. These need to change. The old
  92         TIFFHeader structure is replaced by the new TIFFHeaderClassic,
  93         TIFFHeaderBig, and TIFFHeaderCommon structures that are an exact
  94         binary representation of the ClassicTIFF and BigTIFF header, and of
  95         the part that is common to both. There is no new equivalent for the
  96         old TIFFDirEntry structure (or more precisely, there is still a
  97         TIFFDirEntry structure, but it is changed, moved to library-private
  98         definition, and no longer an exact binary representation of the tag
  99         structure of either TIFF version).
 100
 101         <LI>Sizer functions, like TIFFTileSize or TIFFScanlineSize and the
 102         like, return a tmsize_t value (tmsize_t is defined as int32 on 32bit
 103         machines, and int64 on 64bit machines, and as such it is meant to
 104         represent signed memory sizes). This is because we figure 98% of the
 105         calling code uses the return value as sizes in allocations and the
 106         like. So, any overflow that is theoretically possible with BigTIFF
 107         when LibTiff is running on a 32bit system, is best detected inside the
 108         sizer functions and it is best to return a type that makes sense as a
 109         memory size. If your calling code is the exception and is interested
 110         in actual file size, you best use the newer TIFFTileSize64 or
 111         TIFFScanlineSize64 function that returns an uint64 type.
 112
 113         <LI>These TIFF tags require a 64-bit type as an argument in
 114         libtiff 4.0.0:
 115         <UL>
 116         <LI> TIFFTAG_FREEBYTECOUNTS
 117         <LI> TIFFTAG_FREEOFFSETS
 118         <LI> TIFFTAG_STRIPBYTECOUNTS
 119         <LI> TIFFTAG_STRIPOFFSETS
 120         <LI> TIFFTAG_TILEBYTECOUNTS
 121         <LI> TIFFTAG_TILEOFFSETS
 122         </UL>
 123
 124 </UL>
 125
 126 Other important backward incompatible changes in the public API:
 127
 128 <UL>
 129         <LI> TIFFRewriteField() renamed into _TIFFRewriteField() and moved out
 130         from the public interface (from tiffio.h to tiffiop.h). Type of its
 131         'count' parameter changed from uint32 to tmsize_t.
 132
 133         <LI> TIFFMergeFieldInfo() returns non-void result now. It returns 0
 134         if successful and -1 if failed. Though this is now obsoleted function
 135         and should not be used in new programs. Use the new tag extension
 136         scheme instead.
 137
 138         <LI> TIFFFieldWithTag() and TIFFFieldWithName() functions now return
 139         pointer to TIFFField constant object instead of TIFFFieldInfo.
 140
 141         <LI> TIFFReassignTagToIgnore() function and TIFFIgnoreSense enumeration
 142         have been removed. They was unused and never been used properly.
 143         Should be unneeded for high-level applications.
 144
 145         <LI> TIFFTagValue structure removed from the public tiffio.h
 146         to private tif_dir.h and not accessible anymore. It should be unneeded
 147         for high-level applications.
 148
 149 </UL>
 150
 151 <P><HR WIDTH=65% ALIGN=left>
 152 <!--------------------------------------------------------------------------->
 153
 154 <P><A NAME="configure"><B><FONT SIZE=+3>C</FONT>HANGES IN THE SOFTWARE CONFIGURATION:</B></A></P>
 155
 156 <UL>
 157
 158         <LI>Updated autotools: Autoconf 2.68, Automake 1.11.1, libtool
 159         2.4.
 160
 161         <LI>Enabled support for Automake silent build rules
 162         (--enable-silent-rules or 'make V=0')
 163
 164         <LI>Enabled support for Automake colorized and parallel tests.
 165
 166         <LI>Added detection of 64-bit integer types since libtiff 4.0
 167         requires use of 64-bit signed and unsigned integer types.
 168
 169         <LI>Libtiff now provides a more comprehensive test suite with
 170         over 72 tests, which may be executed on Unix-like systems, or
 171         under Microsoft Windows using MinGW/MSYS or Cygwin.
 172
 173         <LI>--disable-lzma configure option to disable use of liblzma.
 174
 175         <LI>--enable-defer-strile-load configure option to enable
 176         experimental deferred strip/tile offset/size loading.  May
 177         cause some extremely sophisticated uses of libtiff to fail.
 178
 179         <LI>--enable-chunky-strip-read configure option to enable
 180         experimental enable reading large strips in chunks in
 181         TIFFReadScanline().
 182
 183         <LI>Now always uses WIN32 native I/O functions for Microsoft
 184         Windows except for under Cygwin.
 185
 186         <LI>Now provides a pkg-config support file (libtiff-4.pc).
 187
 188 </UL>
 189
 190 <P><HR WIDTH=65% ALIGN=left>
 191
 192 <!--------------------------------------------------------------------------->
 193
 194 <P><A NAME="libtiff"><B><FONT SIZE=+3>C</FONT>HANGES IN LIBTIFF:</B></A></P>
 195
 196 <UL>
 197
 198         <LI>Patches/fixes made to stable libtiff (v3.9.X) are also
 199         applied to 4.0.0.  There are too many to list here.  See the
 200         distribution ChangeLog for a detailed change list.
 201
 202         <LI>There is considerable change in some files like
 203         tif_dirread and tif_dirwrite. These changes don't impact
 204         backwards compatibility, they are mostly a clean rewrite that
 205         does allow BigTIFF support as well as somewhat more robust
 206         reading of the unexpected already and will also serve future
 207         API extension but does not impact current API or functionality
 208         in a negative way that you need to know about.
 209
 210         <LI>Although there is still a functional definition for types
 211         like toff_t (file offset), tstrip_t (strip index number), etc,
 212         we recommend against using these in newer code. We have
 213         learned that it is next to impossible to use these
 214         consistently and make real abstraction of the binary format of
 215         these types. Instead, at a certain level we always end up
 216         doing casts anyway, and taking the exact binary format into
 217         account, so these types are nothing but dangerously misleading
 218         and obfuscating. You do not need to update calling code that
 219         uses them, as 99.9% of such code will continue to work. But we
 220         recommend against using them in newer calling code, and we
 221         started replacing them with binary clear types like uint16,
 222         uint32 and such in the library.
 223
 224         <LI>We do use and will continue to use one functional type
 225         that is an exception to the above rule, being tmsize_t. This
 226         is a signed memory size type, i.e. it is int32 on 32bit
 227         machines, or int64 on 64bit machines.
 228
 229         <LI>Optionally support LZMA compression via TIFF tag 34925.
 230         Tiffcp supports compression levels similar to "-c lzma:p1" or
 231         "-c zip:p9 for setting the LZMA compression parameters.
 232
 233         <LI>Optionally defer the load of strip/tile offset and size
 234         tags for optimized scanning of directories.  Enabled with the
 235         --enable-defer-strile-load configure option (DEFER_STRILE_LOAD
 236         #define in tif_config.h).
 237
 238         <LI>Optionally enable experimental support for reading big
 239         strips in chunks.  Enabled with the --enable-chunky-strip-read
 240         configure option.
 241
 242 </UL>
 243
 244 <P><HR WIDTH=65% ALIGN=left>
 245
 246 <!-------------------------------------------------------------------------->
 247
 248 <P><A NAME="tools"><B><FONT SIZE=+3>C</FONT>HANGES IN THE TOOLS:</B></A></P>
 249
 250 <UL>
 251
 252         <LI>tiffset: add -d and -sd switches to allow operation on
 253         a particular directory, not just the first.
 254
 255 </UL>
 256
 257 <P><HR WIDTH=65% ALIGN=left>
 258
 259 <!--------------------------------------------------------------------------->
 260
 261 <P><A NAME="contrib"><B><FONT SIZE=+3>C</FONT>HANGES IN THE CONTRIB AREA:</B></A></P>
 262
 263 <UL>
 264 </UL>
 265
 266 Last updated $Date: 2011-04-09 21:01:00 $.
 267
 268 </BODY>
 269 </HTML>