1XLI - X11 Image Loading Utility
2
3WHAT IS IT?
4
5xli is an image display program for X, created by Graeme Gill from Jim
6Frost's xloadimage, and currently maintained by smar@reptiles.org.
7
8xli will view several types of images under X11, or load images onto
9the X11 root window. The current version (1.17) supports:
10
11 CMU Window Manager raster files
12 Faces Project images
13 Fuzzy Bitmap (.fbm) images
14 GEM bit images
15 GIF images (Including GIF89a compatibility)
16 G3 FAX images
17 JFIF style JPEG images
18 McIDAS areafiles
19 MacPaint images
20 Windows, OS/2 BMP Image
21 Monochrome PC Paintbrush (.pcx) images
22 Photograph on CD Image
23 Portable Bitmap (.pbm, .pgm, .ppm) images
24 Portable Network Graphics (PNG) images
25 Sun monochrome rasterfiles
26 Sun color RGB rasterfiles
27 Targa (.tga) files
28 Utah Raster Toolkit (.rle) files
29 X pixmap (.xpm) files (Version 1, 2C and 3)
30 X10 bitmap files
31 X11 bitmap files
32 X Window Dump (except TrueColor and DirectColor)
33
34A variety of options are available to modify images prior to viewing.
35These options include clipping, dithering, depth reduction, zoom (either X
36or Y axis independently or both at once), brightening or darkening, input
37gamma correction, and image merging. When applicable, these options are
38done automatically (eg. a color image to be displayed on a monochrome
39screen will be dithered automatically). A utility (xlito) is provided
40that allows these viewing options to be appended to the image files.
41
42CHANGES FROM XLI 1.16
43
44 Converted source code to ANSI C prototypes.
45
46 Removed MSDOS support (Sorry! Anyone want to add Win32 support?)
47
48 Added PNG file format loader.
49
50 Added support for MIT shared memory extension.
51
52 Rewrote JPEG file format loader to use the IJG library, to take
53 advantage of performance improvements and support progressive
54 scan JPEGs.
55
56 Added the -delete, -iscale, -focus, and -cache options.
57
58 Added interactive image fast scaling with the '<', '>' and '=' keys.
59
60 Added TODO file. Feel free to do anything on the list, or offer
61 your own fixes and enhancements.
62
63HOW IS XLI RELATED TO XLOADIMAGE ?
64
65 xloadimage is maintained by Jim Frost - jimf@saber.com
66
67 xli version 1.00 was based on xloadimage version 3.01.
68
69 xli was maintained by Graeme Gill - graeme@labtam.oz.au, up to
70 version 1.16.
71
72 xli is currently maintained by smar@reptiles.org
73
74 Please read README.xloadimage, which is the original xloadimage
75 README file for xloadimage info and credits.
76
77WHERE CAN I GET IT ?
78
79 http://pantransit.reptiles.org/prog/#xli
80
81COMPILING
82
83 There are a variety of ways to compile xli, depending on what
84 environment you have.
85
86 The easiest way of compiling it is to use the Imakefile. Simply
87 run 'xmkmf' (which should be in your systems /usr/bin/X11 or
88 somewhere equivalent), which should make a Makefile suitable
89 for your system. Type 'make' to then build xli. It can be
90 installed in the standard place (along with its aliases xview
91 and xsetbg) by typing 'make install'. The manual entry can
92 be installed using 'make install.man'.
93
94 The JPEG reader assumes that you have the IJG JPEG library somewhere.
95 You can get it from ftp://ftp.uu.net/graphics/jpeg/.
96
97 The PNG reader assumes you have the PNG group's library and zlib.
98 They're at http://www.cdrom.com/pub/png/pngcode.html, along with a
99 lot of other PNG stuff. You'll need libpng-1.0.5 or later.
100
101 If using the Imakefile is not possible, then you can try using
102 Makefile.std. Choose your target from
103
104 std BSD environment
105 sysv SYSV environment
106 gcc BSD using gcc
107 sysv-gcc SYSV using older gcc
108
109 and use something like:
110
111 make -f Makefile.std target
112
113 There are a few compilation flags that you may need/want to change.
114 This can be done in the Makefile.std file. The defines are:
115
116 -DHAVE_GUNZIP if you want to use gunzip rather than uncompress
117 on .Z files
118
119 -DNO_UNCOMPRESS if you system doesn't have uncompress or gunzip.
120
121SUGGESTIONS AND BUG REPORTS
122
123 xli has been developed in a fairly limited hardware environment, and
124 not all combinations of displays and/or image formats and options have
125 been tested. xli is useful to me, and maybe it will be useful to you.
126
127 Suggestions and bug reports should go to:
128
129 smar@reptiles.org
130
1/* #ident "@(#)x11:contrib/clients/xloadimage/README.orig 1.1 91/12/18 Labtam" */
2
3XLOADIMAGE - X11 Image Loading Utility
4
5WHAT IS IT?
6
7This utility will view several types of images under X11, or load
8images onto the root window. The current version supports:
9
10 CMU Window Manager raster files
11 Faces Project images
12 Fuzzy Bitmap (FBM) images
13 GEM bit images
14 GIF images
15 G3 FAX images
16 McIDAS areafiles
17 MacPaint images
18 PC Paintbrush (PCX) images
19 Portable Bitmap (PBM, PGM, PPM) images
20 Sun monochrome rasterfiles
21 Sun color RGB rasterfiles
22 Utah Raster Toolkit (RLE) files
23 X pixmap files
24 X10 bitmap files
25 X11 bitmap files
26 X Window Dump (except TrueColor and DirectColor)
27
28A variety of options are available to modify images prior to viewing.
29These options include clipping, dithering, depth reduction, zoom
30(either X or Y axis independently or both at once), brightening or
31darkening, and image merging. When applicable, these options are done
32automatically (eg a color image to be displayed on a monochrome screen
33will be dithered automatically).
34
35COMPILING
36
37There are a variety of ways to compile xloadimage, depending on what
38environment you have. The building techniques have changed somewhat
39from versions earlier than 2.0.
40
41If you use gcc you should read this whole section before compiling.
42
43If you are compiling under the X11R4 distribution, the apropriate
44Imakefile is included. I recommend using the standard Makefile as it
45contains a number of different build targets depending on your
46environment.
47
48If you're compiling on a BSD system or a system that's mostly BSDish,
49use "make std" or just "make".
50
51If you're compiling on a System-V system, use "make sysv". If you
52have gcc you may want to use that (read on for caveats) and should use
53"make sysv-gcc" or "make sysv-gcc-1-37" as appropriate.
54
55If you have gcc on your system, and it's not gcc 1.37, compile via
56"make gcc". Gcc should be used if it works because the
57strength-reduction and inline-functions directives dramatically
58improve performance of some operations. Please note that use of gcc
59on some systems, particularly Sun-4, may cause problems.
60
61If you have gcc 1.37 on your system, compile via "make gcc-1-37". Gcc
621.37 has an optimizer bug which causes (at least) GIF image loading to
63fail. This make target adds some extra compilation flags which should
64correct this problem.
65
66If you run into problems with code compiled with gcc, I suggest trying
67the same thing using the standard or System-V target (whichever is
68appropriate) before reporting a bug. Bug fixes are always
69appreciated. PLEASE INCLUDE THE VERSION NUMBER REPORTED BY xloadimage
70-version IN ANY BUG REPORT.
71
72WORKAROUNDS FOR BROKEN SERVERS
73
74Some servers which use odd-depth displays (eg not 1 or a multiple of 8
75bits) do not correctly handle a plane mask with GXcopy. If your
76server displays color images in only two colors although it supports
77more colors, add a -DSERVER_HAS_BROKEN_PLANEMASK to CFLAGS in the
78Makefile. Some Visual X-19 Turbo displays have this problem; you
79should request an updated ROM if you have one of these. Xloadimage
80version 3.0 and later should not exhibit this problem.
81
82Xloadimage version 3.0 and later supports all visual types and will
83attempt to pick the best visual for a given image. Sometimes it may
84pick a bad visual or you pick one that the server says it knows how to
85do but really can't handle. In either case the -visual option can be
86used to force a particular visual.
87
88INSTALLATION
89
90After compiling and installing xloadimage, I recommend linking or
91symlinking to the executable with the names "xview" and "xsetbg". The
92default behavior is slightly different when invoked with these
93commands (they're also easier to type). If you have a public image
94area you should consider setting the SYSPATHFILE option in the
95makefile and setting up a system-wide configuration file. See the man
96page for information on the format of this file.
97
98IMPLEMENTATION
99
100Most functions are not particularly fast, and some functions use
101simple-minded algorithms deliberately over more advanced ones. I
102stressed portability over all and simplicity over performance,
103although many algorithms have become fairly complex over time. I
104believe the result is a usable, portable tool which should serve the
105needs of most users.
106
107The source code is basically in two parts: image manipulation routines
108and everything else. The image manipulation routines should be
109completely independent of X, thus allowing people to use them under
110other graphical systems. No guarantees here, but I tried.
111
112Performance-oriented people will notice that some operations are
113redundant. Xloadimage is designed to work fairly quickly for most
114operations but in some cases I opted for a cleaner internal design
115rather than pure performance.
116
117OWNERSHIP
118
119I used a modified version of the MIT X Consortium copyright with all
120of these functions, thereby allowing full freedom with the code so
121long as the copyright notices remain intact. Free code can be good
122code. All contributions have similar notices.
123
124Commercial sites are welcome to use the code even without asking me,
125although I'm very happy to hear of this stuff going toward real
126products so I appreciate it if anyone who uses some or all of the code
127drops me a line. If you tell me you're using it I'm much more likely
128to keep you informed about new versions as well, so it works out well
129all around.
130
131PRAISE, SUGGESTIONS AND BUG REPORTS
132
133Praise, suggestions, and bug reports should go to:
134
135 Jim Frost
136 Saber Software
137 185 Alewife Brook Parkway
138 Cambridge, MA 02138
139 (617) 924-1985
140 jimf@saber.com
141 ..!uunet!saber!jimf
142
143Please include the version number and sample image data if you are
144reporting a bug.
145
146Functions implementing new image types are welcomed; mail them to the
147same address and I'll do my best to distribute them. Please include a
148small sample image. Try to send them as public domain so I can keep
149the number of differing copyright messages to a minimum -- I'll use my
150standard message and leave the implementor's name and information in
151the file for credit. I wouldn't copyright this stuff at all except
152that it's a requirement for X11 distribution.
153
154If you particularly like xloadimage, feel free to drop me a line. It
155makes me feel good and I get a feel for who does what with it, which
156sometimes influences what parts are worked on.
157
158THANKS
159
160Special thanks to the crew at the Boston University Graphics Lab for
161their assistance and sample images, and to bzs@std.com for his simple
162dithering algorithm (or what's left of it). Real special thanks to
163Kirk L. Johnson (tuna@athena.mit.edu) for a very nice GIF loader and
164dithering routine, to Mark Snitily (zok!mark@apple.com) for 386/ix
165compatibility work, to Andreas Stolcke (stolcke@icsib12.berkeley.edu)
166for miscellaneous bug fixes, to Anthony A. Datri (datri@convex.com)
167for a number of things, to Mark Moraes (moraes@cs.toronto.edu) for
168the slideshow colormap fix, to Gregg Townsend (gmt@cs.arizona.edu) for
169a suggested dithering routine and other fixes, to Brian Frost
170(B1F5814@RIGEL.TAMU.EDU) for changes for VMS, to Chip Horstman for G3
171FAX support, to Deron Dann Johnson (dj@eng.sun.com) for fixing the
172RetainTemporary bug, to Tom Tatlow (tatlow@dash.enet.dec.com) for
173image rotation code, to Mark A. Horstman (mhorstm@sarek.sbc.com) for
174tilde expansion in .xloadimagerc files and virtual-root support in
175root.c, to Tim Roper (timr@labtam.labtam.oz.au), Graeme Gill
176(graeme@labtam.oz.au) for gamma correction and Utah RLE image support,
177Mark Majhor (uunet!sequent!markm) for FBM and MacPaint support, Ian
178MacPhedran (macphed@dvinci.usask.ca) for PGM and PPM support, Per
179Fogelstrom (pf@diab.se) for a fix to send.c, Hans J. Albertsson
180(hans@Sweden.Sun.COM) for cleaning up GIF aborting, Graham Hudspith
181(gwh@inmos.com) for a geometry patch, Glenn P. Davis
182(davis@unidata.ucar.edu) for McIDAS areafile support, Keith S. Pickens
183(maxwell.nde.swri.edu!ksp) for fixing the RLE loader to work with the
184updated zio package, Mike Douglas (douglas@wilbur.coyote.trw.com) for
185normalization, Rod Johnson (johnson@wrl.epi.com) for speedup
186suggestions, Hal Peterson (hrp@cray.com) for his Imakefile fix, Matt
187Caprile (Matthew.Caprile@ec.bull.fr) for slideshow delay code, Bob
188Deroy (rwd@bucrsb.bu.edu) for mondo 24-bit Sun Rasterfile images that
189broke everything, Christos S. Zoulas (christo@ee.cornell.edu) for a
190first-cut 24-bit implementation, Gerald James Barnes
191(gjb@oasis.icl.stc.co.uk) for a first-cut forced-visual
192implementation, Michael Campanella (campanella@cvg.enet.dec.com) for
193more VMS changes, Kee Hinckley (nazgul@alfalfa.com) for robustness
194changes to the g3 and MacPaint loaders and the ZIO package, Tim
195Northrup (tim@brspyr1.brs.com) for PC Paintbrush and GEM image
196formats, Richard Weidner (richard@elroy.jpl.nasa.gov) for lots of
19724-bit testing, and any others whose names I've missed.
198
199HISTORY
200
201Patch 01 contained a new Makefile.std, Makefile.gcc, and Imakefile.
202It contained a bug-fix to sendImageToX() which allowed bitmaps to be
203sent from little-endian machines (eg VAX, 80386) correctly, and a fix
204to xbitmapLoad() to allow correct loading of X10 bitmap images. An
205enhancement to imageInWindow() which allowed exiting from image
206windows by typing 'q' was submitted by Chris Tengi
207(tengi@idunno.princeton.edu) and was included. The previously missing
208file 'patchlevel' was included.
209
210Patch 02 contained modifications to the Makefiles, support for the X
211Pixmap image type, a different dithering algorithm that didn't blow
212the image up (with the old one moved to halftone.c), and a bug fix to
213zoom.c to correct problems when zooming bitmaps.
214
215Patch 03 contained a new loader for GIF files. The dither bits array
216in dither.c was changed so it worked properly, and both dither.c and
217halftone.c had minor bugs fixed. Merge.c was modified to correct bugs
218when merging RGB images. Pbm.c was modified to handle raw format
219images. Root.c was modified to deny image loads which would change
220the root window's colormap. Send.c was modified to use shared colors
221whenever possible and to handle color displays which have depths which
222are not a multiple of 8. Window.c was modified to avoid deleting the
223default colormap, allowing proper operation on some servers prior to
224X11R3 patchlevel 08. There were many miscellaneous bug fixes.
225
226Patchlevel 04 contained an enhancement to root.c to use
227RetainTemporary and KillClient(disp, AllTemporary) so that it could
228clean up after itself when reloading. The -quiet and -zoom options no
229longer cause garbage to be displayed for the image title. A small bug
230in new.c that caused incorrect allocation of bitmap images was fixed.
231Several calls to XCreateColormap were missing the "visual" parameter
232in send.c; this was fixed. A bug relating to -border and monochrome
233displays was fixed. There were several changes to the Imakefile and
234Makefiles.
235
236Patchlevel 05 contained enhancements to allow slideshows and
237fullscreen viewing, some bug fixes related to scrolling around within
238images, Saber-C makefile enhancements, a bug fix to the halftoning
239title, and the addition of greyscale Sun Rasterfile support.
240
241Patchlevel 06 contained support for G3 FAX images, bug fixes to
242merge.c to fix some signed/unsigned errors and clipping problems,
243changes to root.c to make previously allocated resources be freed
244properly, and a completely new dithering routine.
245
246Version 2, patchlevel 00 contained support for MacPaint, FBM, PGM,
247PPM, CMU, Utah RLE and XWD image formats, gamma equalization, image
248smoothing, and image rotation. G3 FAX support was modified to cut
249down on false positive identifications. The zio subsystem was
250modified to cache reads for performance improvements and to allow
251stdin to be used as an input source. Several loader functions which
252did not properly close their files were fixed. Color slideshows now
253work. Icon titles use an abbreviated titlebar title to enhance
254readability. The resource class name was changed from XLoadImage to
255xloadimage to be more predictable. Several options now propagate to
256all images following them if the -slideshow option is specified.
257
258Version 2.01 contained several fixes to window.c to work around a bug
259in twm/tvtwm which could crash servers. The resource class name was
260changed (again) to Xloadimage to conform with standard class naming
261practices. Several problems with System-V compilation were corrected.
262The gcc-1-37 make target was fixed to prevent a double-define. The
263GIF loader was patched to respond better to short GIF files. The Utah
264RLE image loader was patched to work with the updated ZIO package.
265
266Version 2.02 added the options -default, -gray, -normalize, and
267-private. The memToVal routines were macro-ized for substantial speed
268increases. The atom used for deleting previously allocated colors for
269the -onroot option was changed to correspond to that used by xsetroot.
270Dithering and halftoning were changed to use a lookup table for
271intensities to speed them up somewhat. Rle.h was changed to use
272memToValLSB() instead of its own byte-swapping algorithm for
273portability. Window.c was modified to eliminate the initial paint,
274moving it instead to within ConfigureNotify. A fix was made to xwd.c
275to fix its colormap loader for out-of-order colormaps. The G3 FAX
276identification function was fixed and the G3 loader moved to prior to
277the MacPaint loader so that both can be used. A bug in send.c where
278color images using the default colormap would not appear correctly if
279the display depth was not a multiple of 8 was corrected. The default
280gamma value used in rle.c was changed from 2 to 1. There were
281miscellaneous portability changes.
282
283Version 2.03 added -delay. Many minor programming errors were cleaned
284up. Hash.c was changed to use image.h instead of local typedefs
285(fixing a problem with PPM image loading). Window.c was changed to
286fix a problem with override redirect windows in fullscreen mode,
287and refresh problems with some servers in slideshow mode were fixed.
288Path.c was modified to ignore directories when searching for files.
289Send.c was modified to allow TrueColor and DirectColor visuals.
290
291Version 2.03-JPL contained interim code to handle 24-bit TrueColor and
292DirectColor displays pending the release of Version 3.0.
293
294Version 3.0 added full support for all server types. Internal support
295for 24-bit images was implemented (including the improvement of Sun
296Rasterfile and PPM support to use the 24-bit format internally). Many
297modifications to image processing routines to support or make use of
29824-bit images. A much-improved colormap reduction algorithm replaced
299the primitive one in previous versions. The window display code was
300modified to work with the best possible visual. The window display
301code was modified to use backing store when available (and -pixmap was
302added to force the old technique). The -fit option was added to force
303an image to be fit into the default colormap if it didn't fit as
304supplied. The -fork option was added to allow automatic
305backgrounding. The -onroot -fullscreen options were modified to
306preserve aspect ratio. The -windowid option was added to allow the
307setting of the background pixmap of any window. The -onroot code was
308modified to work with DECWINDOWS servers. The -normalize option was
309improved for color images. The -slideshow option was removed (and
310made the default behavior) and -merge was added to allow more flexible
311image merging. The WM_DELETE protocol is now recognized. PC
312Paintbrush (PCX) and GEM bitmap image formats are now supported. The
313GIF 89a signature is now recognized (although no support for its
314additional capabilities has been implemented).
315
316Version 3.01 corrected color problems when merging RGB files and fixed
317a few small problems.
318