libtiff-4.0.7/html/v4.0.0.html

<HTML>
<HEAD>
<TITLE>
	Changes in TIFF v4.0.0
</TITLE>
</HEAD>

<BODY BGCOLOR=white>
<FONT FACE="Helvetica, Arial, Sans">
<FONT FACE="Helvetica, Arial, Sans">

<BASEFONT SIZE=4>
<B><FONT SIZE=+3>T</FONT>IFF <FONT SIZE=+2>C</FONT>HANGE <FONT SIZE=+2>I</FONT>NFORMATION</B>
<BASEFONT SIZE=3>

<UL>
<HR SIZE=4 WIDTH=65% ALIGN=left>
<B>Current Version</B>: v4.0.0<BR>
<B>Previous Version</B>: <A HREF=v3.8.2.html>v3.8.2</a><BR>
<B>Master FTP Site</B>: <A HREF="ftp://ftp.remotesensing.org/pub/libtiff">
ftp.remotesensing.org</a>, directory pub/libtiff</A><BR>
<B>Master HTTP Site</B>: <A HREF="http://www.remotesensing.org/libtiff">
http://www.remotesensing.org/libtiff</a>
<HR SIZE=4 WIDTH=65% ALIGN=left>
</UL>

<P>
This document describes the changes made to the software between the
<I>previous</I> and <I>current</I> versions (see above).
If you don't find something listed here, then it was not done in this
timeframe, or it was not considered important enough to be mentioned.
The following information is located here:
<UL>
<LI><A HREF="#hightlights">Major Changes</A>
<LI><A HREF="#configure">Changes in the software configuration</A>
<LI><A HREF="#libtiff">Changes in libtiff</A>
<LI><A HREF="#tools">Changes in the tools</A>
<LI><A HREF="#contrib">Changes in the contrib area</A>
</UL>
<p>
<P><HR WIDTH=65% ALIGN=left>

<!--------------------------------------------------------------------------->

<P><A NAME="highlights"><B><FONT SIZE=+3>M</FONT>AJOR CHANGES:</B></A></P>

BigTIFF support changes:

<UL>

	<LI>The options parameter in the TIFFOpen and TIFFClientOpen funcs has
	been extended. When creating new files, you can add option '4' to
	specify you want to create a ClassicTIFF file, though that is the
	default and the option is not strictly necessary. (As such, old
	calling code will continue to function and create ClassicTIFF files.)
	Or you can add option '8' to specify you want to create a BigTIFF file
	instead. This new option is also reflected in some of the tools we
	already upgraded. For instance, you can use the -8 option on tiffcp to
	have tiffcp produce BigTIFF files instead of the default ClassicTIFF.
	(Whilst on additional option is provided for version selection when
	creating new files, no such option is necessary when reading TIFF
	files. LibTiff reads ClassicTIFF and BigTIFF both, and the application
	does not need to be aware which TIFF version an opened file is.)

	<LI>Although the tag count in BigTIFF is 64bit, we restricted the
	count in the implementation to a much more reasonable size. This is
	necessary in current implementation, because all tag data gets read
	automatically in the IFD reading stage, so if there's half a dozen
	private tags with multiple gigabytes of data that causes considerable
	overhead even if the application level is never interested in these
	tags. Our choice to ignore tags with data longer then a certain sanity
	value is much needed as things stand. We also recommend to step away
	from writing tiles that are 8 kilobyte in their uncompressed form, or
	writing single-line strips, in really big files, resulting in mega's
	of tiles or strips. It's much more efficient to choose bigger tile or
	strip sizes, up to several megabyte if needed, and have a few kilo of
	tiles or strips instead.

	<LI>Although it's rare, some application code does directly access
	file offsets. Some of these are automatically upgraded because they
	used the toff_t type, others need to be aware that the datatype
	changed and need to start using toff_t or uint64. This impacts access
	to tags like the EXIF IFD tag, for example, or the SubIfds tag, or to
	StripOffsets or TileOffsets, the return type of functions like
	TIFFCurrentDirOffset, and a parameter type to functions like
	TIFFSetSubDirectory.

	<LI>Although it's rare, some application code does use structures
	like TIFFHeader or TIFFDirEntry that used to be an exact binary
	representation of TIFF structures. These need to change. The old
	TIFFHeader structure is replaced by the new TIFFHeaderClassic,
	TIFFHeaderBig, and TIFFHeaderCommon structures that are an exact
	binary representation of the ClassicTIFF and BigTIFF header, and of
	the part that is common to both. There is no new equivalent for the
	old TIFFDirEntry structure (or more precisely, there is still a
	TIFFDirEntry structure, but it is changed, moved to library-private
	definition, and no longer an exact binary representation of the tag
	structure of either TIFF version).

	<LI>Sizer functions, like TIFFTileSize or TIFFScanlineSize and the
	like, return a tmsize_t value (tmsize_t is defined as int32 on 32bit
	machines, and int64 on 64bit machines, and as such it is meant to
	represent signed memory sizes). This is because we figure 98% of the
	calling code uses the return value as sizes in allocations and the
	like. So, any overflow that is theoretically possible with BigTIFF
	when LibTiff is running on a 32bit system, is best detected inside the
	sizer functions and it is best to return a type that makes sense as a
	memory size. If your calling code is the exception and is interested
	in actual file size, you best use the newer TIFFTileSize64 or
	TIFFScanlineSize64 function that returns an uint64 type.

