
                               xdesktopwaves 1.3

               Simulation of water waves on the X Windows desktop

                        Copyright (C) 2004 Oliver Hamann


                  For license please refer to the file COPYING


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.

If you want to read more about xdesktopwaves before installation, type:

   man -l xdesktopwaves.1

or go to the homepage:

   http://xdesktopwaves.sourceforge.net/


INSTALLATION
============

In seldom cases you may have to edit the Makefile. An example would be to
compile with another compiler than gcc, or to change the include, library
and install directories. Or maybe you want to add a compiler flag like
-mcpu=athlon-xp or -mcpu=pentium4.

For compiling xdesktopwaves simply type:

   make

If you get errors from the assembler, try the following command. It disables
SSE2 assembly:

   make XDW_MAX_OPTIMIZATION=1

If you get errors from the assembler again, you will probably even have to
disable MMX:

   make XDW_MAX_OPTIMIZATION=0

Hint: There is no need to disable optimization for lack of support by the CPU.
That is checked by the program at run-time.

After compilation was successful, be root and install xdesktopwaves with:

   make install

Now read the manual:

   man xdesktopwaves

You don't like to read the manual? Okay, try some of these commands:

   xdesktopwaves
   xdesktopwaves -colortheme 9 -verbose
   xdesktopwaves -quality 3 -colortheme 1 -root -stippled
   xdesktopwaves -quality 6 -colortheme 5 -window -opaque -rain 7
   xdesktopwaves -quality 4 -colortheme 3 -storm 8

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
examples above. For stopping, create an entry containing this command:

   xdesktopwaves -end


CHANGES
=======

Version 1.3
 * Added dealing with non-rectangular shape of client windows.
 * Added a criterion for the idle mode: obscurity of output window.
 * Added xdwapi.

Version 1.2
 * Added an option for improving the trails of mouse and windows:
   -eventsperframe <count>. Because this even has influence on CPU load, it
   got member of the set of options adjusted through the -quality option.
 * Added options for configuring lighting: -skyintensity <1-10>,
   -lightintensity <1-10>, -lightaltitude <deg>, -lightazimuth <deg>.
   In order to solve that, the formulas for calculating the reflections have
   been redesigned. It is theoretically a little bit more realistic now, but
   it makes no appreciable difference in the look.
 * The option -highlightcolor has been renamed to -lightcolor.
 * Added an option for another method of transparency (still highly
   experimental): -wmopacity <0-100>.

Version 1.1
 * The intensity of rain and storm is configurable now. New options:
   -rain <0-10> and -storm <0-10> (the old yes-or-no variants are deprecated).
 * The viscosity of the fluid is no longer a constant (without any speed
   loss). New option: -viscosity <1-5>
 * The rain feature no longer prevents from the idle mode: just obscure by
   other windows, but don't give -nww.
 * Bugfix: On 64-bit x86, xdesktopwaves now even compiles with gcc 3.4.
 * Bugfix: Fixed arithmetic exception on systems with a small RAND_MAX.
 * Bugfix: If -stippled, clear window at initialization.
 * Optimization/Bugfix: The color palette is reduced to have only different
   colors. This can spare about 10% of the rectangles sent to the server,
   if the display depth is 16-bit.
 * Optimization: Treatment of minimum range of out-of-date canvas rows. This
   spares up to 50% client CPU cycles when there are just very few waves
   (shortly before entering idle mode).


BUGS & FANTASIES
================

 - If running with -wmbackdrop, mouse clicks mostly are not forwarded to the
   desktop (possibly just at every second scan-line in shaped mode). I'm afraid
   that the only solution would be to extend the standard of "Extended Window
   Manager Hints", so that an application can tell the window manager not to
   interpret any input on the window.

 - There is some flicker when client windows are moved. Depending on the X
   Server, it can be conspicuous with shaped windows. This could be reduced by
   disabling the "clear-on-exposure" behavior and by immediate repainting on
   exposure events (if double-buffered).

 - Screen saver mode is still missing.

 - In high quality mode, and if client and server are on the same machine, it
   could make sense to paint with XShmPutImage instead of XFillRectangles.

 - Add special support for enlightenment 0.17.

 - The API should have functions for modifying all the other settings.

 - A graphical user interface for modifying the settings is more and more
   desirable.

 - Maybe it is possible to add options for the behavior at the edges of the
   windows: positive reflection of waves; weaker reflection of waves; deletion
   of waves; let the waves come back from the opposite edges of the output
   window.

 - The cellular automata could possibly be improved by making the cells
   hexagonal.

 - There could be an option for setting a background pixmap (stipple mode only).

 - Another idea is to have an option for setting a bitmap which defines a
   land/water mask. Would be nice in combination with an appropriate background
   pixmap.

 - Finally xdesktopwaves may be developed towards a real-time ray tracer:
   Reflect an environment pixmap (trees, clouds...). Illuminate a sea bottom
   pixmap by refraction of sunbeams. Refract rays from eye to sea bottom. Do the
   same with animated animal pixmaps in one or more layers. Unfortunately these
   things probably would not look good with the interlaced shaping of the output
   window. But maybe there could be a shore area, in which the desktop icons are
   still visible.
