PIXELDLL
---------
PIXELDLL is a simple DLL that allows a process to create
VGA graphics in a full screen OS/2 protected mode session.

GENERAL NOTES
--------------
Only one thread per session is allowed to access the DLL
at a time.

Available functions from the DLL are defined in the file
PIXELDLL.H. This file should be included in any programs that use
the DLL.

The DLL function CliOpenVGA must be called before any other
DLL calls can be made. Likewise, CliCloseVGA must be called after
all DLL calls and before the program exits.

The following calls to the DLL will BLOCK until the physical screen
for the process calling the function comes to the foreground :

CliOpenVGA - Saves screen mode and state, and then sets VGA
mode and registers screen threads for process.
CliCloseVGA - Releases owners of screen threads and
resets screen state and screen mode.

PgrClrScrVGA - Clears entire screen to given color.
PgrSaveScreenVGA - Saves entire screen to given file.
PgrRestoreScreenVGA - Restores entire screen from given file.

PgrSetPaletteVGA - Sets acolor [] array value to given value.
The proper operation of this function
has NOT been verified.

The following calls to the DLL will NOT BLOCK, but will be
queued until the processes physical screen returns to the foreground.

PgrGraph - Plots object of given sType on the screen.


NOTES ON CLIOPENVGA and CLICLOSEVGA
------------------------------------
CliOpenVGA starts two threads on behalf of the calling process :
a VioSavRedrawWait thread and a VioModeWait thread.
The VioSavRedrawWait thread dynamically allocates the memory
for saving the screen when a screen-switch-out occurs, and releases the
memory upon restoring the screen after a screen-switch-in. If
insuffiscient memory is available, an ERROR beep will sound and the
screen will not be saved (or restored when the screen-switch-in occurs).

NOTES ON PGRGRAPH
------------------
In this version of the DLL only the _PIXEL object is supported.
This is due in part to the lack of CRT math functions for DLL
functions that draw more complex objects, like arcs. Also, more
complex objects take longer to plot. This is a probelm if we
queue 8000 arcs, return to the graphics session to plot the
queued arcs, then immediately ask for a task switch. The 8000
arcs may not be completely plotted before the screen switch is
forced and data may be lost. On the other hand, 8000 queued points will
redraw in a matter of seconds.
Attempts to plot any of the other sTypes defined in the header
file PIXELDLL will result in an ERROR beep sounding.
When the plot queue has filled (current capacity is 8190 objects),
a NOTE beep will sound.


NOTES ON PGRSAVESCREENVGA and PGRRESTORESCREENVGA
--------------------------------------------------
Theses functions allow plotted images to be moved to and
from disk. The data is stored in the file as 80 bytes for each plane, with
4 planes needed to represent every row of the image (always 480 rows).
Care must be used when saving and restoring files, due to the nature
of the functions which perform these tasks. Why? The entire screen must be
saved or restored before the screen is unlocked. Performing "shaky" I/O
while the screen is locked is dangerous at best, so errors during I/O
could result in the screen not being unlocked. Also, disk I/O (not to
mention overall processing speed), is very slow on my 10MHz Model 50.
This means that if a task switch request is registered when we begin
to save our screen image, the saving may not finish before the screen
switch is forced and the saved image may be incomplete. Also, I have noted
that when writing to disk while the screen is locked and the system is
waiting to screen-switch-out, the full 30 seconds might NOT be alloted
to the process before the screen switch is forced. For these reasons, the
PgrSaveScreenVGA function turns off disk verification and returns it
to its previous state when finished. Also, both the saving and restoring
functions run in the PRTYC_TIMECRITICAL class at PRTYD_MAXIMUM priority.


SAMPLE PROGRAM NOTES
---------------------
The sample program HPCOS2 is an adaptation of the hypcloid
program found in the original QC manual. Run the program with no
arguments to see the required command line parameters.
Make sure PIXELDLL.DLL resides in the LIBPATH setup in the
CONFIG file.
After entering the required data, HPCOS2 will begin to plot
points on the screen. Feel free to switch out to another task while
the figure is calculated or watch it plot. If the plotting is in the
background, a NOTE beep will sound when the plot queue is full.
When the image is draw to your liking, hit any key to save
the screen and continue. After saving the screen, the program
asks for new data parameters for plotting the hypcloid, restores
the previous screen, and plots the new hypcloid on top of the old one.
This will continue for the number of graphs specified on the command
line.
The images saved on disk can be viewed with the PIXVIEW
program. Run the program with no arguments to see the required
command line parameters.

ENDING NOTES
-------------
All functions for the DLL are written in C except for a simple
ASM helper routine used for port I/O. While this helper routine is not
necessary, it was nice to figure out how to do it.
I cannot guarantee the operation of the DLL on your machine, as
I did not write the direct memory access routines myself. These routines
were adapted from a fine, fine book called Graphics Programming in C by
Stevens. Please use care because while it is difficult to really
damage most hardware with software , I understand that incorrectly
using the video registers can damage the video equipment. I have used
this DLL on a 10MHz model 50 with an 8512 running OS/2 1.0 and 1.1 (all
CSD's) without any problems since July of 1989. My main use for the
DLL is in generating fractal images.