.TH xdesktopwaves 1 "18 December 2004" "xdesktopwaves 1.3"
.SH NAME
xdesktopwaves \- simulation of water waves on the X Windows desktop
.SH SYNOPSIS
\fBxdesktopwaves\fR [\fIoption\fR]...
.SH DESCRIPTION
xdesktopwaves is a cellular automata setting the
background of your X Windows desktop under water.
Windows and mouse are like ships on the sea.
Each movement of these ends up in moving water waves.
You can even have rain and/or storm stirring up the water
(\fB\-rain\fR \fI0\-10\fR, \fB\-storm\fR \fI0\-10\fR).
.PP
In shaped mode, which is enabled by default, xdesktopwaves usually works
good together with other desktop background programs like \fBxfishtank\fR,
\fBxpenguins\fR, \fBxsnow\fR and \fBxearth\fR.
They are all under water.
.PP
xdesktopwaves has many options.
The most important ones are \fB\-quality\fR \fI0\-9\fR
and \fB\-colortheme\fR \fI0\-9\fR.
The first one is for adjusting the balance between
display quality and system load.
And the other option is for selecting a set of colors for visualization.
Choose a color theme suitable for your background picture.
There are even options for fine-tuning.
.PP
\fBWindow Managers\fR
.PP
If you are using the \fBKDE\fR window manager, please enable "Allow
programs in desktop window" in the KDE desktop configuration (right-click
on the desktop and choose "Configure Desktop").
Otherwise xdesktopwaves may not be visible.
If you are using \fBEnlightenment 0.16\fR with "Multiple Desktops"
instead of "Virtual Desktops", xdesktopwaves appears always on the
first desktop.
A solution is \fB\-wmbackdrop\fR, but read the comments on that option.
With most other window managers xdesktopwaves should
work without difficulties.
If not, try \fB\-root\fR, \fB\-wmbackdrop\fR or \fB\-window\fR, and/or
\fB\-opaque\fR.
.PP
If supported by the window manager, you should decide to enable opaque moving
and resizing of windows ("display content in moving windows" or something
like that), instead of displaying just a frame.
This may result in very dynamic wave effects - try to pile up a big wave
by moving a window slowly.
But: unfortunately some window managers seem to be
very CPU-intensive while moving a window opaque.
In that case xdesktopwaves does not perform very smooth.
.PP
\fBStarting and stopping\fR
.PP
For a first try, open a shell and type \fBxdesktopwaves\fR followed
by desired options.
Example:
.RS
.PP
\fBxdesktopwaves \-quality 4 \-colortheme 3\fR
.RE
.PP
Just press CTRL\-C for stopping.
.PP
Now, if you want to create menu entries in your desktop
environment, window manager or wherever:
For starting, create an entry containing a command like the example above.
And for stopping, create an entry containing this command:
.RS
.PP
\fBxdesktopwaves \-end\fR
.RE
.PP
Hint:
Whenever xdesktopwaves is starting, it automatically tells other
instances of xdesktopwaves to terminate.
So there cannot be more than one instance.
.PP
\fBxdesktopwaves every day?\fR
.PP
Depending on the quality settings, xdesktopwaves can be very CPU-intensive.
To get along with this, the program goes into an \fBidle mode\fR if
there are no waves on the water or if the output window is
obscured. The cellular automata stops computing in that mode.
Additionally, you can give a lower priority to the xdesktopwaves
process (see \fB\-nice\fR).
.PP
If you want to have xdesktopwaves automatically started when starting X Windows,
insert the start command in the file \fB$HOME/.xinitrc\fR (see \fBstartx\fR(1)).
But don't forget to append \fB&\fR to the command.
This way, xdesktopwaves is started before the window manager (may or may
not work, depending on the type of window manager).
.SH GENERAL OPTIONS
.TP
\fB\-h\fR or \fB\-help\fR
Print a short help and exit.
.TP
\fB\-V\fR or \fB\-version\fR
Print version and exit.
.TP
\fB\-v\fR or \fB\-verbose\fR
Print some information about what's going on.
.TP
\fB\-vv\fR or \fB\-veryverbose\fR
Print much information (for debugging).
.TP
\fB\-d\fR \fIname\fR or \fB\-display\fR \fIname\fR
Connect to the display named \fIname\fR.
.TP
\fB\-e\fR or \fB\-end\fR
Exit after terminating a possibly already existing instance of xdesktopwaves.
.SH WINDOW CREATION OPTIONS
.TP
\fB\-r\fR or \fB\-root\fR
Do not create any window, draw the waves to the (virtual) root window.
This option implies \fB\-stippled\fR if not \fB\-opaque\fR.
.TP
\fB\-b\fR or \fB\-backdrop\fR (default)
Create an override-redirect backdrop window on the (virtual) root window.
.TP
\fB\-wmb\fR or \fB\-wmbackdrop\fR
Create a backdrop window using the extended window manager hints.
This is not supported by every window manager.
And if it is, there's still the problem that it may not be possible
to activate icons or menus on the desktop background (possibly just
at every second scan-line in shaped mode).
.TP
\fB\-w\fR or \fB\-window\fR
Create an ordinary normal window.
For some window managers you'll even have to give \fB\-opaque\fR.
.SH TRANSPARENCY OPTIONS
.TP
\fB\-o\fR or \fB\-opaque\fR
Have no transparency at all.
.TP
\fB\-t\fR or \fB\-stippled\fR
Have faked transparency.
This lets the desktop background picture shine through.
Other desktop background programs and desktop icons may not be visible.
The window of xdesktopwaves inherits the background from the root
window, and the waves are drawn in stippled mode.
This option implies \fB\-nodoublebuffer\fR.
.TP
\fB\-s\fR or \fB\-shaped\fR (default)
Have better transparency.
Everything behind xdesktopwaves shines through.
The window of xdesktopwaves is shaped by every second
scan-line, using the XShape extension.
This option is ignored if \fB\-root\fR, otherwise this option
implies \fB\-doublebuffer\fR.
.TP
\fB\-wmo\fR \fIpercent\fR or \fB\-wmopacity\fR \fIpercent\fR
Have best transparency.
\fBThis is still highly experimental!\fR
It sets the window property _NET_WM_WINDOW_OPACITY, which is a hint for the
window manager respectively composite manager to render the window with
alpha blending.
This option is ignored if \fB\-root\fR.
.SH PERFORMANCE OPTIONS
.TP
\fB\-q\fR \fInumber\fR or \fB\-quality\fR \fInumber\fR (default: \fB5\fR)
Set overall quality of the waves.
\fInumber\fR can be \fB0\fR to \fB9\fR.
The higher the quality, the higher the CPU/network load.
This option is a comfortable alternative for \fB\-framerate\fR,
\fB\-simsperframe\fR, \fB\-eventsperframe\fR, \fB\-resdivision\fR,
\fB\-cellsize\fR and \fB\-maxcolors\fR.
.TP
\fB\-fr\fR \fIrate\fR or \fB\-framerate\fR \fIrate\fR
Set maximum frame rate in hertz.
This option is overridden by \fB\-quality\fR.
.TP
\fB\-sf\fR \fIcount\fR or \fB\-simsperframe\fR \fIcount\fR
Set number of simulation steps per frame.
Hereby you can adapt the speed of the waves.
This option is overridden by \fB\-quality\fR.
.TP
\fB\-ef\fR \fIcount\fR or \fB\-eventsperframe\fR \fIcount\fR
Set number of event processings per frame.
This can improve the trails of fast moving objects (mouse and windows), but
it can even incur a sensible higher CPU load, because of a worse cache
utilization.
Maximum is the number of simulation steps per frame.
This option is overridden by \fB\-quality\fR.
.TP
\fB\-rd\fR \fIrdx\fR \fIrdy\fR or \fB\-resdivision\fR \fIrdx\fR \fIrdy\fR
Set overall division of resolution in x and y direction.
These values have dramatic influence on the CPU usage on both
sides, the client and the server.
This option is overridden by \fB\-quality\fR.
.TP
\fB\-cs\fR \fIcw\fR \fIch\fR or \fB\-cellsize\fR \fIcw\fR \fIch\fR
Set width and height of the cells of water.
These values have dramatic influence on the CPU usage on the client side.
The water surface is made of rectangular cells.
This is a kind of an image, where each pixel is a cell.
For each frame, that image is scaled up to the screen size in two steps.
In the first step it is scaled by (\fIcw\fR, \fIch\fR) with
bi-linear interpolation, and in the second step it is scaled by
(\fIrdx\fR, \fIrdy\fR) without interpolation.
This option is overridden by \fB\-quality\fR.
.TP
\fB\-mc\fR \fIcount\fR or \fB\-maxcolors\fR \fIcount\fR
Set maximum number of colors for drawing the waves.
The higher the color count, the more rectangles may be sent to the X server.
\fIcount\fR can be \fB2\fR to \fB128\fR.
This option is overridden by \fB\-quality\fR.
.TP
\fB\-db\fR or \fB\-doublebuffer\fR (default)
Draw with double buffering.
This option is ignored if \fB\-stippled\fR.
.TP
\fB\-ndb\fR or \fB\-nodoublebuffer\fR
Draw without double buffering.
This option is ignored if \fB\-shaped\fR.
.TP
\fB\-n\fR \fIincrement\fR or \fB\-nice\fR \fIincrement\fR (default: \fB0\fR)
Increment nice value of the xdesktopwaves process.
The higher the nice value, the lower the process priority.
A typical value for \fIincrement\fR is \fB10\fR.
.TP
\fB\-i\fR or \fB\-idle\fR (default)
Go idle if there are no waves or if the output window is obscured.
This can spare CPU cycles.
.TP
\fB\-ni\fR or \fB\-noidle\fR
Never go idle.
.TP
\fB\-mo\fR \fInumber\fR or \fB\-maxoptimization\fR \fInumber\fR (default: \fB2\fR)
Set maximum optimization by CPU instruction set.
If compiled with GCC for x86 (32 or 64-bit), \fB1\fR means MMX and
\fB2\fR means SSE2.
\fB0\fR means to have no special optimization.
.SH COLOR OPTIONS
.TP
\fB\-c\fR \fInumber\fR or \fB\-colortheme\fR \fInumber\fR (default: \fB0\fR)
Select a color theme.
\fInumber\fR can be \fB0\fR to \fB9\fR.
Just try them through.
This option is a comfortable alternative for \fB\-watercolor\fR,
\fB\-skycolor\fR and \fB\-lightcolor\fR.
.TP
\fB\-wc\fR \fIcolor\fR or \fB\-watercolor\fR \fIcolor\fR
Set color of water.
This option is overridden by \fB\-colortheme\fR.
.TP
\fB\-sc\fR \fIcolor\fR or \fB\-skycolor\fR \fIcolor\fR
Set color of sky reflections.
This option is overridden by \fB\-colortheme\fR.
.TP
\fB\-lc\fR \fIcolor\fR or \fB\-lightcolor\fR \fIcolor\fR
Set color of light reflections.
This option is overridden by \fB\-colortheme\fR.
.SH PHYSICS OPTIONS
.TP
\fB\-wm\fR or \fB\-wavesbymouse\fR (default)
Produce waves by mouse pointer movements.
.TP
\fB\-nwm\fR or \fB\-nowavesbymouse\fR
Ignore the mouse.
.TP
\fB\-ww\fR or \fB\-wavesbywindows\fR (default)
Produce waves by client windows.
.TP
\fB\-nww\fR or \fB\-nowavesbywindows\fR
Ignore client windows.
.TP
\fB\-rn\fR \fIintensity\fR or \fB\-rain\fR \fIintensity\fR (default: \fB0\fR)
Simulate raindrops falling on the water.
\fIintensity\fR can be \fB0\fR (no rain) to \fB10\fR (cloudburst).
.TP
\fB\-st\fR \fIintensity\fR or \fB\-storm\fR \fIintensity\fR (default: \fB0\fR)
Simulate a storm blowing on the water.
\fIintensity\fR can be \fB0\fR (no wind) to \fB10\fR (strong storm).
.TP
\fB\-vs\fR \fIvalue\fR or \fB\-viscosity\fR \fIvalue\fR (default: \fB3\fR)
Set viscosity of the fluid.
\fIvalue\fR can be \fB1\fR to \fB5\fR.
The higher the viscosity, the shorter the lifetime of waves.
.TP
\fB\-si\fR \fIintensity\fR or \fB\-skyintensity\fR \fIintensity\fR (default: \fB5\fR)
Set intensity of sky reflections.
\fIintensity\fR can be \fB1\fR to \fB10\fR.
.TP
\fB\-li\fR \fIintensity\fR or \fB\-lightintensity\fR \fIintensity\fR (default: \fB5\fR)
Set intensity of light reflections.
\fIintensity\fR can be \fB1\fR to \fB10\fR.
.TP
\fB\-lal\fR \fIdegrees\fR or \fB\-lightaltitude\fR \fIdegrees\fR (default: \fB30\fR)
Set altitude of the source of light.
\fIdegrees\fR can be \fB0\fR to \fB90\fR.
.TP
\fB\-laz\fR \fIdegrees\fR or \fB\-lightazimuth\fR \fIdegrees\fR (default: \fB\-35\fR)
Set azimuth of the source of light.
\fIdegrees\fR can be \fB\-360\fR to \fB360\fR.
.SH EXAMPLES
.TP
\fBxdesktopwaves \-quality 6 \-colortheme 1 \-verbose\fR
Increased quality.
Blue color theme.
Print information about settings and performance.
.TP
\fBxdesktopwaves \-q 6 \-c 1 \-v\fR
Short cut of the previous example.
.TP
\fBxdesktopwaves \-c 2 \-rn 8 \-r \-o\fR
Dark night with flashy lights.
It's raining.
Draw to the root window without any transparency.
.SH SEE ALSO
xfishtank, xpenguins(1), xearth(1), xsnow(1), xlife(1x), xsetroot(1), startx(1)
.SH HOMEPAGE
http://xdesktopwaves.sourceforge.net/
.SH AUTHOR
Oliver Hamann (olha@users.sourceforge.net)
.SH COPYRIGHT
xdesktopwaves is copyrighted (C) 2004 by Oliver Hamann
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA