annotate man/man1/xreview.1 @ 0:5242703e91d3 tip

Initial checkin for AIM92 aimR8.2 (last updated May 1997).

.TH XREVIEW 1 "12 May 1995"
.LP
.SH NAME
.LP
xreview \- display of AIM cartoons for X Window System
.SH SYNOPSIS
.LP
xreview [options] [filename]
.LP
.SH OVERVIEW
.LP
xreview is a program for displaying bitmap cartoons produced by the AIM
software. All frames of a cartoon or a subset of frames can be played.
The speed may be slowed and it is possible to step through
a cartoon frame-by-frame. It has been tested under X11R4 and above. 
.SS GENERATION OF BITMAP CARTOONS
.LP
Any AIM module that creates a sequence of pictures, or "frames", may be used
to generate a cartoon. The frames are saved as bitmaps; that is, a copy
of the screen memory for the frame.  The bitmaps are created using the option "bitmap". For example,
.RS 4
  gensai [options] -bitmap [options] waveform
.RE
.LP
This creates a file called "waveform.ctn", which can be used as input
to xreview.
.LP
xreview reads and plays the sequence of bitmaps. The bitmap option
is available for AIM modules genasa, genepn, gensai and genspl.
.LP
Because the bitmaps are an exact copy of the screen memory, it is impossible
to change either the size of the cartoon or any AIM display parameters 
within xreview. In addition, if the cartoons are generated on a mulitplane
screen (e.g. 8 bits deep) then the bitmaps are very big, even though only
two colours are used by the AIM display software.  The hidden option "mono_ctn=on" 
may be used to copy only a 1-bit plane from the screen to the bitmaps.
On some machines the incorrect plane may be copied, in which case the 
cartoon displayed by xreview looks completely different to the cartoon
as it was generated by the AIM software. If this occurs, then
the option "planemask_ctn" may be used to specify which plane is copied.
This is best done by trial-and-error.  The hidden option "colour_ctn=on" forces
all planes to be copied to the bitmaps.
.RE

.SS DISPLAY OF BITMAP CARTOONS
.LP
The basic xreview command is 
.LP
	xreview [options] waveform.ctn
.LP
This loads the entire cartoon and displays the first frame.  
There are two control modes: 
.LP
 (a) keyboard and mouse-buttons within the Cartoon Window, 
.LP
.RS 1
or
.RE
.LP
 (b) a separate "Controls Window".


.SS KEYBOARD CONTROL (cursor in the Cartoon Window)
.LP
space/return: animate cartoon once (leaving the last 
.RS 35
frame displayed).
.RE
.LP
.RS 4
n:     move to and display next frame
.LP
p:     move to and display previous frame
.LP
q:     quit xreview.
.RE


.LP
left mouse button:    animate cartoon once (leaving the  
.RS 30
last frame displayed).
.RE
.LP
right mouse button:   quit xreview.
.LP
middle mouse button:  display Controls Window.
.RE

.SH CONTROLS WINDOW
.LP
'Buttons' in the Controls Window set the start frame and end frame of the 
animation, the framestep in the animation (e.g., skip every 2nd frame) and
the speed of the animation; the number indicates the delay between
frames in ms.  The buttons in the bottom panel move to and display a single
frame:
.LP
<<       back 10 frames
.LP
<        previous frame
.LP
>        next frame
.LP
>>       forward 10 frames
.LP
first    first frame
.LP
middle   middle frame
.LP
last     last frame
.LP
The numbers in the bottom-right corner indicate the current frame and the
total number of frames.
.LP
Unlike AIM displays from gen??? instructions, the cartoons may be
moved, iconified, hidden, etc. in the normal way.  The gen???
instructions are from an earlier are when few graphical tools were
available.

