.\" Copyright (c) 1988, University of Utah
.TH GETX11 1 "Jan 28, 1990" 1
.UC 4 
.SH NAME
getx11 \- get RLE images to an X11 display
.SH SYNOPSIS
.B getx11
[
.BI \-= " window_geometry"
] [
.B \-a
] [
.BI \-d " display"
] [
.B \-D
] [
.B \-f
] [
.BI \-g " display_gamma"
] [
.BI \-{iI} " image_gamma"
] [
.B \-j
] [
.B \-m
[
.I  maxframes/sec
]
] [
.BI \-n " levels"
] [
.B \-s
] [
.BI \-t " title"
] [
.B \-v
] [
.B \-{wW}
] [
.BI \-x " visualtype"
] [ 
.I infile ...
]
.SH DESCRIPTION
This program displays an
.IR RLE (5)
file on an 
.I X11
display.  It uses a dithering technique to take a
full-color or gray scale image into the limited number of colors
typically available under
.IR X .
Its default behavior is to try to
display the image in color with as many brightness levels as possible
(except on a one bit deep display).  Several
.I getx11
processes running simultaneously with the same color resolution will
share color map entries.
.PP
.I Getx11
uses the standard 
.I X
window creation procedure to create a window with a location and size
specified by the user, with the restriction that the window must be at
least as large as the input image.  If the window is turned into an
icon, a smaller version of the image will be displayed in the icon. 

