XLOADIMAGE - X11 Image Loading Utility

WHAT IS IT?

This utility will view several types of images under X11, or load
images onto the root window.  The current version supports:

	CMU Window Manager raster files
	Faces Project images
	Fuzzy Bitmap (FBM) images
	GIF images
	G3 FAX images
	McIDAS areafiles
	MacPaint images
	Portable Bitmap (PBM) images
	Sun monochrome rasterfiles
	Sun color RGB rasterfiles
	X pixmap files
	X10 bitmap files
	X11 bitmap files
	Utah Raster Toolkit (RLE) files

A variety of options are available to modify images prior to viewing.
These options include clipping, dithering, depth reduction, zoom
(either X or Y axis independently or both at once), brightening or
darkening, and image merging.  When applicable, these options are done
automatically (eg a color image to be displayed on a monochrome screen
will be dithered automatically).

COMPILING

There are a variety of ways to compile xloadimage, depending on what
environment you have.  The building techniques have changed somewhat
from versions earlier than 2.0.

If you are compiling under the X11R4 distribution, the apropriate
Imakefile is included and you should compile as with any other client.
I haven't personally tested this, but if it's broken it'll be easy to
fix.  Since imake trashes the standard Makefile, a backup copy is kept
in Makefile.std.

If you're compiling on a BSD system or a system that's mostly BSDish,
use "make std" or just "make".  If you have gcc you should keep
reading.

If you're compiling on a System-V system, use "make sysv".  If you
have gcc you may want to use that (read on for caveats) and should use
"make sysv-gcc" or "make sysv-gcc-1-37" as appropriate.

If you have gcc on your system, and it's not gcc 1.37, compile via
"make gcc".  This is changed from earlier versions which had a
separate Makefile for gcc.  Gcc should be used if it works because the
strength-reduction and inline-functions directives dramatically
improve performance of some operations.  Please note that use of gcc
on some systems, particularly Sun-4, may cause problems.

If you have gcc 1.37 on your system, compile via "make gcc-1-37".  Gcc
1.37 has an optimizer bug which causes (at least) GIF image loading
and colormap reduction to fail.  This make target adds some extra
compilation flags which should correct this problem.

If you run into problems with code compiled with gcc, I suggest trying
the same thing using the standard or System-V target (whichever is
appropriate) before reporting a bug.  Bug fixes are always appreciated.

WORKAROUNDS FOR BROKEN SERVERS

Some servers which use odd-depth displays (eg not 1 or a multiple of 8
bits) do not correctly handle a plane mask with GXcopy.  If your
server displays color images in only two colors although it supports
more colors, add a -DSERVER_HAS_BROKEN_PLANEMASK to CFLAGS in the
Makefile.  Some Visual X-19 Turbo displays have this problem; you
should request an updated ROM if you have one of these.

INSTALLATION

