.TH xwave "" "" "X Application"
.PC "A real-time perspective mesh demo for X"
.fi
\fBxwave 
[\-amp \fIA\^\fB]
[\-bound \fIbits\^\fB]
[\-cols \fIC\^\fB]
[\-dampfactor \fIB\^\fB]
[\-demo \fInameOrNum\^\fB]
[\-edit]
[\-force \fIfuncname\^\fB]
[\-forcecol \fIN\^\fB]
[\-forcefull]
[\-forcepoint \fIR C\^\fB]
[\-forcerow \fIN\^\fB]
[\-omega \fIM\^\fB]
[\-omega2 \fIM\^\fB]
[\-plotvel]
[\-printdemo \fInameOrNum\^\fB]
[\-root]
[\-rows \fIR\^\fB]
[\-springconst \fIK\^\fB]
[\-stereo]
[\-version]
[\-wave \fIfuncname\^\fB]\fR
.PP
.B xwave
plots a perspective projection of a plane grid that oscillates in
three dimensions in real time.
You can select the size of the grid,
a forcing function to apply (and where to apply it),
and the wave propagation model to use.
You can display a plot of the velocity of the points in the
grid as well as their positions.
Double buffering is simulated using a background pixmap.
Other options are described below.
.PP
While the wave is being displayed, you can pan and zoom, stop and start
updates, and make other changes.
These also are described below.
.SH "Command-line Options"
.B xwave
recognizes the following command-line options:
.IP "\fB\-amp \fIA\fR"
Set the amplitude of the forcing function to
.IR A .
Typical values are between 20 and 100; the default is 100.
.IP "\fB\-bound \fIbits\fR"
Select which corners and edges of the grid are bound and which are free.
By default, all corners and edges are bound.
If you set
.I bits
to a single `0' or `1',
.B xwave
applies that value to all eight corners and edges.
Otherwise, each character in the string applies to one corner or edge:
if that character is `0', the corresponding corner or edge is free;
else it is bound.
The sequence of corners and edges in the string is as follows:
low row/low column,
low row,
low row/high column,
high column,
high row high column,
high row,
high row/low column, and
low column.
For example,
.DM
	-bound "00111000"
.DE
.IP
means that the high column end of the grid,
including those corners, are bound; and all other corners and edges are free.
.IP "\fB\-cols \fIC\fR"
Set the number of columns in the grid to
.IR C .
The minimum number of columns is two.
Larger numbers give more detailed wave displays,
but take longer to compute and thus do not update as quickly.
The default is 25.
.IP "\fB-dampfactor \fIB\fR"
Set to
.I B
the damping factor used in the ``wave'' propagation model.
For details, see the description of the option
.BR \-wave ,
below.
The default is 0.001.
.IP "\fB\-demo \fInameOrNum\fR"
Run demonstration program
.IR nameOrNum .
Each demonstration is equivalent to a specific set of switches
(which you can see with the command-line option
.BR \-printdemo ).
For a quick tour of the program, run
.DM
	xwave -demo \fIN\fR
.DE
.IP
beginning \fIN\fR=0 and incrementing until it tells you there are no more
demonstrations.
.IP \fB\-edit\fR
Interactively shape the wave while the program is running.
When the program is in edit mode, the mouse controls an X-shaped cursor that
moves over the surface of the grid.
Position the cursor to where you want
to modify the wave and press and hold the left-mouse button.
At this point,
dragging the mouse up and down modifies the amplitude of the wave, and
dragging it left and right controls its frequency.
Releasing the mouse button lets you modify additional points.
When you are finished editing points,
press the right mouse button to enter continuous-run mode.
.IP "\fB\-force \fIfuncname\fR"
Use the forcing function
.IR funcname .
You can also change this interactively; for details, see the section on
interactive use, below.
.IP "\fB\-forcecol \fIC\fR"
Apply the forcing function to every grid point in column
.IR C .
(The forcing function
.B multisine
ignores this information.)
.IP \fB\-forcefull\fR
Forcing functions that do not cover the full cycle should
force a zero value during the remainder of the cycle.
By default, the forcing function takes no action during this part of the
cycle, but lets the point move freely.
This affects the forcing functions
.BR delta ,
.BR pulse ,
.BR onehalfsine ,
and
.BR onehalfsinesquared .
.IP "\fB-forcepoint \fIR C\fR"
Apply the selected forcing function to the point at row
.I R
and column
.IR C .
(The forcing function
.B multsine
ignores this information.)
.IP "\fB\-forcerow \fIR\fR"
Apply the forcing function to every point in row
.IR R .
(The forcing function
.B multisine
ignores this information.)
.IP "\fB\-omega \fIM\fR"
Use the frequency multiplier
.I M
with forcing functions.
A larger number makes the forcing functions cycle through their values faster.
.IP "\fB\-omega2 \fIM\fR"
Use
.I M
as the secondary frequency multiplier.
This number is used in the forcing functions
.BR pulse ,
.BR onehalfsine ,
and
.BR onehalfsinesquared .
If you specify
.BR "\-omega2 1" ,
each of these functions has a duty cycle of 1/2;
if you specify
.BR "-omega 2" ,
it will be 1/4, etc.
.IP \fB\-plotvel\fR
Tell
.B xwave
to display a plot of the velocity of each point in the grid below
the plot of that point's the position.
The velocity information is updated only by the ``wave'' propagation function.
.IP "\fB\-printdemo \fInameOrNum\fR"
Print the switches that comprise the specified demonstration, then exit.
.IP \fB\-root\fR
Plot the wave in the root window.
.IP "\fB\-rows \fIR\fR"
Use
.I R
rows on the grid.
The minimum number is two.
Larger numbers give more detailed wave displays,
but take longer to compute and thus do not update as quickly.
The default is 18.
.IP "\fB\-springconst \fIK\fR"
Use the spring constant
.I K
in the ``wave'' propagation function.
For details, see the description of the switch
.B \-wave ,
below.
The default is 0.01.
.IP \fB\-stereo\fR
Plot separate projections in red and blue.
Make sure you have your 3-D glasses handy.
This works only on a color display.
.IP \fB\-version\fR
Prints the current version of
.B xwave
and exit.
.IP "\fB\-wave \fIfuncname\fR"
Use the wave-propagation function
.IR funcname ,
which can be one of the following:
.RS
.IP \fBnone\fR
Use no wave-propagation function.
This lets you see the ``naked'' forcing function.
.IP \fBrelax\fR
This gives a pleasant demostration with the forcing function
.B multisine
(the original
.B xwave
program).
.IP \fBwave\fR
This uses a physical wave-propagation model.
In this model, each point has a mass of one, and a velocity as well as a
position.
A simple spring model is used,
.DM
	F = -K*x -B*v
.DE
.IP
where
.I K
is the spring constant (as specified by the option
.BR \-springconst )
and
.I B
is the damping factor (as specified by the option
.BR \-dampfactor ).
The distance used for
.I x
is the simple vertical distance between a point and its neighbors.
.RE
.IP
Note that since this is a discreet simulation, the simulation is
highly dispersive (low frequencies travel faster),
so single pulses do not travel very well.
However, you can still see the effects of reflection against a free or
bound end, set up nice standing waves, see how the velocity is out of
phase with the position, and so on
.SH "Interactive Use"
While
.B xwave
is running, you can use the mouse buttons to change the perspective.
.PP
To pan the picture as it is running, hold down the middle-mouse
button and drag the mouse.
To zoom in and out, hold down the left- or right-mouse buttons.
(Note that these operations do not work unless
.B xwave
in continuous-run mode.)
.PP
.B xwave
also recognizes a number of single-key keyboard commands that
you can type into its graphics window.
You can enter these commands whether or not
.B xwave
is in continuous run mode.
.B xwave
beeps if it does not understand a command.
Note that there may be a bit of delay in processing a keyboard command when
the program is in continuous-run mode.
The following summarizes the recognized keyboard commands:
.IP \fBC\fR
Clear the data and reset the forcing function time.
Everything starts over again.
.IP \fBD\fR
Load the forcing function data.
This is useful when in step mode.
.IP \fBF\fR
Select a different forcing function.
.B xwave
prints the name of the new forcing function.
.IP \fBP\fR
Print data.
.B xwave
prints all velocity and position data that are non-zero.
This is useful mainly in step mode for debugging.
.IP \fBQ\fR
Quit.
.IP \fBR\fR
Toggle run/step mode.
In run mode, the program runs continuously and updates the screen.
This consumes 100% of the available CPU time, and looks nice.
In step mode, you can step through each generation by pressing the
space bar, and see in detail how the grid changes at each step.
By default, the program comes up in continuous-run mode.
.IP \fBT\fR
Toggle timing mode.
When the program is in time mode,
it prints an approximation of how many frames per second it is displaying.
This is re-calculated and printed every 50 frames.
.IP \fBW\fR
Select a different wave-propagation function.
.B xwave
prints the name of the new propagation function.
.IP \fB<space>\fR
Step (when in step mode).
Calculates and displays the grid at the next time point.
.SH "See Also"
.B
X applications
.R
.SH Notes
.II "Riddle, Paul"
.II "Friedman, Mike"
.II McBeath, Jim"
.B xwave
was written by
Paul Riddle (paulr@umbc3.umbc.edu),
Mike Friedman (mikef@umbc3.umbc.edu), and
Jim McBeath (jimmc@hisoft.uucp).

