home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
rtsi.com
/
2014.01.www.rtsi.com.tar
/
www.rtsi.com
/
OS9
/
MM1
/
GRAPHICS
/
kwsaver20.lzh
/
programmer.lzh
/
kwsaver.programmers.notes
< prev
Wrap
Text File
|
1994-06-21
|
7KB
|
149 lines
KWSaver Programmers' Notes
==========================
UPDATED FOR VERSION 2.0 (06/21/94)
This file contains information on writing your own screen-savers for use
with KWSaver. No information contained in this file is guaranteed for future
versions (although it probably will still be valid). The version used when
writing this file was Version 2.0. As always, use this program (and all
related files) at your own risk.
Also, it is assumed you have read the "Technical Notes" section in the
kwsaver.readme file, which contains some important information not mentioned
here.
Three Types of Screen-Savers:
=============================
There are three types (ways of writing) screen-savers for KWSaver. Type 1
screen-savers are the simplest. What makes them Type 1? The fact that they
require no signal handler function. I.E. they die when a signal (any signal)
is sent to them. So, Type 2 screen-savers obviously require a signal handler
to prevent their death at the hands of a signal. Type 3 screen-savers also
require a signal handler, and also rely on the memory data module named
"kwsaver_data" (Version 2.0). Type 3 screen-savers need code to link-to, and
unlink-from the module.
When is a signal sent to a screen-saver? When KWSaver wants the
screen-saver to go away due to the user returning to his mouse/keyboard.
KWSaver will send the signal 4444 (decimal) when this occurs. For Type 1
savers, this means instant death. But why would Type 2 and 3 savers want to
prevent this death anyway?
Type 2 and 3 savers "stare death in the eye" because they need to do some
cleanup processing before dying (exiting). Usually, this cleanup work is
killing some K-Windows graphics buffers the saver used for animation while it
was running. Type 3 savers need to unlink from the memory data module,
kwsaver_data. If there was no signal handler, the saver would die instantly,
but any K-Windows buffers it may have used would remain, needlessly hogging up
memory. And for a Type 3 saver, if it dies without unlinking from the
kwsaver_data module, the module will remain in memory until manually unlinked
by an unusually perceptive user! (And the kwsaver_data module is quite a
memory-hog.) So, when the saver receives a signal, it should deallocate
(kill) any K-Windows buffers it has been using, unlink from the kwsaver_data
module (if it's a Type 3 saver), and then exit.
RULES FOR WRITING SCREEN-SAVERS THAT WORK:
==========================================
1) Thou shalt use the current screen, and none other. Do not allocate any
other screen, and do not attempt to Select() another screen.
2) Thou shalt NOT deallocate (DWEnd) the current screen. (KWSaver will take
care of this for you upon exit.)
3) Thou shalt NOT change palettes. (Actually, you can if you want, but since
savers do not run on the currently selected screen, the palette changes will
have absolutely no visual effect.)
4) Thou shalt die when a signal is sent. (Specifically for Type 2 and 3
savers... Be sure to make your saver responsive enough to a received signal.
When the user comes back, s/he does not want to wait a half-hour for the
screen-saver to die because the programmer wanted to list the credits, company
logo, etc.!)
5) Thou shalt NOT require any command-line arguments... since there's no
command-line!
6) If thy screen-saver is of Type 3, thou shalt unlink from the
"kwsaver_data" module before exiting. (Hmmm... I wonder how many times I
should repeat this to make sure people know it's important!)
Included Sample Files:
======================
Well, that's pretty much all the information you really need to get
started. If you follow the rules, things should work out pretty nicely.
There are a few sample files with source code included in this archive to help
you out. 'kwsaver_lines.c' is a simple Type 1 saver. If you are a novice
OS-9 C programmer, you may want to check this out. If you are familiar with
signal handlers, and feel you're ready to tackle Type 2, check out
'kwsaver_mm1s.c' to see how a graphical logo is moved around the screen.
(The last program also requires a header file, 'kwsaver_mm1s.h' to compile.)
Type 3 screen-savers add yet another level of complexity, and you really
do need to know what you're doing before you attempt one of these puppies. I
have included the source-code to a sample Type 3 saver program named
'kwsaver_rain.c' for those interested. I would suggest directly copying the
the module linking/unlinking code directly from that source to any Type 3
saver you may try to write, since that can be a slightly confusing part of
writing a Type 3 saver. Below, please find the file specification of the
"kwsaver_data" module.
Anyone who develops a screen-saver, please send me a copy. I'd love to
see it!
Finally, this program has taken up a decent amount of time to write
(mainly trying to find ways to side-step K-Windows bugs). No, I'm not asking
for any money; rather I'm stating that I'm not receiving money for this
program. Therefore, I hearby decree, no one may sell (for profit, excluding
minimal copying, shipping, and media charges) screen-savers where the intended
audience is KWSaver users. Nor can KWSaver be sold. In other words, no one
may take the work I've done for free and use it to profit themselves or
others. You may upload your screen-savers whereever you like for others to
enjoy -- that is strongly encouraged!
- = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = - = -
DEFINITION OF THE CONTENTS OF THE "KWSAVER_DATA" DATA MODULE
------------------------------------------------------------
* 'Offset' is given in BYTES, while 'INT Offset' is given in integers (4-byte
integers). The sample source file "kwsaver_rain.c" uses the convenient 'INT
Offset' notation within its code as an example.
Offset INT Offset Description
====== ========== ==========================================================
0 0 Version number of KWSaver (in ascii). The format is VVRR,
where VV is version and RR is release. For example,
Version 2.0 of KWSaver would place the string '0200' in
the first 4 bytes of the data module.
4 1 Actual size (in bytes) of screen data saved.
8 2 Bytes per scanline. (Length of each horizontal line.)
12 3 Total scanlines. (Total Y-pixel coordinates.)
16 4 Maximum X pixel coordinate.
20 5 Bits per pixel.
* Note that the number of pixels per byte can be
computed from this with the formula:
pixels_per_byte = 8/bits_per_pixel;
24 6 Maximum colors available. (16 for 16-color screen,
256 for 256-color screen.)
28 7 This is where the raw screen-data is saved. The length
of this data is given above in "Actual size of screen
data saved". Nothing follows the raw screen-data.