======================================================================
This file is part of the Blackout screen saver.       v0.91 1995-04-15
Copyright (C) 1995 by Staffan Ulfberg.   
======================================================================


--- IMPORTANT NOTICE! --- IMPORTANT NOTICE! --- IMPORTANT NOTICE! ---

This program controls the GRAPHICS HARDWARE of your computer.  Not all
graphics adapters are supported, and the program MAY CAUSE DAMAGE to
the graphics adapter and/or monitor if used incorrectly or on the
wrong type of hardware.  If you don't want to take this risk, DO NOT
RUN THE PROGRAM!  This program comes with absolutely NO WARRANTY.

Be sure to read the "Bugs / Future" and the "Copyright details"
sections of this document before installing, using or distributing
this program.

--- IMPORTANT NOTICE! --- IMPORTANT NOTICE! --- IMPORTANT NOTICE! ---



CONTENTS
========

1. What it is and what it is good for
2. Installation / Files in archive
3. Command line options
4. How it works
5. Bugs / Future
6. Credits
7. Copyright details
8. Author
9. Revision history



1. WHAT IT IS AND WHAT IT IS GOOD FOR
=====================================

"Blackout" is a completely FREE screen saver for OS/2 versions 2.0 and
above.  It is intended for use with monitors that do have DPMS, or
"green" support.  I wrote the program primarily because I needed one
myself, and was unable to locate a free one.  At the same time I
thought this was a great time to learn OS/2 programming.

The program blanks Presentaton manager and OS/2 full screen sessions.
DOS full screen sessions are not blanked.  This of course holds for
WIN-OS/2 full screen sessions as well.  The program is not sensitive
to mouse moves, but it is to mouse clicks.  This is because I don't
want the monitor to switch on only because I happen to shake the
table.

You can forget about fancy graphics.  This program has two different
levels of screen saving: 1) After a user-programmable time, it reduces
the colour intensity on the screen.  This will save the monitor, but
you will still be able to see that it is turned on.  2) After an
additional amount of time (possibly zero) the monitor will be shut off.
I myself think that this is an undispensible tool since I like to have
my computer running 24 hours a day.

Staffan Ulfberg
email: staffanu@nada.kth.se



2. INSTALLATION / FILES IN ARCHIVE
==================================

First of all, you've got to have the emx runtime environment
installed.  If you don't already have that, get the file "emxrt.zip"
which is available at all the major OS/2 ftp sites.  Follow the
installation instructions that come with emxrt to install it.
Blackout won't run without it.

Create a directory for the screen saver (e.g. "c:\blackout").  Unzip
the archive in this directory.  You will find the following files:

	README		This file
	COPYING		The GNU General Public Licence
	blackout.exe	The program to run to start Blackout.
	black.exe	Program to switch off VSYNC and HSYNC.  This
			program doesn't run alone without blackout
			running.
	full.exe	Program that monitors keyboard activity in
			full-screen sessions.  Doesn't run
			stand-alone.
	blackdll.dll	DLL used by Blackout.
	source.zip	The source code for the program files above.

The program to run is "blackout.exe."  It can be started from an Icon
on the desktop, possibly put in the desktop "Startup" folder if you
want to start the program automatically every time you start up your
system.  Another possibility would be to add the line

RUN=c:\blackout\blackout.exe

to CONFIG.SYS.  If you do this,  you have to add the program directory
for Blackout to your PATH and LIBPATH.  I use an icon in the Startup
folder.

The program won't say anything when started.  If you want to check if
the program is running you could 1) wait for the screen to be blanked,
2) use the -l option (see next section) or 3) try to start the program
again.  It will complain if already started.

One other thing: I strongly recommend not to start the "black.exe"
program when Blackout is running already.  (How many will try this
just because I told you not to???)



3. COMMAND LINE OPTIONS
=======================

On invocation, the following command line options are available:

-t xxx		Sets timeout before time is blanked to grey in
		minutes.  The default setting is 15 minutes.

-b yyy		Sets the time from that the screen is turned grey
		until it is turned off using the DPMS function.
		Default for this parameter is 45 minutes.  It might
		not be a good idea to set xxx+yyy to a very short
		time.

-s 		Sets monitor in suspend mode instead of the default
		power-off mode after xxx+yyy minutes.	

-l		Add program to the system window list, so it can be
		switched to by pressing CTRL-ESC.  The window
		displayed contains no information.  The only reason
		that this switch is included is that it might feel
		"safer" to be able to end the program this way...

-r		Removes the program from memory if already loaded.

Note that there is no option to make the screen saver work without the
DPMS function.  If you want the program to do this, use for example
"-b 500000", that will set the timeout to about one year.



4. HOW IT WORKS
===============

In this section I'll try to explain a bit about the inner workings of
the program.  Since the source code is freely available - just unzip
the "source.zip" file that comes with this package - you can change it
yourself to fit your needs.  Still - DO read the copyright notice.

The following files are contained in the file "source.zip":

	Makefile 	Makefile to compile the program.

	blackout.def	Source files for the main program.
	blackout.rc
	blackout.ico
	blackout.c
	blackout.h
	grey.c
	grey.h

	blackdll.def	Source files for blackdll.dll.
	blackdll.c	

	full.c		Sources for full.exe.

	black.c		Source file for black.exe.
	black.def

	16bit.c		THUNK code for 16 bit os calls.
	16bit.h

	vga.h		Contains constants for physical registers in
			the vga / vesa chips.