If the input image has only a single channel, and has a color map, then
this color map will be loaded directly (if possible) instead of using
the normal dithering process.  Many images will look better if
pre-processed by 
.IR mcut (1)
or
.IR rlequant (1),
both of which produce images reduced to a single channel with a
colormap.  This is because the colors that are used to display the
image are chosen to be a good set of colors for that particular image,
rather than a set of colors that are mediocre for all images.  The
color map so created will not be shared with other windows.  The
picture comment \fIcolormap_length\fP specifies the exact number of
useful entries in the input color map.  If this is significantly less
than 256, this can save space in the shared X color map.
.SH OPTIONS
.TP
.BI \-= " window_geometry"
Specify the geometry of the window in which the image will be
displayed.  This is useful mostly for giving the location of the
window, as the size of the window will be at least as large as the
size of the image.
.TP
.B \-a
"As is", suppress dithering.
.TP
.BI \-d " display"
Give the name of the 
.I X
display to display the image on.  Defaults to the value of the
environment variable
.IR DISPLAY .
.TP
.B \-D
"Debug mode".  The operations in the input
.IR RLE (5)
file will be printed as they are read.
.TP
.B \-f
"No fork."  Normally,
.I getx11
will fork itself after putting the image on the screen, so that the
parent process may return the shell, leaving an "invisible" child to
keep the image refreshed.  If 
.B \-f
is specified, getx11 will not exit to the shell until the image is removed.
.TP
.BI \-g " display_gamma"
Specify the gamma of the 
.I X
display monitor.  The default value is 2.5, suitable for most color TV
monitors (this is the gamma value assumed by the NTSC video standard).
.TP
.BI \-i " image_gamma"
Specify the gamma (contrast) of the image.  A low contrast image,
suited for direct display without compensation on a high contrast
monitor (as most monitors are) will have a gamma of less than one.
The default image gamma is 1.0.  Image gamma may also be specified by
a picture comment in the
.I RLE (5)
file of the form
.BI image_gamma= gamma.
The command line argument will override the value in the file if specified.
The dithering process assumes that the incoming image has a gamma of
1.0 (i.e., a 200 in the input represents an intensity twice that of
a 100.)  If this is not the case, the input values must be adjusted
before dithering.
.TP
.BI \-I " image_gamma"
An alternate method of specifying the image gamma, the number
following
.B \-I
is the gamma of the display for which the image was originally
computed (and is therefore 1.0 divided by the actual gamma of the
image).  Image display gamma may also be specified by
a picture comment in the
.I RLE (5)
file of the form
.BI display_gamma= gamma.
The command line argument will override the value in the file if specified.
.TP
.B \-j
"Jump mode".  When reading an image from the standard input, each scan
line is normally displayed as soon as it is read.  This allows a user
to monitor the progress of an image generating program, for example
(common usage is "tail \-f image.rle | getx11").  Images read directly
from files are only updated after every 10 lines are read to improve
the display speed.  This behavior can be forced for the standard input
by specifying jump mode.
.TP
\fB\-m\fP [ \fImaxframes/sec\fP ]
"Movie mode."  Optional argument is maximum rate at which movies will play, in
frames per second.
.TP
.BI \-n " levels"
Specify the number of gray or color levels to be used in the dithering
process.  If not this many levels are available,
.I getx11
will try successively fewer levels until it is able to allocate enough
color map entries.
.TP
.B \-s
"Stingy mode".  Normally,
.I getx11
allocates an X server pixmap for each image to speed up the window
refresh.  If many images are displayed, the server may run out of
memory to store these pixmaps (or its virtual memory size may get very
large).  Stingy mode suppresses pixmap allocation (except in movie
mode, where the pixmaps are necessary for reasonable performance).
.TP
.BI \-t " title"
The window name for an image window normally comes from the input file
name or a 
.BI "image_title=" title
comment in the RLE file.  The window name can be forced to a
particular string with this option.
.TP
.B \-v
Verbose.  (But less so than with
.B \-D.)
.TP
.B \-w
This flag forces
.I getx11
to produce a gray scale (black-and-white) dithered image instead
of a color image.
Color input will be transformed to black and white via the
.I NTSC Y
transform.  On a low color resolution display (a display with only 4
bits, for example), this will produce a much smoother looking image
than color dithering.  It may be used in conjunction with
.B \-n
to produce an image with a specified number of gray levels.
.TP
.B \-W
This flag forces
.I getx11
to display the image as a bitonal black and white bitmap image.  This is the
only mode available on monochrome (non gray scale) displays (and is
the default there).  Black pixels will be displayed using the
.IR BlackPixel (3X)
value and white with the
.IR WhitePixel (3X)
value (note that these may not be black and
white on certain displays, or when they have been modified by the user.)
.TP
.BI \-x " visual_type"
Specify X visual type to be used.  The value may be a string or a number.
This number is assumed to be an integer
between 0 and 5, denoting 
.BR staticgray (0), grayscale (1), 
.BR pseudocolor (2), staticcolor (3), 
.BR truecolor (4), 
or 
.BR directcolor (5).
The string must match one of these visual types 
(any capitalization is ignored).
.TP
.I infile ...
Name(s) of the
.IR RLE (5)
file(s) to display.  If not specified, the image will be read from the
standard input.  In movie mode, you get one window, and zooming
is disabled.  In normal mode, you get one window per image.
.SH "Mouse/key actions (normal mode)"
.TP 20
Mouse 1 (left):
Increase zoom factor by 1, center on this pixel.
.TP 20
Mouse 2 (middle):
Recenter on this pixel.
.TP 20
Mouse 3 (right):
Decrease zoom factor by 1, center on this pixel.
.TP 20
Shift mouse 1:
Show value at this pixel.  In B&W, just shows intensity.
.TP 20
Shift mouse 2:
Toggle between zoomed and unzoomed.
.TP 20
q,Q,^C:
Quit.
.TP 20
1,2,3,4,5,6,7,8,9:
Set zoom factor.
.TP 20
Arrow keys:
Move image (when zoomed).  Shifted moves faster.
.SH "Mouse/key actions (movie mode)"
.TP 20
Mouse 1:
Run movie forward.
.TP 20
Shift Mouse 1:
Run movie continuously in current direction.
.TP 20
Mouse 2:
Step movie one frame in current direction.
.TP 20
Shift Mouse 2:
Set movie speed by moving mouse "up" and "down".  The speed chosen is displayed
in the upper right corner of the window.
.TP 20
Mouse 3:
Run movie backward.
.TP 20
space:
Flip one frame in current direction.
.TP 20
b:
"Bounce" image \- run it continuously forwards, then backwards, then
forwards, ...
.TP 20
c,C:
Run move continuously.  "c" runs it forward, "C" runs it backward.
When the movie reaches the "end", it will immediately restart from the
beginning. 
.LP
All continuing movie action can be halted by pressing a key or mouse button.
.SH SEE ALSO
.IR urt (1),
.IR RLE (5).
.SH AUTHOR
Spencer W. Thomas, University of Utah (X10 version)
.PP
Andrew F. Vesper, Digital Equipment Corp. (X11 modifications)
.PP
Martin R. Friedmann, University of Michigan (better X11, flipbook, 
magnification, info)
.SH BUGS
Display to a 24-bit visual is somewhat optimized, but could be faster.

Doesn't pay any attention to the X resource database (i.e., cannot be
customized via the
.I .Xdefaults
file).  The options, while standard for the raster toolkit, are
non-standard for X.