matrixgl - Cross-Platform Matrix Screensaver
********************************************
. Version: matrixgl-v2.2.5 (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.com/projects/matrixgl/
Git Repository  : http://matrixgl.git.sourceforge.net/git/gitweb.cgi?p=matrixgl/matrixgl;a=summary


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.5-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. If you don't use xscreensaver, You can use 
'./configure --disable-xscreensaver' to build without it. The install command
will still work, just installing the man page. You could then 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.

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

NOTE: In some distros, xscreensaver won't automatically recognize new 
screensavers when you launch xscreensaver-demo. If you don't see it in the 
list, you need to run the following script:
  $./add-user-entry 
which will add the entry for the user that ran the script. This means that
if your distro is affected, each user that wants to use matrixgl MUST run 
this script.

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 binary package from the project website listed
above, and follow the instructions in the accompanying README. Compiling on 
windows isn't supported, if you don't know how to do it, we can't help you.


COMPILING AND INSTALLING ON MAC OSX
===================================
Matrixgl can't be run as a screensaver on OSX, as it is incompatible 
with the mac version of xscreensaver. It can be compiled and run the
same as it would for *NIX, but the installation won't work.

Note: There may be a mac version in the future, someone else is
working on a port.


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

In Windows, no files are added, although if you clicked 'Install', the file 
was probably copied to %WINDIR%\System32\matrixgl.scr. Also, you may want to 
delete the files %WINDIR\matrixgl_config and %WINDIR%\matrixgl_config.exe. 
You may also wish to delete any GLUT files that you placed in your system 
directory. However, these files are only graphics libraries, and are not part 
of matrixgl.


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
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.
