src/tiff/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.9.5.html>v3.9.5</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://download.osgeo.org/libtiff">
http://download.osgeo.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. Please consult
the ChangeLog file in the source package for full change details.  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.

	<LI>These TIFF tags require a 64-bit type as an argument in
	libtiff 4.0.0:
	<UL>
	<LI> TIFFTAG_FREEBYTECOUNTS
	<LI> TIFFTAG_FREEOFFSETS
	<LI> TIFFTAG_STRIPBYTECOUNTS
	<LI> TIFFTAG_STRIPOFFSETS
	<LI> TIFFTAG_TILEBYTECOUNTS
	<LI> TIFFTAG_TILEOFFSETS
	</UL>

</UL>

Other important backward incompatible changes in the public API:

<UL>
	<LI> TIFFRewriteField() renamed into _TIFFRewriteField() and moved out
	from the public interface (from tiffio.h to tiffiop.h). Type of its
	'count' parameter changed from uint32 to tmsize_t.

	<LI> TIFFMergeFieldInfo() returns non-void result now. It returns 0
	if successful and -1 if failed. Though this is now obsoleted function
	and should not be used in new programs. Use the new tag extension
	scheme instead.

	<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>

	<LI>Updated autotools: Autoconf 2.68, Automake 1.11.1, libtool
	2.4.

	<LI>Enabled support for Automake silent build rules
	(--enable-silent-rules or 'make V=0')

	<LI>Enabled support for Automake colorized and parallel tests.

	<LI>Added detection of 64-bit integer types since libtiff 4.0
	requires use of 64-bit signed and unsigned integer types.

	<LI>Libtiff now provides a more comprehensive test suite with
	over 72 tests, which may be executed on Unix-like systems, or
	under Microsoft Windows using MinGW/MSYS or Cygwin.

	<LI>--disable-lzma configure option to disable use of liblzma.

	<LI>--enable-defer-strile-load configure option to enable
	experimental deferred strip/tile offset/size loading.  May
	cause some extremely sophisticated uses of libtiff to fail.

	<LI>--enable-chunky-strip-read configure option to enable
	experimental enable reading large strips in chunks in
	TIFFReadScanline().

	<LI>Now always uses WIN32 native I/O functions for Microsoft
	Windows except for under Cygwin.

	<LI>Now provides a pkg-config support file (libtiff-4.pc).

</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>Patches/fixes made to stable libtiff (v3.9.X) are also
        applied to 4.0.0.  There are too many to list here.  See the
        distribution ChangeLog for a detailed change list.

	<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.

	<LI>Optionally support LZMA compression via TIFF tag 34925.
	Tiffcp supports compression levels similar to "-c lzma:p1" or
	"-c zip:p9 for setting the LZMA compression parameters.

	<LI>Optionally defer the load of strip/tile offset and size
	tags for optimized scanning of directories.  Enabled with the
	--enable-defer-strile-load configure option (DEFER_STRILE_LOAD
	#define in tif_config.h).

	<LI>Optionally enable experimental support for reading big
	strips in chunks.  Enabled with the --enable-chunky-strip-read
	configure option.

</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>

	<LI>tiffset: add -d and -sd switches to allow operation on
	a particular directory, not just the first.

</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: 2011-04-09 21:01:00 $.

</BODY>
</HTML>
Commit	Line	Data
	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>