XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
NAME
xloadimage, xsetbg - load images into an X11 window or onto the root
window
SYNOPSIS
xloadimage [global_options] {[image_options] image ...}
xloadimage [global_options] [image_options] stdin < image
DESCRIPTION
Xloadimage displays images in an X11 window or loads them onto the root
window. See the IMAGE TYPES section below for supported image types.
If the filename stdin is given, xloadimage will read the image from
standard input.
If the destination display cannot support the number of colors in the
image, the image will be dithered (monochrome destination) or have its
colormap reduced (color destination) as appropriate. This can also be
done forcibly with the -halftone, -dither, and -colors options.
A variety of image manipulations can be specified, including gamma
correction, brightening, clipping, dithering, depth-reduction, rotation,
and zooming. Most of these manipulations have simple implementations;
speed was opted for above accuracy.
If you are viewing a large image in a window, the initial window will be
at most 90% of the size of the display unless the window manager does not
correctly handle window size requests or if you've used the -fullscreen
option. You may move the image around in the window by dragging with the
first mouse button. The cursor will indicate which directions you may
drag, if any. You may exit the window by typing 'q' or '^C' when the
keyboard focus is on the window.
It's possible to have a "slideshow" of many images by specifying the
-slideshow option.
A wide variety of common image manipulations can be done by mixing and
matching the available options. See the section entitled HINTS FOR GOOD
IMAGE DISPLAYS for some ideas.
Xsetbg is equivalent to xloadimage -onroot -quiet and
RESOURCE CLASS
Xloadimage uses the resource class name Xloadimage for window managers
which need this resource set. This name changed in version 2.00 and
2.01; some previous versions used the name XLoadImage (which was
difficult to predict) or xloadimage (which conflicted with class naming
conventions).
GLOBAL OPTIONS
The following options affect the global operation of xloadimage. They
may be specified anywhere on the command line.
10/89 Page 1
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
-border color
This sets the background portion of the window which is not
covered by any images to be color.
-default
Set the root background to the default root weave. This is the
same as xsetroot with no arguments.
-debug Talk to the X server in synchronous mode. This is useful for
debugging. If an X error is seen while in this mode, a core will
be dumped.
-delay secs
Automatically advance to the next image after secs seconds.
-display display_name
X11 display name to send the image(s) to.
-fit Force image to use the default visual and colormap. This is
useful if you do not want technicolor effects when the colormap
focus is inside the image window, but it may reduce the quality
of the displayed image. This is on by default if -onroot or
-windowid is specified.
-fork Fork xloadimage. This causes xloadimage to disassociate itself
from the shell. This option automatically turns on -quiet.
-fullscreen
Use the entire screen to display images. If combined with
-onroot, the image will be zoomed to fill the entire rootwindow.
-geometry WxH[{+-X}{+-}Y]
This sets the size of the window onto which the images are loaded
to a different value than the size of the image. When viewing an
image in a window, this can be used to reduce the size of the
destination window. When loading an image onto the root window,
this option controls the size of the pixmap which will be loaded
onto the root. If the size is smaller than that of the display,
the image will be replicated.
-goto image_name
Forces the next image to be displayed to be the image named
image_name. This is useful for generating looped slideshows. If
more than one image of the same name as the target exists on the
argument list, the first in the argument list is used.
-help [option ...]
Give information on an option or list of options. If no option
is given, a simple interactive help facility is invoked.
Page 2 10/89
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
-identify
Identify the supplied images rather than display them.
-install
Forcibly install the image's colormap when the window is focused.
This violates ICCCM standards and only exists to allow operation
with naive window managers. Use this option only if your window
manager does not install colormaps properly.
-list List the images which are along the image path.
-onroot Load image(s) onto the root window instead of viewing in a
window. This option automatically sets the -fit option. This is
the opposite of -view. XSetbg has this option set by default.
-path Displays the image path and image suffixes which will be used
when looking for images. These are loaded from ~/.xloadimagerc
and optionally from a systemwide file (normally
/usr/lib/xloadimagerc).
-pixmap Force the use of a pixmap as backing-store. This is provided for
servers where backing-store is broken (such as some versions of
the AIXWindows server). It may improve scrolling performance on
servers which provide backing-store.
-private
Force the use of a private colormap. Normally colors are
allocated shared unless there are not enough colors available.
-quiet Forces xloadimage to be quiet. This is the default for xsetbg,
but the others like to whistle.
-supported
List the supported image types.
-verbose
Causes xloadimage to be talkative, telling you what kind of image
it's playing with and any special processing that it has to do.
This is the default for xloadimage.
-version
Print the version number and patchlevel of this version of
xloadimage.
-view View image(s) in a window. This is the opposite of -onroot and
the default for xloadimage.
-visual visual_name
Force the use of a specific visual type to display an image.
Normally xloadimage tries to pick the best available image for a
particular image type. The available visual types are:
DirectColor, TrueColor, PseudoColor, StaticColor, GrayScale, and
10/89 Page 3
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
StaticGray. Nonconflicting names may be abbreviated and case is
ignored.
-windowid hex_window_id
Sets the background pixmap of a particular window ID. The
argument must be in hexadecimal and must be preceeded by "0x" (eg
-windowid 0x40000b. This is intended for setting the background
pixmap of some servers which use untagged virtual roots (eg HP-
VUE), but can have other interesting applications.
IMAGE OPTIONS
The following options may preceed each image. These options are local to
the image they preceed.
-at X,Y
Indicates coordinates to load the image at on the base image. If
this is an option to the first image, and the -onroot option is
specified, the image will be loaded at the given location on the
display background.
-background color
Use color as the background color instead of the default (usually
white but this depends on the image type) if you are transferring a
monochrome image to a color display.
-brighten percentage
Specify a percentage multiplier for a color image's colormap. A
value of more than 100 will brighten an image, one of less than 100
will darken it.
-center
Center the image on the base image loaded. If this is an option to
the first image, and the -onroot option is specified, the image
will be centered on the display background.
-clip X,Y,W,H
Clip the image before loading it. X and Y define the upper-left
corner of the clip area, and W and H define the extents of the
area. A zero value for W or H will be interpreted as the remainder
of the image.
-colors n
Specify the maximum number of colors to use in the image. This is
a way to forcibly reduce the depth of an image.
-dither
Dither a color image to monochrome using a Floyd-Steinberg
dithering algorithm. This happens by default when viewing color
images on a monochrome display. This is slower than -halftone and
affects the image accuracy but usually looks much better.
Page 4 10/89
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
-foreground color
Use color as the foreground color instead of black if you are
transferring a monochrome image to a color display. This can also
be used to invert the foreground and background colors of a
monochrome image.
-gamma display_gamma
Specify the gamma correction for the display. The default value is
1.0, a typical display needs 2.0 to 2.5.
-gray Convert an image to grayscale. This is very useful when displaying
colorful images on servers with limited color capability. The
optional spelling -grey may also be used.
-halftone
Force halftone dithering of a color image when displaying on a
monochrome display. This option is ignored on monochrome images.
This dithering algorithm blows an image up by sixteen times; if you
don't like this, the -dither option will not blow the image up but
will take longer to process and will be less accurate.
-idelay secs
Set the delay to be used for this image to secs seconds (see
-delay). If -delay was specified, this overrides it. If it was
not specified, this sets the automatic advance delay for this image
while others will wait for the user to advance them.
-invert
Inverts a monochrome image. This is shorthand for -foreground
white -background black.
-merge
Merge this image onto the base image after local processing. The
base image is considered to be the first image specified or the
last image that was not preceeded by -merge. If used in
conjunction with -at and -clip, very complex images can be built
up. This option is on by default for all images if the -onroot or
-windowid options are specified.
-name image_name
Force the next argument to be treated as an image name. This is
useful if the name of the image is -dither, for instance.
-newoptions
Reset options that propagate. The -bright, -colors, -delay,
-dither, -gamma, -normalize, -smooth, -xzoom, -yzoom, and -zoom
options normally propagate to all following images.
-normalize
Normalize a color image.
10/89 Page 5
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
-rotate degrees
Rotate the image by degrees clockwise. The number must be a
multiple of 90.
-smooth
Smooth a color image. This reduces blockiness after zooming an
image up. If used on a monochrome image, nothing happens. This
option can take awhile to perform, especially on large images. You
may specify more than one -smooth option per image, causing
multiple iterations of the smoothing algorithm.
-xzoom percentage
Zoom the X axis of an image by percentage. A number greater than
100 will expand the image, one smaller will compress it. A zero
value will be ignored. This option, and the related -yzoom are
useful for correcting the aspect ratio of images to be displayed.
-yzoom percentage
Zoom the Y axis of an image by percentage. See -xzoom for more
information.
-zoom percentage
Zoom both the X and Y axes by percentage. See -xzoom for more
information. Technically the percentage actually zoomed is the
square of the number supplied since the zoom is to both axes, but I
opted for consistency instead of accuracy.
EXAMPLES
To load the rasterfile "my.image" onto the background and replicate it to
fill the entire background:
xloadimage -onroot my.image
To load a monochrome image "my.image" onto the background, using red as
the foreground color, replicate the image, and overlay "another.image"
onto it at coordinate (10,10):
xloadimage -foreground red my.image -at 10,10 another.image
To center the rectangular region from 10 to 110 along the X axis and from
10 to the height of the image along the Y axis:
xloadimage -center -clip 10,10,100,0 my.image
To double the size of an image:
xloadimage -zoom 200 my.image
To halve the size of an image:
xloadimage -zoom 50 my.image
Page 6 10/89
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
To brighten a dark image:
xloadimage -brighten 150 my.image
To darken a bright image:
xloadimage -brighten 50 my.image
HINTS FOR GOOD IMAGE DISPLAYS
Since images are likely to come from a variety of sources, they may be in
a variety of aspect ratios which may not be supported by your display.
The -xzoom and -yzoom options can be used to change the aspect ratio of
an image before display. If you use these options, it is recommended
that you increase the size of one of the dimensions instead of shrinking
the other, since shrinking looses detail. For instance, many GIF and G3
FAX images have an X:Y ratio of about 2:1. You can correct this for
viewing on a 1:1 display with either -xzoom 50 or -yzoom 200 (reduce X
axis to 50% of its size and expand Y axis to 200% of its size,
respectively) but the latter should be used so no detail is lost in the
conversion.
When zooming color images up you can reduce blockiness with -smooth. For
zooms of 300% or more, I recommend two smoothing passes (although this
can take awhile to do on slow machines). There will be a noticable
improvement in the image.
You can perform image processing on a small portion of an image by
loading the image more than once and using the -merge, -at and -clip
options. Load the image, then merge it with a clipped, processed version
of itself. To brighten a 100x100 rectangular portion of an image located
at (50,50), for instance, you could type:
xloadimage my.image -merge -at 50,50 -clip 50,50,100,100 -brighten
150 my.image
If you're using a display with a small colormap to display colorful
images, try using the -gray option to convert to grayscale.
PATHS AND EXTENSIONS
The file ~/.xloadimagerc (and optionally a system-wide file) defines the
path and default extensions that xloadimage will use when looking for
images. This file can have two statements: "path=" and "extension=" (the
equals signs must follow the word with no spaces between). Everything
following the "path=" keyword will be prepended to the supplied image
name if the supplied name does not specify an existing file. The paths
will be searched in the order they are specified. Everything following
the "extension=" keyword will be appended to the supplied image name if
the supplied name does not specify an existing file. As with paths,
these extensions will be searched in the order they are given. Comments
are any portion of a line following a hash-mark (#).
10/89 Page 7
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
The following is a sample ~/.xloadimagerc file:
# paths to look for images in
path= /usr/local/images
/home/usr1/guest/madd/images
/usr/include/X11/bitmaps
# default extensions for images; .Z is automatic; scanned in order
extension= .csun .msun .sun .face .xbm .bm
Versions of xloadimage prior to version 01, patchlevel 03 would load the
system-wide file (if any), followed by the user's file. This behavior
made it difficult for the user to configure her environment if she didn't
want the default. Newer versions will ignore the system-wide file if a
personal configuration file exists.
IMAGE TYPES
Xloadimage currently supports the following image types:
CMU Window Manager raster files
Faces Project images
Fuzzy Bitmap (FBM) images
GEM bit images
GIF images
G3 FAX images
McIDAS areafiles
MacPaint images
PC Paintbrush (PCX) images
Portable Bitmap (PBM, PGM, PPM) images
Sun monochrome rasterfiles
Sun color RGB rasterfiles
Utah Raster Toolkit (RLE) files
X pixmap files
X10 bitmap files
X11 bitmap files
X Window Dump (except TrueColor and DirectColor)
Normal, compact, and raw PBM images are supported. Both standard and
run-length encoded Sun rasterfiles are supported. Any image whose name
ends in .Z is assumed to be a compressed image and will be filtered
through "uncompress".
AUTHOR
Jim Frost
Saber Software
jimf@saber.com
For a more-or-less complete list of other contributors (there are a lot
of them), please see the README file enclosed with the distribution.
Page 8 10/89
XLOADIMAGE(1) UNIX System V(8 May 1991) XLOADIMAGE(1)
FILES
xloadimage - the image loader and viewer
xsetbg - pseudonym which quietly sets the background
/usr/lib/X11/Xloadimage - default system-wide configuration file
~/.xloadimagerc - user's personal configuration file
COPYRIGHT
Copyright (c) 1989, 1990 Jim Frost and others.
Xloadimage is copywritten material with a very loose copyright allowing
unlimited modification and distribution if the copyright notices are left
intact. Various portions are copywritten by various people, but all use
a modification of the MIT copyright notice. Please check the source for
complete copyright information. The intent is to keep the source free,
not to stifle its distribution, so please write to me if you have any
questions.
BUGS
Zooming dithered images, especially downwards, is UGLY.
Images can come in a variety of aspect ratios. Xloadimage cannot detect
what aspect ratio the particular image being loaded has, nor the aspect
ratio of the destination display, so images with differing aspect ratios
from the destination display will appear distorted. See HINTS FOR GOOD
IMAGE DISPLAYS for more information.
The GIF format allows more than one image to be stored in a single GIF
file, but xloadimage will only display the first.
Only GIF87a format is supported.
Some window managers do not correctly handle window size requests. In
particular, many versions of the twm window manager use the MaxSize hint
instead of the PSize hint, causing images which are larger than the
screen to display in a window larger than the screen, something which is
normally avoided. Some versions of twm also ignore the MaxSize
argument's real function, to limit the maximum size of the window, and
allow the window to be resized larger than the image. If this happens,
xloadimage merely places the image in the upper-left corner of the window
and uses the zero-value'ed pixel for any space which is not covered by
the image. This behavior is less-than-graceful but so are window
managers which are cruel enough to ignore such details.
The order in which operations are performed on an image is independent of
the order in which they were specified on the command line. Wherever
possible I tried to order operations in such a way as to look the best
possible (zooming before dithering, for instance) or to increase speed
(zooming downward before compressing, for instance).
10/89 Page 9