@(#)README 1.2 11/8/90 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: Faces Project GIF Portable Bitmap (PBM) Sun Rasterfile X11 Bitmap X Pixmap 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 three ways to compile xloadimage, depending on what environment you have. 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. If you have gcc on your system, and it's not gcc 1.37, compile via "make -f Makefile.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, and that gcc 1.37 will not work due to an optimizer bug which causes GIF image loading and colormap reduction to fail. If improper behavior is noticed after compiling with gcc, please try using Makefile.std before reporting a problem. Normal compilations can be done via "make -f Makefile.std". This invokes the standard cc using the -O flag. 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. Try do 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, to Brian Frost (B1F5814@RIGEL.TAMU.EDU) for changes for VMS, to Chip Horstman for G3 FAX support, and to Deron Dann Johnson (dj@eng.sun.com) for fixing the RetainTemporary bug. 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. This derivative of version 1.06 of xloadimage has an additional option to allow slideshows under program control; also included is a program "next_slide" for controlling the advance from one image to the next. Although written by Entropic Research Laboratory, the next_slide program and Entropic's additions to xloadimage are free software; they are NOT covered by ERL's license agreements for ESPS and waves+; and the fees paid to ERL as part of those license agreements do NOT include any payments for this software. The next_slide program and Entropic's additions to xloadimage are covered by the same type of "MIT-style" copyright notice and disclaimer of liability that cover the main body of xloadimage and other contributions thereto. Briefly, you are free to use this software, copy it, and pass it on to other people provided that the relevant notices remain intact. See the source files for the full text of the notices.
