
		Tcl Image formats (Img)
		(Version 1.1p3 / may 11 1998)

		Jan Nijtmans

This file contains a collection of format handlers for Tk.
It can be used in combination with Tk4.1 or later (tested
up to Tk8.1a2). Also supported are Itcl 2.1 and Itcl 2.2.

Included in this distribution are the most recent versions
(as of may '98) of the libz, libpng, libjpeg and libtiff
libraries. These are not required for compilation of libimg,
only if you need support for the PNG, JPEG or TIFF 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. This scripts is tested on UNIX and Windows.
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.

Configuration of libtiff and libjpeg will be done automatically.

PATCH

In the patches subdirectory, patch files "patch.tk4" and
"patch.tk8" and a source file "tkphoto4.c" is present.
Either copy one of the patch file to the Tk distribution and
type "patch <patch.tk?", or rename "tkphoto4.c" to "tkImgPhoto.c"
and copy it into the "generic" directory of Tk4.1 or Tk4.2.
For Tk8.0(p1) there are more files that need to be replaced.
If you cannot use "patch.tk8", you can download "patchtk8.tgz"
or "patchtk8.zip" from the same place where you found Img1.1.
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.
  - In "patch.tk8" additional fixes, as suggested by Steve Ball,
    are implemented. This 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.1.so will be built. Further on:

	make		build libimg1.1.so only
	make z		build libz.so
	make png	build libpng.so
	make jpeg	build libjpeg.so
	make tiff	build libtiff.so
	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.1.so only
	make install-z		install libz.so.1.1.2
	make install-png	install libpng.so.2.1.0
	make install-jpeg	install libjpeg.so.6.0.1
	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.

If you use Tk 4.1, make sure that the environment variable
TCLLIBPATH contains the directory where your pkgIndex.tcl
and libimg1.1.so files are. For Tk 4.2 and higher this is
not necessary any more.

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>"
  "png"
  "jpeg -fast -grayscale"
  "tiff"
  "xbm"
  "xpm"
  "postscript -index <n> -zoom <x> <y>"		(-index not yet implemented)

Valid format specifiers for writing photo's:
  "bmp"
  "gif"
  "png Author <name> Title <title> Description ....."
  	Each pair of arguments will add a named text chunk to the file.
  "jpeg -quality <n> -smooth <n> -grayscale -optimize -progressive"
  "tiff -compression <compression>"
  "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.
	-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
	-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 2.7.2.1)
		IRIX 6.2	(cc, 32 bits only)
		ULTRIX 4.1	(both cc and gcc)
		ULTRIX 4.4	(cc 3.0)
		HP-UX-9		(both cc and gcc 2.7.0)
		HP-UX-10.2	(gcc 2.7.2)
		SunOS-4.1.2     (cc)
		Solaris 2.5	(gcc 2.7.2 only)
		FreeBSD	2.2	(gcc)
		Windows	95/NT	(MS Visual C++ 5.0, Windows 95/NT3.51/NT4.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.

THANKS

Many thanks to Andreas Kupries <a.kupries@westend.com> for all his
feedback and the Windows port.

		Jan Nijtmans
		CMG (Computer Management Group) Arnhem
		email: Jan.Nijtmans@wxs.nl (private)
		       Jan.Nijtmans@cmg.nl (work)
		url:   http://home.wxs.nl/~nijtmans/