First of all, I should tell you that I use gcc/emx09a and gnumake to
compile the program.  Actually, I don't know much about the other OS/2
compilers; if you use another compiler, I can't help you out with how
to port the program to it.

So, lets begin...  The main program is "blackout.c."  This is a PM
program.  On startup it installs an input hook to monitor keyboard and
mouse activity.  The hook function is in blackdll.c.  The input hook
sends messages "WM_USER" to the client window function when it detects
user activity.  To reduce the number of messages sent,  the input hook
function never sends a message more often than every ten seconds.

Every time the client window procedure receives a WM_USER message,  it
resets a timer.  When the timer elapses, the screen is blanked.  If
the screen was already blanked to "grey," then the DPMS blanking is
started.  More about this later.

The problem with the configuration above is that user input is never
detected in full screen sessions.  This problem is solved by two
different mechanisms:

1) A thread is started by Blackout at start-up.  All this thread does
is to wait for a semaphore.  Then it sends a WM_USER message to the
client window procedure, and waits for the semaphore again.  Thus
other processes can signal the semaphore to tell the program about
user input.  This is what the "full.exe" program does.  This program
tries to monitor keyboard and mouse activity in the current session,
but is unable to do so if it's not an OS/2 full-screen sesson.
full.exe is started by blackout when blackout is first started.

2) The screen is never blanked if the current session is a DOS
full-screen session.  If this was not checked for, the screen would be
blanked when running DOS sessions as neither of the two user-activity
sensing mechanisms will not work.

The blanking function itself consists of two parts.  The first is
linked in the main program and is called when the screen should be
made "grey".  The code currently writes directly to the VGA hardware.
Since this is a presentation manager application it should be possible
to use the palette manager for this instead.  The truth is I don't have
the programming manuals for the Gpi functions - but some time in the
future the code in "grey.c" should be rewritten.

For the DPMS blanking,  it is carried out by a full-screen executable
called black.exe.  The reason for putting this into a full-screen
program is that I write directly to the hardware.  I use the
VioScrLock function to be sure that noone else can gain access to the
screen at the same time.  Once the screen is blanked,  the program
waits for a semaphore which is cleared by the main program
(blackout.exe) when user activity starts again.

You might think that it is inconsistent to have the dpms functions in
a stand-alone executable when the "grey" functions are built in into
the program.  After all, both functions use the hardware directly.
You're right.  It is inconsistent.  The reasons for doing things like
this are 1) the "grey" function doesn't switch the video mode.  Thus
you don't have to "hear" from the monitor every time the screen turns
to grey.  2) This code should eventually be changed so that it does
not write directly to the hardware.

So, I know the above is far from a complete description of the
program...  After all, this is version 0.91.  Hopefully it will be
more complete in the future.  Please read the follwing section.  There
are lots of things to do...



5. BUGS / FUTURE
================

In this section I have collected a list of bugs to be fixed and future
enhancements to be written.  If you fix a bug or add to the program,
please let me know so I can include the changes in future versions.
You will be listed in the "credits" section below.  If you're going to
change something on the list which is going to involve a lot of work -
contact me first.  Chances are it's already fixed.  (Especially if
it's on the list).  And finally: if you find a bug that is not on the
list - please let me know!


VGA/VESA hardware is assumed.  The port addresses are hard-wired in
the program and it will therefore NOT WORK with some adapters.

DOS full screen sessions are not blanked.

Full screen sessions don't use DPMS blanking.  The problem here is
that I haven't succeded in launching the "black.exe" program when
Blackout itself is executing in the background.  The program starts,
but not as a foreground session; so it can't lock the screen.  For now
the palette is set to all black instead. (Adding a function to
grey.c.)

The "grey" function of the program should be completely revised to use
the palette manager.  Currently the program assumes that 256 colours
are used and writes directly to the hardware.  Beware!

The "full.exe" program that watches keyboard activity in full screen
sessions currently forks a new process every time you switch from one
session to another.  The process for the previous session is killed,
of course, but this would be much more efficient if carried out with
threads.  The problem here is I don't know how to kill a thread from
the main thread.

As you can see, the icon is made in a hurry.  This program needs? a
new icon!



6. CREDITS
==========

The code to switch off VSYNC and HSYNC is "stolen" from the Linux
console drivers.  Thanks to the Linux folks, and to Henrik Storner who
sent me the code.

I have studied the VESA drivers for emx written by Johannes Martin.
Actually the file "vga.h" is a direct import from this package.

This software was developed using Emacs, emx/gcc and gnumake.  Thanks
to the authors and contributors of the respective programs!



7. COPYRIGHT DETAILS
====================

Copyright (C) 1995 by Staffan Ulfberg

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.

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.

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., 675 Mass Ave, Cambridge, MA 02139, USA.



8. AUTHOR
=========

The author of Blackout is

Staffan Ulfberg
Skanoervaegen 18		(TeX: Skan\"orv\"agen)
121 52 Johanneshov
Sweden

email: staffanu@nada.kth.se



9. REVISION HISTORY
===================

1995-04-11	v0.9	First release of the program.

1995-04-15	v0.91   Added mouse button sensing in full screen
			sessions that use the mouse.  This makes it
			possible to exit black.exe by clicking the
			mouse.

			Makefile rewritten.

			Option -s added.
