matrixgl - Cross-Platform Matrix Screensaver
********************************************
. Version: matrixgl-v2.2.7 (Stable release)
. Based on matrixgl 1.0 (see http://knoppix.ru/matrixgl.shtml)
. Written By:  Alexander Zolotov  <nightradio@gmail.com> 2003.
        and :  Eugene Zolotov     <sentinel@knoppix.ru> 2003.
. Modified By: Vincent Launchbury <vincent@doublecreations.com> 2008,2009.
. See AUTHORS for a complete list of contributors.


INTRODUCTION
============
The matrixgl 2.x series is based on the original version 1.0 screensaver from 
Knoppix.ru. It was written by brothers Alexander and Eugene Zolotov back in 
2003. Vincent Launchbury is now maintaining the project, with the goals of:
   * Fixing bugs, and making it run more smoothly.
   * Improving portability, so that it can run on more operating systems.
   * Adding new features and a larger variety of images.


ADDITIONAL DOCUMENTATION 
========================
AUTHORS           - A list of authors and contributors
BUGS              - List of known bugs
COPYING           - License for this software (GPL V2)
ChangeLog         - A complete changelog, for developers
INSTALL           - Detailed generic install instructions
NEWS              - A basic changelog, for users
TODO              - Future feature plans

Project Website : http://www.doublecreations.com/projects/matrixgl/
Sourceforge Site: http://www.sourceforge.net/projects/matrixgl/
Git Repository  : http://matrixgl.git.sourceforge.net/git/gitweb.cgi?p=matrixgl/matrixgl


COMPILING AND INSTALLING ON *NIX
================================
Packages for *NIX aren't currently provided. You could always ask your distros 
development team to add matrixgl to their repositories, if you don't like 
compiling yourself. 

To extract the source code, fire up a terminal, cd into your download 
directory and type the following commands:
   $tar xzf matrixgl-2.2.6-src.tar.gz
   $cd matrixgl

Then, to compile and install, run the following commands:
   $./configure
   $make
   (Then, as root)
   #make install

The latter command will install matrixgl into xscreensaver, as well as adding a
man page.  There's still one more step to get it working though, as xscreensaver
won't automatically detect new screensavers when it is run. To get it to see
matrixgl, you'll need to run the following script:
  $./add-user-entry 
which will add the entry for the user that ran the script. This means that each
user that wants to use matrixgl MUST run this script.

To run matrixgl as a screensaver, run 'xscreensaver-demo' and select 'matrixgl'
from the list.  Use the settings dialog to change various settings, such as
color and mode. 

If you don't use xscreensaver, you can run
'./configure --disable-xscreensaver' to build without it. The install command
is still needed so you can run matrixgl from a terminal, or use it with another
screensaver manager. To use with KDE/GNOME, install xscreensaver and see
instructions in the xscreensaver manpage.

For a more advanced install, see the file INSTALL. Note however, that the 
file contains generic instructions not specific to this project.

If for any reason the compilation or installation fails, you can send us
a bug report (described below), and we will get it working for you. It's
easy to do, and will also help out other users in the same situation.


INSTALLING ON WINDOWS
=====================
To run on windows, download the installer from the project website. Run it and
follow the instructions. Compiling on windows isn't supported, if you don't
know how to do it, we can't help you.


INSTALLING ON MAC OSX
=====================
Stephane Sudre ported matrixgl to Mac OSX, and it works with OSX 10.4 or later.
You can download the mac binary and sources from:
   http://s.sudre.free.fr/Software/matrixgl.html

The source is also available in the macsrc/ directory for your convenience.
Note that compiling the mac version isn't supported by us, although, if you
run into problems or find a bug, you could report it to Stephane. See the 
AUTHORS file for contact information.


REMOVING MATRIXGL
=================
In *NIX, to remove any files that may have been added, simply run 
'#make uninstall' in the source directory, as root.

In OSX, consult the README in the osx package.

In Windows, to uninstall, open the start menu and go into 
   All Programs > Matrixgl 2.2.7 
then click on "uninstall matrixgl" and follow the instructions.


SCREENSAVER FUNCTIONS/KEYS
==========================
p - Pause Screensaver at any time
c - View 3D-text credits
s - Toggle classic mode (no 3D images)
n - Cycle through to next image (when not in classic mode)


COMMENTS AND SUGGESTIONS
========================
All comments and suggestions are fully welcome. If you have anything to say,
drop me a line at vincent@doublecreations.com. 


REPORTING BUGS
==============
If you have found a bug in matrixgl, don't worry, it is very easy to report. 
Open up a terminal and cd into the source directory. Then, as a regular user,
run '$./gen-bug-report.sh' and follow the instructions. This script will 
generate a file that will help us to fix bugs. When finished, you can email 
<vincent@doublecreations.com> with details of the problem. Please attach the 
bug_report file once it has been generated, it will help us immensely. 

Again, don't worry if you are new to this, if you're not sure if something is 
a bug, send the report anyway. As a show of our appreciation for your help, 
we will add you to the AUTHORS file as a tester, if you give us your name/
nickname (and also your email if you choose).

Please do not send any bug reports to knoppix.ru unless you are using their 
original version. Any bugs in this version are fully mine.


SUPPORTED OPERATING SYSTEMS
===========================
matrixgl has been tested and confirmed to fully work on the following platforms:
   . Windows XP 32 bit
   . Windows Vista 32 bit
   . Windows 7 64 bit
   . Linux: Gentoo
   . Linux: Ubuntu
   . Linux: Debian
   . BSD: Openbsd
   . Mac OSX 10.4, 10.5, 10.6
If you're platform isn't listed, it doesn't mean that it won't work, it just 
means that it hasn't been tested. If matrixgl works properly on your OS,
you can email the good news to <vincent@doublecreations.com> and we'll add
it to the list.

ACKNOWLEDGEMENTS
================
Just a note to put credit where credit is due, I'd like to say that the 
original screensaver was developed by brothers Alexander and Eugene 
Zolotov of knoppix.ru. I did not write this screensaver, I merely modified 
it to my liking, fixing bugs and adding features. But in reality, these are 
just simple modifications of a complex and brilliantly designed gem of free 
software :). 

See the file AUTHORS for a full list of acknowledgements and contributors.