</UL>

Other important backward incompatible changes in the public API:

<UL>
	<LI> TIFFFieldWithTag() and TIFFFieldWithName() functions now return
	pointer to TIFFField constant object instead of TIFFFieldInfo.

	<LI> TIFFReassignTagToIgnore() function and TIFFIgnoreSense enumeration
	have been removed. They was unused and never been used properly.
	Should be unneeded for high-level applications.

	<LI> TIFFTagValue structure removed from the public tiffio.h
	to private tif_dir.h and not accessible anymore. It should be unneeded
	for high-level applications.
</UL>

<P><HR WIDTH=65% ALIGN=left>
<!--------------------------------------------------------------------------->

<P><A NAME="configure"><B><FONT SIZE=+3>C</FONT>HANGES IN THE SOFTWARE CONFIGURATION:</B></A></P>

<UL>

</UL>

<P><HR WIDTH=65% ALIGN=left>

<!--------------------------------------------------------------------------->

<P><A NAME="libtiff"><B><FONT SIZE=+3>C</FONT>HANGES IN LIBTIFF:</B></A></P>

<UL>

	<LI>There is considerable change in some files
	like tif_dirread and tif_dirwrite. These changes don't impact backwards
	compatibility, they are mostly a clean rewrite that does allow BigTIFF
	support as well as somewhat more
	robust reading of the unexpected already and will also serve future API
	extension but does not impact current API or functionality in a negative way
	that you need to know about.

	<LI>Although there is still a functional definition for types like toff_t
	(file offset), tstrip_t (strip index number), etc, we recommend against
	using these in newer code. We have learned that it is next to impossible to
	use these consistently and make real abstraction of the binary format of
	these types. Instead, at a certain level we always end up doing casts
	anyway, and taking the exact binary format into account, so these types are
	nothing but dangerously misleading and obfuscating. You do not need to
	update calling code that uses them, as 99.9% of such code will continue to
	work. But we recommend against using them in newer calling code, and we
	started replacing them with binary clear types like uint16, uint32 and such
	in the library.

	<LI>We do use and will continue to use one functional type that is an
	exception to the above rule, being tmsize_t. This is a signed memory size
	type, i.e. it is int32 on 32bit machines, or int64 on 64bit machines.

</UL>

<P><HR WIDTH=65% ALIGN=left>

<!-------------------------------------------------------------------------->

<P><A NAME="tools"><B><FONT SIZE=+3>C</FONT>HANGES IN THE TOOLS:</B></A></P>

<UL>

</UL>

<P><HR WIDTH=65% ALIGN=left>

<!--------------------------------------------------------------------------->

<P><A NAME="contrib"><B><FONT SIZE=+3>C</FONT>HANGES IN THE CONTRIB AREA:</B></A></P>

<UL>
</UL>

Last updated $Date: 2007-07-09 10:19:31 $.

</BODY>
</HTML>