matrixgl - Cross-platform Matrix Screensaver
--------------------------------------------
. Version: matrixgl-v2.2.4 (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.


Table of Contents
-----------------
. Introduction
. File Manifest
. Supported Operating Systems
. Compiling and Installing on *NIX
. Compiling and Installing on Mac OSX
. Compiling and Installing on Windows
. Removing Matrixgl
. Screensaver Functions/Keys
. Comments and Suggestions
. Reporting Bugs
. Acknowledgements

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.


File Manifest
-------------
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
Makefile.am       - Automake file
NEWS              - A basic changelog, for users
README            - The file you're currently reading
TODO              - Future feature plans
configure.ac      - Autoconf file
gen-bug-report.sh - Script to generate a bug report.
m4/*              - Macros used by autoconf
src/Makefile.am   - Automake file
src/matrix.c      - Main source file
src/matrix.h      - Contains prototypes for matrix.c
src/matrix1.h     - Font  header file
src/matrix2.h     - 3D Images header file
src/matrixhgl.1   - *NIX man Page
src/matrixgl.xml  - Xscreensaver config file
src/vroot.h       - Lets us find the virtual root window on *NIX
winconf/*         - Windows configuration dialog files

All other files are generated by autotools.

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 above, it will likely still work. 

Compiling and Installing on *NIX
----------------------------------
I don't provide binary packages for matrixgl, but if you know how to make one, please submit it to me. Otherwise, I'd suggest asking your distros development team to add matrixgl to their repositories.

To compile and install, fire up a terminal, cd into the source directory, and type the following commands:

$./configure
$make

And then, as root,

#make install

The latter command will add matrixgl into the appropriate xscreensaver directorys. If they don't exist, the build will fail. You can use './configure --disable-xscreensaver' to build without xscreensaver support, and still run it from a terminal, or use it with another screensaver manager.

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

I have chosen not to support KDE and Gnome screensavers, because xscreensaver is DE independent, and can run on both of them anyway. Instructions of how to switch to xscreensaver from KDE or GNOME are in the xscreensaver man page (accessible via '$man xscreensaver').

Note: On some setups, xscreensaver won't automatically recognize new screensavers when you launch xscreensaver-demo. If it doesn't, you can fix it manually by adding the line "   matrixgl -root -C green         \n\" to your ~/.xscreensaver file. This should be done automatically in a future release.

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


Compiling and Installing on Mac OSX
----------------------------------
NOTE: We don't yet support OSX. If you are not a developer, the following text won't help.

To compile on OSX, you will need to first install XCode. It should come on a disk accompanying most macs, but you can always download it at <http://developer.apple.com/technology/Xcode.html>.

Depending what version of OSX you have, you may need to download the X-Windows System (X11), available at <http://www.apple.com/downloads/macosx/apple/macosx_updates/x11formacosx.html>. It comes on the disc with 10.4 (Tiger), but you'll have to download it for 10.3 (Panther). I believe 10.5 (Leopard) has it installed by default.

Then, open up the terminal (I believe it is in Applications->Utilities->Terminal), cd to the source directory, and run the following commands:

$./configure
$make

This is where things get tricky, it compiles and runs fine (try --fs for a fullscreen window). However, I don't know how to install it in OSX, as xscreensaver works differently on it. If you know how to get it working, please email <vincent@doublecreations.com> or submit a patch, or even just a description, at <http://sf.net/projects/matrixgl/>. I don't own a mac, so I cannot work on it myself.

Compiling and Installing on WINDOWS
-----------------------------------
To run matrixgl on windows, you will need to obtain the GLUT Utility Library, as it is not a standard part of OPENGL on Windows. It can be obtained from a variety of places including the host of the original screensaver at http://knoppix.ru/glut-3.7.6-bin.zip. Follow the README included in the package. 

One way to compile would be to use Visual C++ 2005. It is freely available at http://msdn2.microsoft.com/en-us/express/aa975050.aspx, probably because its an outdated version. You can obtain a free activation key if you register. If you choose to use Visual C++, you will need to make sure you have the Platform SDK, obtainable at http://msdn2.microsoft.com/en-us/express/aa700755.aspx. Also, make sure you copy the GLUT library and header files into the appropriate directories of whichever compiler you are using.

You can compile this software as a regular .exe file. Once compiled, to install it as a screensaver, you will need to rename the .exe file, changing the extension to '.scr'. Matrixgl requires GLUT to run, and even if you didn't compile matrixgl from source, you will need to download and copy the glut32.dll library to your system directory at %WINDIR%\System\ (%WINDIR% is a Windows built-in variable, so you can paste this directly into your file manager). The glut32.dll file is included in the GLUT library mentioned at the top of this section.

Once you have installed GLUT, and have the matrixgl.scr file, simple right click and choose the 'Install' option. Then, copy the file matrixgl_config.exe to %WINDIR% (just paste %WINDIR% in the location bar of the file explorer, and copy the file over.) You can then click Preferences to change the settings.


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. You may then also want to delete the original source file directory. 

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 it. Open up a terminal and cd into the soruce directory. Then, type the following as a regular user:

$./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 immensly. 

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 appreciation for your help, we will add you to the AUTHORS file as a contributer, if you give us your name/nickname (and also your email or website 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.

Acknowledgements
-----------------
Just a note to put credit where credit is due, I would like to say that the original screensaver was developed by Alexander Zolotov and Eugene Zolotov of knoppix.ru and that it composes the vast majority of the functionality of this version. 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 :). 

Also, although I personally like the 'knoppix.ru' credit that shows up at the beginning in the original screensaver, many users found it to be an annoyance, so I moved it to a credits section accessible via the 'c' key.

See file AUTHORS for a full list of acnowledgements and contributors.
