Writing Screen Savers for Delirium Version 2                 20th July 1998
============================================

	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 smoothy 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 exitting
  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 earler, 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
* Reads the current Palette
* Optionally blanks/fades etc the screen
* Reads the pointer state, and turns the pointer on

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

* Sending Quit message to the saver
* Restoring the old Desktop mode (if the mode has changed) and palette
* 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 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.

This should give you a reasonably good idea about how to get your own
effects. 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.demon.co.uk

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

General Delirium email should be sent to:

	delirium@various-artists.demon.co.uk

The Delirium web site is at:

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