Writing Screen Savers for Delirium Version 2           2nd January 1999
============================================

We welcome other coders to produce screen savers for Delirium, but we'd
like to point out that the whole aim of Delirium was to increase the
quality of Acorn screen savers. Please don't start releasing crappy
savers at the first opportunity. If you are interested in writing some
good quality effects for Delirium then please contact me (Joe) at the
address at the bottom of this file, and I'll gladly give you some help!

Before you release any of your own savers, please contact someone at
Kulture so we can officially 'OK' it. If we like the saver and are happy
for you to release it, we'll put it on our web site for people to
download.


Files and Directories
---------------------

Screen savers are stored as applications, normally within the "Savers"
directory inside Delirium (this uses the system variable
DeliriumSavers$Dir for the location on the particular system). Inside
the saver's directory there must be an "Info" file which describes the
saver to the Delirium front end, and a '!RunSaver' file that actually
starts the saver.

Optionally, savers can contain an application "!SvrSetup" which, when
run, set up various bits of the saver. More about this later.

All the files within this directory must be treated as read only. This
is because on a networked system, it might well be. The
user-configurable options for the saver should be saved to a file in the
<Choices$Write>.Delirium directory, using the name of the saver as the
filename. Non user-configurable options can live happily within the
saver's own directory if they wish.

A new feature in version 2 is that further to the single options file in
the choices directory, a further Info file can be placed in there. This
is useful if a saver (say) wants to use different VRAM values, as by
default these would be stored in the savers own directory, and so are
read only. The way to do this is to create a directory in Choices$Write,
which has the same name as the saver's own directory (including the
"!"), and drop a new Info file in there. You only need to put in this
new file any values that are different from those in the standard Info
file, as this will still be read. For example, Metamorphosis uses this
feature to allow different VRAM settings.


The !SvrSetup application
-------------------------

As mentioned earlier, a program to set up the saver can be placed in the
saver's application directory. This program will create the files in
Choices$Write.Delirium, where the saver itself can read them. The
programs should follow these guidelines:

* The program will open its main configure window when run (preferably
  in the centre of the screen), and the program will exit when this
  window is closed.
  
* If no choices file exists for the saver, the config window will
  contain sensible default values for the saver, if there is a choices
  file, the saved values will be displayed. The default values should be
  the same as those as used by the saver itself, so as to avoid
  confusion.

* The window will contain a "Default" and "Save" button - and "Save"
  will be the default (have a yellow border, etc.) The actions of these
  buttons are:
  
  Default - Put sensible default values into the icons. Do not save these
            values to file, and do not close the window.
            
  Save -    Save the selected values to file, and if clicked with Select,
            close the window (leave it open with Adjust clicks). Closing
            the window will have the effect of also exitting the
            configure program.
  
* The window sould also have a close icon on it's title bar, which will
  close the window (and exit the program), without saving any settings.


Rules for saver programs
------------------------

The saver itself can be written in whatever language you choose, but
must adhere to the following rules:

* There must be an "Info" and "!RunSaver" file, and the !RunSaver file
  must contain a suitable 'wimpslot' line.

* It must multitask by calling Wimp_Poll periodically (after every frame
  of the saver ideally).

* It must exit cleanly on receipt of the Quit message from the WIMP
  (message number 0).

* The code should be treated as system extension code, so no error
  messages can be produced. If an error occurs the saver should shut
  down silently and immediately. 

* The saver may change screen mode using the BASIC 'MODE' command, or
  OS_ScreenMode (or similar). Do not use Wimp_SetMode or you'll screw up
  the desktop. Delirium will restore the desktop mode when the saver
  exits.

* If errors occur on the code (address exceptions, divisions by zero
  etc) the saver should exit smoothly with no error message. In BASIC, a
  simple method is to use: ON ERROR OSCLI"Desktop", or somesuch, and in
  C you can use signal handlers to trap the errors.

* If for some reason the saver cannot be run properly at that time (eg.
  some savers rely on 16 bit sound, which may not be present), the saver
  again should exit smoothly with no error message. The front end can
  then start a replacement saver if configured to do so.
  
* On errors and general saver-faining-to-start events, it can set the
  system variable Delirium$Error to a suitable error string before
  exiting if it likes. Who knows - sometime in the future the front end
  might display it to let the user know what went wrong. ;)


