xloadimage.1

speech signal process tools

.\" @(#)xloadimage.1	1.2	11/8/90
.TH XLOADIMAGE 1 "7 November 1990"
.SH NAME
xloadimage, xsetbg, xview \- load images into an X11 window or onto
the root window
.SH SYNOPSIS
\fIxloadimage\fR [global_options] {[image_options] image ...}
.SH DESCRIPTION
\fIXloadimage\fR displays images in an X11 window or loads them onto
the root window.  See the \fIIMAGE TYPES\fR section below for
supported image types.
.PP
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 \fI-halftone\fR and \fI-colors\fR options.
.PP
If more than one image is to be loaded, they will be merged into a
single image.  The \fI-at\fR and \fI-center\fR options control where
subsequent images will be loaded onto the initial image.  Any
combination of color image depths and/or monochrome images may be
loaded at one time.  If merging two color images would overload the
number of available colormap entries, the number of colors shared
between the images will be automatically reduced to fit.
.PP
A variety of image manipulations can be specified, including
brightening, clipping, dithering, depth-reduction, and zooming.  Most
of these manipulations have simple implementations; speed was opted
for above accuracy.
.PP
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
\fI-fullscreen\fR 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.
.PP
It's possible to have a "slideshow" of many images by specifying the
\fI-slideshow\fR or \fI-prog_slideshow\fP option.
.PP
A wide variety of common image manipulations can be done by mixing and
matching the available options.  See the section entitled \fIHINTS FOR
GOOD IMAGE DISPLAYS\fR for some ideas.
.PP
\fIXsetbg\fR is equivalent to \fIxloadimage -onroot -quiet\fR and
\fIxview\fR is equivalent to \fIxloadimage -view -verbose\fR.
.SH GLOBAL OPTIONS
The following options affect the global operation of \fIxloadimage\fR.
They may be specified anywhere on the command line.
.TP 8
-border \fIcolor\fR
This sets the background portion of the window which is not covered by
any images to be \fIcolor\fR.
.TP
-display \fIdisplay_name\fR
X11 display name to send the image(s) to.
.TP
-fullscreen
Use the entire screen to display images.  This option is incompatible
with -onroot.
.TP
-geometry \fIWxH[{+-X}{+-}Y]\fR
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.
.TP
-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.
.TP
-list
List the images which are along the image path.
.TP
-help
Displays a short summary of xloadimage command line syntax.
.TP
-onroot
Load image(s) onto the root window instead of viewing in a window.
This is the opposite of \fI-view\fR.  \fIXSetbg\fR has this option set
by default.  Loading with the -onroot option will fail if enough
sharable colors cannot be allocated from the default colormap.
.TP
-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).
.TP
-prog_slideshow
Show image arguments one at a time instead of merging them.  While
\fIxloadimage\fP is running (say as a background process) running the
program \fInext_slide\fP will advance to the next image.  Typing 'p'
(for "pause") will cause the next invocation of \fInext_slide\fP to
wait indefinitely before advancing to the next image.  Typing 'c'
(for "continue") will undo the effect of 'p'.  Typing 'q' will quit.
This option is useful for automated demo programs in which image display is
coordinated with other programmed activity such as recorded voice output.
See the manual page for \fInext_slide\fP for more information.
.TP
-quiet
Forces \fIxloadimage\fR and \fIxview\fR to be quiet.  This is the
default for \fIxsetbg\fR, but the others like to whistle. 
.TP
-slideshow
Show each image argument one at a time instead of merging them.
Typing 'p' will back up to the previous image displayed, 'n' will go
to the next image, and 'q' or '^C' will quit.  This option is often
used in conjunction with -fullscreen.
.TP
-supported
List the supported image types. 
.TP
-verbose
Causes \fIxloadimage\fR 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 \fIxview\fR and \fIxloadimage\fR. 
.TP
-version
Print the version number and patchlevel of this version of
\fIxloadimage\fR.  Versions prior to version 1, patchlevel 03 do not
have this option and should be updated.
.TP
-view
View image(s) in a window.  This is the opposite of \fI-onroot\fR and
the default for \fIxsetbg\fR. 
.SH IMAGE OPTIONS
The following options may preceed each image.  These options are
local to the image they preceed. 
.TP
-at \fIX\fR,\fIY\fR
Indicates coordinates to load the image at on the first image.  If
this is an option to the first image, and the \fI-onroot\fR option is
specified, the image will be loaded at the given location on the
display background. 
.TP
-background \fIcolor\fR
Use \fIcolor\fR 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. 
.TP
-brighten \fIpercentage\fR
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. 
.TP
-center
Center the image on the first image loaded.  If this is an option to
the first image, and the \fI-onroot\fR option is specified, the image
will be centered on the display background. 
.TP
-colors \fIn\fR
Specify the maximum number of colors to use in the image.  This is a
way to forcibly reduce the depth of an image.
.TP
-clip \fIX\fR,\fIY\fR,\fIW\fR,\fIH\fR
Clip the image before loading it.  \fIX\fR and \fIY\fR define the
upper-left corner of the clip area, and \fIW\fR and \fIH\fR define the
extents of the area.  A zero value for \fIW\fR or \fIH\fR will be
interpreted as the remainder of the image. 
.TP
-dither
Dither a color image to monochrome using a Floyd-Steinberg dithering
algorithm.  This is slower than \fI-halftone\fR but looks much better.
.TP
-foreground \fIcolor\fR
Use \fIcolor\fR 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. 
.TP
-halftone
Force halftone dithering of a color image when displaying on a
monochrome display.  This happens by default when viewing color images
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 \fI-dither\fR option will not blow the image up
but will take longer to process.
.TP
-name \fIimage_name\fR
Force the next argument to be treated as an image name.  This is
useful if the name of the image is \fI-dither\fR, for instance. 
.TP
-xzoom \fIpercentage\fR
Zoom the X axis of an image by \fIpercentage\fR.  A number greater
than 100 will expand the image, one smaller will compress it.  A zero
value will be ignored. 
.TP
-yzoom \fIpercentage\fR
Zoom the Y axis of an image by \fIpercentage\fR.  See \fI-xzoom\fR for
more information. 
.TP
-zoom \fIpercentage\fR
Zoom both the X and Y axes by \fIpercentage\fR.  See \fI-xzoom\fR 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.
.SH EXAMPLES
To load the rasterfile "my.image" onto the background and replicate
it to fill the entire background:
.sp
.ti +5
xloadimage -onroot my.image
.PP
To load a monochrome image "my.image" onto the background, using red