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