The Info File
-------------

Comments can be put into the Info file by putting a # at the beginning
of a new line.

name: <text>

        This is the name used in the Savers menu in the configuration
        window. If this is not present then the name of the saver's
        directory is used instead.

        eg. savername: Exciting Saver


author: <text>

        Stick your name in here. Used in the Saver Info window.
        
        eg. author: The Uncle


comments: <text>

        This is a short text string to be used in the Saver Info window.
        
        eg. comments: A swirling mass of multi-coloured blobs.


version: <text>

        The saver version. Again, used in the Saver Info window.
        
        eg. version: 1.10


blankscreen: <yes/no>

        This tells Delirium whether or not to blank the screen before
        running the saver code. If yes, it opens a black window the size
        of the screen before running your code. If this is not there, it
        assumes 'yes'.


fadein: <yes/no>
fadeout: <yes/no>

        These tell Delirium whether you want the screen to fade out before
        and after executing the saver code. These default to 'yes'.
        Note: These only work if blankscreen is 'yes' too.


internal: <number>

        Don't use this. It's to signal to Delirium that the effect is
        internal to the front end. For example, 'Blank Screen' has
        internal number 1.


screenmemory: <number>

        The amount of screen memory (in Kb) that the saver needs. If this
        cannot be grabbed before the saver starts then Delirium will just
        blank the screen. Set it to zero if the saver uses the current
        desktop mode. This defaults to zero.

        eg. screenmemory: 1024


use_autovcache: <yes/no>

        This instructs Delirium to use the AutoVCache module, if present, to
        turn the screen cache on before running the saver. When the saver
        finishes, Delirium turns the cache back into 'auto' mode. This
        defaults to 'no'.


Further to these, you must ensure that the !RunSaver file for your saver
contains a WimpSlot line. Delirium will read the minimum memory required
by the saver. If this much memory can't be allocated then Delirium will
simply blank the screen.

As mentioned earlier, if an Info file exists at
Choices$Write.Delirium.!SaverName.Info, the values in that file will
override the values in the main Info file. At the moment, you are likely
to only want to put the screenmemory value in this file, although this
may change in the future.



What does the Delirium front end do?
====================================

The Delirium front end is a reasonably clever piece of kit (but then, I
would say that because I wrote it!). It does a rather more than simply
running the saver after a preset time. From version 2 onwards, it does
it with only a minimal number of bugs too! ;) What it actually does is
this:

When a saver is due to start (clicking the test button or after the time
has elapsed), Delirium does the following:

* Checks that enough memory and screen memory is available to run the saver
* Reads the current WIMP mode, palette, and positions of all open windows
* Optionally blanks/fades etc the screen
* Reads the pointer state, and turns the pointer off

If there is user activity, Delirium will stop the saver by:

* Sending a Quit message to the saver
* Restoring the old Desktop mode (if the mode has changed) and palette
* Checking the position of all windows and replacing any that have moved
  since the saver started
* Putting the screen memory back how it found it
* Optionally fading in the screen
* Restores the pointer to it's earlier state

If a saver exits prematurely, Delirium will blank the screen using Gamma
correction, and then unblank as normal when there is user activity. If
the user has selected "Start new saver if one fails" in the general
options then Delirium will attempt to start a different (randomly chosen
from the list specified in the Random congifure window). If it can't
find a suitable saver to start, it'll blank the screen.

If a WIMP error occurs while a saver is running, Delirium will allow the
error to be reported, and then blank the screen. When there is user
activity the screen will be unblanked and the error message will be
seen. For technical reasons, Delirium can't chenge the screen mode
before the error is reported, so it'll be reported in the mode the saver
is running in, and the WIMP mode will be restored when the message is
cancelled.

This should give you a reasonably good idea about how to get your own
effects working. You can also have a look at the savers themselves, as
some of them are written in BASIC. I'd recommend BlurCluster as a good
example...



Contact
=======

For more information about writing savers, contact me, Joe Oldak, at:

Email: joe@various-artists.freeserve.co.uk

Post: 'Ratchwood'
       Rise End
       Middleton
       Matlock
       Derbys DE4 4LS

General Delirium email should be sent to:

        delirium@various-artists.freeserve.co.uk

The Delirium web site is at:

        http://www.various-artists.freeserve.co.uk/delirium/