.SH OPTIONS
.LP
There are a number of command-line options; special purpose
abbrievations are indicated in parentheses.  (The instructions are in
a slightly different form to the gen??? instructions.)
.LP
.SS   Control Window Options
.LP
.RS 5
-controls   automatically display controls window 
.RE
.RS 17
(-con)
.RE
.RS 5
-controls_x <int>  x-position of controls window 
.RE
.RS 24 
in pixels   (-cx)  
.RE
.RS 5
-controls_y <int>  y-position of controls window 
.RE
.RS 24
in pixels (-cy)    
.RE
.RS 5
-controls_size <string>  size of controls window:  
.RE
.RS 30
(-csize)  
.RE
.RS 30
"tiny", "small" or "normal"
.RE

.SS   Cartoon Options
.LP  
.RS 5 
-image_x <int>  x-position of cartoon in pixels  (-ix)          
.RE
.RS 5
-image_y <int>  y-position of cartoon in pixels  (-iy)          
.RE
.RS 5
-speed   <int>  delay between frames in ms; default = 1 
.RE
.RS 21
(-speed)
.RE
.RS 5
-start   <int>  start frame of animation; 
.RE
.RS 21
default = first  (-start)
.RE
.RS 5
-stop    <int>  stop frame of animation; 
.RE
.RS 21
default = last    (-stop)
.RE
.RS 5
-skip    <int>  framestep in animation; 
.RE
.RS 21
default = 1        (-skip)
.RE
.RS 5
-frame   <int>  intial frame to display; 
.RE
.RS 21
default = first   (-frame)
.RE
.RS 5
-help   generate the help page   (-h)
.RE
.RS 5
-verbose  send some running information 
.RE
.RS 15
to stderr    (-v)
.RE

.LP
.SS   Cartoon Window Options
.LP  
.RS 5
-display <string>  X display server to use   -d
.RE
.RS 5
-font <font>       font used in controls window 
.RE
.RS 24
(default = Times) -f
.RE
.RS 5
-point <int>       fontsize (default depends upon 
.RE
.RS 24
size of controls window)
.RE
.RS 5
-title <string>    title of cartoon window 
.RE
.RS 24
(and of its icon)
.RE
.RS 5
-mono              assume monochrome (single-plane)   
.RE
.RS 24
cartoons; default
.RE
.RS 5
-colour            assume colour (multi-plane) 
.RE
.RS 24
cartoons
.LP
.RE
.RS 5
The following options should not be necessary if cartoons are generated and
displayed on the same CPU architecture and screen hardware.  They are of use,
however, if the CPU or screen differ.
.RE
.RS 5
-rv                reverse-video the cartoon 
.RE
.RS 24
window
.RE
.RS 5
-planemask <int>   value of planemask for displaying 
.RE
.RS 24
bitmaps; default = 1
.RE
.RS 5
-lsb               assume bit and byte order of 
.RE
.RS 24
cartoon is LSBFirst
.RE
.RS 5
-msb               assume bit and byte order of 
.RE
.RS 24
cartoon is MSBFirst
.RE
.RS 5
-dec               alias for '-lsb -rv'
.RE
.RS 5
-sun               alias for '-msb'
.RE

.SH SEE ALSO
.LP
review

.SH BUGS
.LP
None currently.

.SH COPYRIGHT
.LP
Copyright (c) Applied Psychology Unit, Medical Research Council, 1993-1995
.LP
Permission to use, copy, modify, and distribute this software without fee 
is hereby granted for research purposes, provided that this copyright 
notice appears in all copies and in all supporting documentation, and that 
the software is not redistributed for any fee (except for a nominal 
shipping charge). Anyone wanting to incorporate all or part of this 
software in a commercial product must obtain a license from the Medical 
Research Council.
.LP
The MRC makes no representations about the suitability of this 
software for any purpose.  It is provided "as is" without express or 
implied warranty.
.LP
THE MRC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
THE A.P.U. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES 
OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, 
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS 
SOFTWARE.
.LP

.SH AUTHOR
.LP
M. Akeroyd, MRC Applied Psychology Unit, Cambridge, UK.