After compiling and installing xloadimage, I recommend linking or
symlinking to the executable with the names "xview" and "xsetbg".  The
default behavior is slightly different when invoked with these
commands (they're also easier to type).  If you have a public image
area you should consider setting the SYSPATHFILE option in the
makefile and setting up a system-wide configuration file.  See the man
page for information on the format of this file.

IMPLEMENTATION

Most functions are not particularly fast, and some functions use
simple-minded algorithms deliberately over more advanced ones.  I
stressed portability over all and simplicity over performance.  I
believe the result is a usable, portable tool which should serve the
needs of most users.

The source code is basically in two parts: image manipulation routines
and everything else.  The image manipulation routines should be
completely independent of X, thus allowing people to use them under
other graphical systems.  No guarantees here, but I tried.

Performance-oriented people will notice that when loading a color
image, the colormap of the image is minimized (and all pixel values in
the image changed), then the colormap is redone (and all pixel values
in the image changed again) before sending to X.  This could be
reduced to only one remapping of the image but I wanted to keep the
image from X's grubby (greedy?) hands as long as possible, and the
image merging function really wants the image to have a minimized
colormap.

OWNERSHIP

I used a modified version of the MIT X Consortium copyright with all
of these functions, thereby allowing full freedom with the code so
long as the copyright notices remain intact.  Free code can be good
code.  All contributions have similar notices.

SUGGESTIONS AND BUG REPORTS

Suggestions and bug reports should go to:

	Jim Frost
	jimf@saber.com
	..harvard!saber!jimf

Please include the version number and sample image data if you are
reporting a bug.

Functions implementing new image types are welcomed; mail them to the
same address and I'll do my best to distribute them.  Please include a
small sample image.  Try to send them as public domain so I can keep
the number of differing copyright messages to a minimum -- I'll use my
standard message and leave the implementor's name and information in
the file for credit.  I wouldn't copyright this stuff at all except
that it's a requirement for X11 distribution.

THANKS

Special thanks to the crew at the Boston University Graphics Lab for
their assistance and sample images, and to bzs@std.com for his simple
dithering algorithm (or what's left of it).  Real special thanks to
Kirk L. Johnson (tuna@athena.mit.edu) for a very nice GIF loader and
dithering routine, to Mark Snitily (zok!mark@apple.com) for 386/ix
compatibility work, to Andreas Stolcke (stolcke@icsib12.berkeley.edu)
for miscellaneous bug fixes, to Anthony A. Datri (datri@convex.com)
for adding the class hint, to Mark Moraes (moraes@cs.toronto.edu) for
the slideshow colormap fix, to Gregg Townsend (gmt@cs.arizona.edu) for
a suggested dithering routine and other fixes, to Brian Frost
(B1F5814@RIGEL.TAMU.EDU) for changes for VMS, to Chip Horstman for G3
FAX support, to Deron Dann Johnson (dj@eng.sun.com) for fixing the
RetainTemporary bug, to Tom Tatlow (tatlow@dash.enet.dec.com) for
image rotation code, to Mark A. Horstman (mhorstm@sarek.sbc.com) for
tilde expansion in .xloadimagerc files and virtual-root support in
root.c, to Tim Roper (timr@labtam.labtam.oz.au), Graeme Gill
(graeme@labtam.oz.au) for gamma correction and Utah RLE image support,
Mark Majhor (uunet!sequent!markm) for FBM and MacPaint support, Ian
MacPhedran (macphed@dvinci.usask.ca) for PGM and PPM support, Per
Fogelstrom (pf@diab.se) for a fix to send.c, Hans J. Albertsson
(hans@Sweden.Sun.COM) for cleaning up GIF aborting, Graham Hudspith
(gwh@inmos.com) for a geometry patch, Glenn P. Davis
(davis@unidata.ucar.edu) for McIDAS areafile support, Keith S. Pickens
(maxwell.nde.swri.edu!ksp) for fixing the RLE loader to work with the
updated zio package, Mike Douglas (douglas@wilbur.coyote.trw.com) for
normalization, Rod Johnson (johnson@wrl.epi.com) for speedup
suggestions, and any others whose names I've missed.

HISTORY

Patch 01 contained a new Makefile.std, Makefile.gcc, and Imakefile.
It contained a bug-fix to sendImageToX() which allowed bitmaps to be
sent from little-endian machines (eg VAX, 80386) correctly, and a fix
to xbitmapLoad() to allow correct loading of X10 bitmap images.  An
enhancement to imageInWindow() which allowed exiting from image
windows by typing 'q' was submitted by Chris Tengi
(tengi@idunno.princeton.edu) and was included.  The previously missing
file 'patchlevel' was included.

Patch 02 contained modifications to the Makefiles, support for the X
Pixmap image type, a different dithering algorithm that didn't blow
the image up (with the old one moved to halftone.c), and a bug fix to
zoom.c to correct problems when zooming bitmaps.

Patch 03 contained a new loader for GIF files.  The dither bits array
in dither.c was changed so it worked properly, and both dither.c and
halftone.c had minor bugs fixed.  Merge.c was modified to correct bugs
when merging RGB images.  Pbm.c was modified to handle raw format
images.  Root.c was modified to deny image loads which would change
the root window's colormap.  Send.c was modified to use shared colors
whenever possible and to handle color displays which have depths which
are not a multiple of 8.  Window.c was modified to avoid deleting the
default colormap, allowing proper operation on some servers prior to
X11R3 patchlevel 08.  There were many miscellaneous bug fixes.

Patchlevel 04 contained an enhancement to root.c to use
RetainTemporary and KillClient(disp, AllTemporary) so that it could
clean up after itself when reloading.  The -quiet and -zoom options no
longer cause garbage to be displayed for the image title.  A small bug
in new.c that caused incorrect allocation of bitmap images was fixed.
Several calls to XCreateColormap were missing the "visual" parameter
in send.c; this was fixed.  A bug relating to -border and monochrome
displays was fixed.  There were several changes to the Imakefile and
Makefiles.

Patchlevel 05 contained enhancements to allow slideshows and
fullscreen viewing, some bug fixes related to scrolling around within
images, Saber-C makefile enhancements, a bug fix to the halftoning
title, and the addition of greyscale Sun Rasterfile support.

Patchlevel 06 contained support for G3 FAX images, bug fixes to
merge.c to fix some signed/unsigned errors and clipping problems,
changes to root.c to make previously allocated resources be freed
properly, and a completely new dithering routine.

Version 2, patchlevel 00 contained support for MacPaint, FBM, PGM,
PPM, CMU, Utah RLE and XWD image formats, gamma equalization, image
smoothing, and image rotation.  G3 FAX support was modified to cut
down on false positive identifications.  The zio subsystem was
modified to cache reads for performance improvements and to allow
stdin to be used as an input source.  Several loader functions which
did not properly close their files were fixed.  Color slideshows now
work.  Icon titles use an abbreviated titlebar title to enhance
readability.  The resource class name was changed from XLoadImage to
xloadimage to be more predictable.  Several options now propagate to
all images following them if the -slideshow option is specified.

Version 2.01 contained several fixes to window.c to work around a bug
in twm/tvtwm which could crash servers.  The resource class name was
changed (again) to Xloadimage to conform with standard class naming
practices.  Several problems with System-V compilation were corrected.
The gcc-1-37 make target was fixed to prevent a double-define.  The
GIF loader was patched to respond better to short GIF files.  The Utah
RLE image loader was patched to work with the updated ZIO package.

Version 2.02 added the options -default, -gray, -normalize, and
-private.  The memToVal routines were macro-ized for substantial speed
increases.  The atom used for deleting previously allocated colors for
the -onroot option was changed to correspond to that used by xsetroot.
Dithering and halftoning were changed to use a lookup table for
intensities to speed them up somewhat.  Rle.h was changed to use
memToValLSB() instead of its own byte-swapping algorithm for
portability.  Window.c was modified to eliminate the initial paint,
moving it instead to within ConfigureNotify.  A fix was made to xwd.c
to fix its colormap loader for out-of-order colormaps.  The G3 FAX
identification function was fixed and the G3 loader moved to prior to
the MacPaint loader so that both can be used.  A bug in send.c where
color images using the default colormap would not appear correctly if
the display depth was not a multiple of 8 was corrected.  The default
gamma value used in rle.c was changed from 2 to 1.  There were
miscellaneous portability changes.
