Tcl Image formats (Img)
		(Version 1.2b2 / March 29 1999)

		Jan Nijtmans

This file contains a collection of format handlers for Tk.
It can be used in combination with Tcl/Tk 8.0b1 or later
but at least 8.0.6 or 8.1b2 is highly recommended.

Included in this distribution are the most recent versions
(as of march '99) of the libz, libpng, libungif, libjpeg,
libtiff and libttf libraries. These are not required for compilation
of libimg, unless you need support for the PNG, JPEG, TIFF
or Text format. If your system already has shared libraries
for these formats, probably it will already work with this
package. Otherwise the tools are here to build it any time later.

INSTALL (binary distributions)

The binary distributions have a script "install.tcl" which
does all the work. On Windows there is a self-extracting executable.
It makes a guess where all the files should be installed, but
you always have the option of installing it somewhere else.

CONFIGURE

The source distributions have "configure", which  has the following
possibilities:
	configure ?options?

Some possible options:
	--prefix=<dir>		Install headers in <dir>/include.
				Default: "/usr/local"
	--exec-prefix=<dir>	Install libraries in <dir>/lib.
				Default: "${prefix}"
	--with-tcl=<dir>	Find Tcl libraries in <dir> and include files in
				<dir>/../include or <dir>/../generic.
				Default: "${exec-prefix}/lib" or a sibling directory
				of the Img build directory.
	--with-tk=<dir>		Find Tk libraries in <dir> and include files in
				<dir>/../include or <dir>/../generic.
				Default: the same values as given by --with-tcl
				or a sibling directory of the Img build directory.
	--disable-shared	Force the creation of static libraries.
	--disable-stubs		Disable stub support. This is necessary if you
	                        want to run Img 1.2 with Tcl/Tk 8.0 up to 8.0.5.


Configuration of libz, libpng, libtiff, libjpeg and libttf
will be done automatically.

PATCH

In the patches subdirectory, a file "patch.tk8" is present.
Either copy this the patch file to the Tk distribution and
type "patch <patch.tk8". If you cannot use "patch.tk8", you
can download "patchtk8.tgz" or "patchtk8.zip" from the same
place where you found Img1.2. All you have to do is copy
them to the tk8.0 directory and extract everyting.

This will enhance the photo widget (try "man photo"):
  - New image subcommand "data", which returns the content
    of the image as a string.
  - New "-format", "-grayscale" and "-background"
    options for the "data" and "write" subcommands.
  - Internal modification which allows writing of transparency
    information to disk or (base-64 encoded) strings.
  - Support for animated GIF's.
  - Additional fixes, suggested by Steve Ball,
    which makes binary data with images possible.

The Img package can be built without these patches, only a lot
of tests will fail. But reading images from files will always
work, no matter if the patch is used or not.


MAKE

By default only libimg1.2.so will be built. Further on:

	make		build libimg1.2.so only
	make z		build libz.so.1.1.3
	make png	build libpng.so.2.1.0
	make jpeg	build libjpeg.so.62.0.0
	make tiff	build libtiff.so.3.4.37
	make all	build all of above
	make test	run tests for all image formats.

Best is to start with "make". If a test fails for one of the
PNG, JPEG or TIFF formats, the error message will indicate
what is wrong. If a library is missing in your system, you
can always build it later. If a crash occurs, this might
also indicate that you better upgrade one of these libraries.

If you prefer to use different versions numbers after the
extension, you can manually adapt the Makefile. On Irix, you
can use the "ifl" libraries which are already part of the
operating system. The top of the Makefile shows which file
names to use.

INSTALL (source distributions only)

You can install whatever you like:
	make install		install libimg1.2.so only
	make install-z		install libz.so.1.1.3
	make install-png	install libpng.so.2.1.0
	make install-jpeg	install libjpeg.so.62.0.0
	make install-tiff	install libtiff.so.3.4.37
	make install-all	install all of above

USE

If you want to use the new image formats to be available
in your own scripts, add the following line somewhere
in your script:

	package require Img

This will load the library into memory and register the
format handlers into Tk.

As an example, have a look at the file "demo.tcl"

FORMAT

The pixmap image type can be used as follows:
  image create pixmap -file <filename>
or
  image create pixmap -data <data> ;#(in XPM format)

Valid format specifiers for reading photo's:
  "bmp"
  "gif -index <n>"
  "jpeg -fast -grayscale"
  "png"
  "tiff"
  "xbm"
  "xpm"
  "postscript -index <n> -zoom <x> <y>"		(-index not yet implemented)
  "pdf -index <n> -zoom <x> <y>"		(-index not yet implemented)
  "window"					(works only with "-data", not "-file")

Valid format specifiers for writing photo's:
  "bmp"
  "gif -interlaced <bool>"
  "jpeg -quality <n> -smooth <n> -grayscale -optimize -progressive"
  "png Author <name> Title <title> Description ....."
  	Each pair of arguments will add a named text chunk to the file.
  "tiff -compression <compression> -byteorder <byteorder>"
  "xbm"
  "xpm"

If wish is patched, "imageName write" has the additional options "-background"
and "-grayscale". "imageName put" has the additional option "-format".
In addition there is a new command "imageName data", which allows the options
"-background", "-format", "-from" and "-grayscale".

The format options have the following meaning:
	-background C: use color C as background color for transparent
	               parts of the image.
	-byteorder:    Byteorder for TIFF file. Should be one of bigendian,
	               littleendian, network, smallendian or {}.
	               Default: {}
	-compression:  Compression for TIFF file. Should be one of
	               none, lzw, jpeg, packbits or deflate.
	               Default: none.
	-fast:         Fast, low-quality processing.
	-grayscale:    Force incoming image to grayscale/ Create monochrome file.
	-index N:      Select one of the sub-images (GIF and postscript only, not
	               yet implemented for postscript).
	               Default value: 0
	-interlaced N: N=1: interlaced. N=0: non-interlaced.
	-optimize:     Optimize Huffman table.
	-progressive:  Create progressive file (JPEG only).
	-quality N:    Compression quality (0..100; 5-95 is useful range).
	               Default value: 75
	-smooth N:     Perform smoothing (10-30 is enough for most GIF's).
	               Default value: 0
	-zoom X Y:     Multiply image size by given scale factors. If Y is
	               missing, the default is the same as X. X and Y are
	               allowed to be in floating point format, but they are
	               rounded to the nearest practically possible value. For
	               postscript this means the zoom factors should be 
	               multiples of 1/72.

PLATFORMS
	tested:
		Linux 2.0.30	(gcc, egcs)
		IRIX 6.2	(cc, 32 bits only)
		ULTRIX 4.1	(cc, gcc, egcs)
		ULTRIX 4.4	(cc 3.0)
		HP-UX-9		(cc, gcc, egcs)
		HP-UX-10.2	(gcc, egcs)
		SunOS-4.1.2     (cc)
		Solaris 2.5	(gcc, egcs)
		FreeBSD	2.2	(gcc, egcs)
		Windows	95/98/NT(Cygwin32/MS Visual C++ 4.2/5.0/6.0)

	Not done yet:
		Mac		) someone interested
		VMS		) to try??????

	Other machines and OS's should work too. 

Feedback about other OS's and compilers is appreciated. Please
help me in making this package better.
--

		Jan Nijtmans, C.M.G. Arnhem, B.V.
		email: Jan.Nijtmans@wxs.nl (private)
		       Jan.Nijtmans@cmg.nl (work)
		url:   http://home.wxs.nl/~nijtmans/