****************************************************************************
*                                                                          *
*                               DarkLord                                   *
*                                                                          *
*                A programmable desk accessory screen saver                *
*                                                                          *
****************************************************************************


Manual for version 1.00

May 11th 1992

This program is an attempt to increase the variety of screen savers
available on the Atari ST. Unlike the majority of such programs, DarkLord is
programmable using a simple command language contained in a text file. This
enables you to set up the program in the manner you require.

DarkLord is freeware; the author retains all copyright to the program, its
source code and manual, but you are free to copy it and give it to anyone as
long as no charge is made (beyond a reasonable disk/distribution charge made
by a PD library).

1. Installing DarkLord

i) System requirements.

Any ST model in any resolution. It has been tested on a TOS 1.0 520ST, a
Mega 2 with TOS 1.02 and a Mega STE with TOS 2.06, all with no problems in
colour or monochrome. It should work on the TT (in ST resolutions) as only
legitimate GEM and TOS calls have been used, but I have not been able to
test this. Unfortunately it will not work on large screen monitors.

ii) Installation

The DarkLord package contains the following files:

    DARKLORD.ACC   - the program itself
    DARKLORD.TXT   - this file
    DARKLORD.INF   - standard .INF file
    SPINNERS.INF   - alternative .INF file

There may be other files such as additional .INF files and possibly a
READ.ME text file. The supplied .INF files have been tested in all three
resolutions, but are set up to work best in high resolution. In those .INF
files containing sprites you may want to alter the sprite 'screen top limit'
parameter if running on a colour system (see section 3.8).

DarkLord is a desk accessory, so copy DARKLORD.ACC to your boot disk or hard
drive boot partition. In addition you should put the file DARKLORD.INF in
the same place. You can of course edit this file later. You will have to
reboot to load DarkLord.

DarkLord will run from Multidesk, but the Multidesk buffer size will need to
be increased and the Multidesk 'Timers' option enabled (this refers to
version 1.82 of Multidesk - later versions may differ in this respect).

When DarkLord is loaded, it first tries to load the file DARKLORD.INF. If it
can't do so, an error message is displayed. Without this file DarkLord can't
do much. It will work, but all it does is produce a blank darkened screen.
The preset defaults DarkLord uses in the absence of an .INF file are listed
in section 4 below.

iii) Operation

Once installed DarkLord does nothing during normal computer use. However if,
for a set period of time, no key is pressed, the mouse is not moved or a
button pressed, and there is no output to the printer or serial port, then
it comes into operation. What happens then depends on the commands you have
written into the .INF file.
The time required before activation is normally 3 minutes but this can be
altered with the DELAY command or by selecting 'DarkLord' from the desk
accessory menu.

Once the program is activated pressing a key or mouse button, or moving the
mouse, will return control to the main program.

iv) The DarkLord menu entry

Selecting the 'DarkLord' entry from the Desk menu brings up an alert box
with three buttons:

    Disable:       this button allows you to disable DarkLord. If you have
                   disabled it already, this will read 'Enable' instead,
                   allowing you to re-enable it.

    Options:       this takes you to another alert box with 3 more choices
                   (see below).

    Cancel:        returns you to the main program.

If you clicked on the 'Options...' button, you get another alert box with
these three buttons:

    Delay:         this button allows you to alter the delay before which
                   DarkLord comes into operation, without having to change
                   and reload your .INF file. It will cause yet another
                   alert box to be displayed, also with three buttons. The
                   left and rightmost buttons will reduce or increase the
                   delay time in 15 second stages; the minimum delay is 30
                   seconds. Click on the centre button when you have got the
                   time you want.

    Load:          this allows you to load another .INF file without
                   rebooting the machine. Normally, DarkLord looks for the
                   file DARKLORD.INF when it is first loaded, but you can
                   load another file at any time. When you choose this
                   button, the file selector is displayed and you can choose
                   the .INF file you want. Alternatively, clicking on the
                   'Cancel' button in the file selector will leave all
                   current settings unchanged. After it is loaded, you will
                   be asked if you want to see the effects of the file
                   immediately, or wait until DarkLord kicks in
                   automatically.

                   If you try to load an .INF file, then DarkLord will not
                   change any of the current settings until it has
                   successfully opened the file. It will then reset all the
                   initial default settings before loading the file; these
                   are listed in section 4 below. If after opening the file
                   there is a disk error or something which prevents all or
                   some of the file from being loaded, you may get a mixture
                   of default settings and those in the .INF file. This may
                   never happen to you, but the results can be puzzling if
                   it does.

    Test:          this button activates DarkLord immediately rather than
                   having to wait until the delay time expires.

2. The .INF file.

This is the key to making DarkLord do what you want. It is a plain ASCII
text file which can be created with any text editor. The file itself
consists of a series of text commands which are followed by a variable
number of numeric parameters, separated from the command and between
themselves by commas or spaces. Note that this file is only loaded once,
when DarkLord itself first runs, and not subsequently unless you
deliberately reload it using the desk accessory menu entry. The file may be
written in upper or lower case.

To give you an idea, here is the standard DARKLORD.INF file supplied with
the package:


; Default .INF file for DarkLord
;this is a comment line
sprite 1,2,2,1,0,0
data 1,1
00000000 00000000 00199800 00199800
00199800 00199800 00199800 00199800
00199800 00199800 00199800 00199800
00399c00 00399c00 00799e00 00799e00
00f99f00 01f99f80 03f99fc0 07f99fe0
1ff18ff8 1ff18ff8 1fe187f8 1fe187f8
1fc183f8 1f8181f8 1f0180f8 1c018038
00000000 00000000 00000000 00000000
colours 000 700 070 007 770 055 777 050 505 227 077 055 707 005 550 270
stars,0,0,1,0,3
;this is the end of the .INF file


Looking at this file, you can see that any line which commences with a semi-
colon (;) is a comment line. This allows you to insert comments so that you
know what each command line does. Blank lines are also allowed which can be
useful in splitting up a long file.

The line which starts with the word 'sprite' is a command line. 'Sprite' is
a DarkLord command and the numbers following the command word are the
command parameters; all parameters must be supplied even if not necessarily
relevant in a particular context (this is explained further under the
respective headings below). The next command is 'data' which is an
instruction to load sprite data; this is supplied in the form of the 32
hexadecimal longwords which follow the command. (Don't worry if this looks a
bit forbidding - all is explained below.) Finally, there are two more
command lines ('stars' and 'colours') and a comment to finish with.

Before examining the commands in detail, note that all commands are entirely
optional, there is no need to use any command if you don't want to. However,
if you do use a command ALL the required parameters must be included. If
this is not done, an error message will be displayed in an alert box (e.g.
'Error in .INF file at line 12!'). You will also get this if you use a
command DarkLord doesn't recognise. This is really all the error warning you
get; more explanatory error messages could have been included, but at the
cost of increasing the program size (it's already rather large).

3. The DarkLord commands.

These can be divided into four types: graphical 'effects' commands,
background commands, sprite commands and general commands.

(i) Background commands.

3.1 COLOURS

Syntax:       colours <16 3 digit hexadecimal words>

Example:
colours 000 700 070 007 770 055 777 050 505 227 077 055 707 005 550 270

This command instructs DarkLord to load a colour palette, which must be
given in the form used by TOS; that is, as 16 3 digit hexadecimal words,
separated by spaces. The entire command and parameters must all be on one
line.

You might be wondering how you get colours coded in this fashion, but in
fact, it is straightforward. If you use the control panel accessory to
change the colours, you will see that (on an ST) each colour is made up of a
mixture of red, green, and blue, with each primary colour having 8 different
values (0-7). So that (for example) yellow has a red value of 7, green value
of 7 and blue value of 0. In other words this colour has the value 770. To
get the values for each colour, use the control panel to set each colour as
you like it, noting down the mixture of primary colours as above. If you are
using high resolution (monochrome) then only the first two colours of the 16
are used, and must be either white (777) or black (000). The other 14
parameters must be given though, or an error will occur. Likewise, in medium
resolution only the first four colours will be used.

DarkLord saves the current colour palette when it becomes active and
restores it when control returns to the regular program. If you do not
include a 'colours' command in your .INF file, DarkLord will use the current
palette, but will change the background to black. It will not change any
other colours unless the primary foreground colour (the one used for text on
the Desktop) would also be black. All this may lead to colour changes you
didn't necessarily want; for this reason it is highly recommended that you
include a 'colours' command in your .INF files, because DarkLord will not
interfere with the colour palette you supply. Initially you can use the one
supplied in the DARKLORD.INF file and change it as needed.

3.2 PICTURE

Syntax:       picture <filename>

Example:      picture b:\degas\testpic.pi2

This command loads a background picture to display on screen. The picture is
only loaded when DarkLord first runs (i.e. at power up or reset), and not
after that, unless you reload an .INF file which contains a PICTURE command.

The picture must be a DEGAS picture and must match the screen resolution
(.PI1 = low res, .PI2 = medium res, .PI3 = high res). A full GEMDOS path
including folders can be passed if required, and this is recommended for if
none is given DarkLord tries to find it in the current directory (which may
not be its own directory). The picture must be uncompressed; compressed
(.PC1, .PC2, or .PC3) pictures cannot be loaded in this version of DarkLord.

Note that this command will automatically cause all colours to be cycled
every 60 seconds unless you turn this feature off using the CYCLE command.
In addition, when a background picture is loaded, if sprites are to be
displayed then the area of the screen where the sprite is to be drawn is
saved before the sprite is written. This may affect the functioning of the
SPRITE command (see section 3.8 below).

3.3 GRID

Syntax:       grid <line colour>, <line thickness>, <grid size>

Example:      grid 3,1,35

The GRID command draws a simple geometric grid on screen. This provides a
background for the sprites to move against, which can look better than a
blank screen. The parameters are:

line colour:  the colour in which the line is drawn. Not applicable in high
              resolution, when the colour will be the opposite of the
              background colour. In the colour modes, it must range from 1
              to either 3 (medium res) or 15 (low res). DarkLord will
              automatically correct colour values outside this range.

line
 thickness:   the thickness of the lines which make up the grid, in pixels.
              The minimum thickness is 1.

grid size:    the distance between the lines, in pixels. Minimum distance is
              1. The larger the size, the more 'open' the grid.

Note that this command turns on the colour cycling effect (see the PICTURE
and CYCLE commands) and causes the screen under any sprites to be saved,
which may affect your SPRITE commands.

3.4 FILL
Syntax:       fill <fill colour>, <fill style>, <fill type>

Example:      fill 2,2,20

This command flood fills the screen with one of the predefined GEM patterns.
Its purpose is the same as the GRID command. The parameters are:

fill colour:  the colour in which the fill is drawn. Ranges are the same as
              for the GRID command.

fill style:   permissible values are:  1 = solid colour (no pattern)
                                       2 = dot patterns
                                       3 = cross hatch patterns
                                       4 = Atari (tm) logo fill

fill type:    this varies depending on the fill style selected. For solid
              colour and Atari logo fills, this value does not apply and any
              number can be given (the parameter must be supplied, even
              though it is not used in this context). For dot patterns, the
              values range from 1 to 24; for cross hatch patterns from 1 to
              12. These values correspond exactly to the values found in any
              GEM reference manual, so that you can select any desired
              pattern. If you don't have such a book, try them all out!

As with the GRID command, this effect turns on both screen saving and colour
cycling.

(ii) Graphic effects

3.5 STARS

Syntax:       stars <burst size>, <burst speed>, <star size>, <star colour>,
              <star type>

Example:      stars 40,2,1,3,3

This command displays a graphic effect, a simple cluster of 'exploding'
stars. The parameters are as follows:

burst size:   This dictates how long the display lasts; it sets the number
              of times the stars are redrawn in new positions on the screen.
              If set to zero, a random size is generated.

burst speed:  this is the speed with which the stars move across the screen;
              the higher the number, the greater the speed. Set to zero it
              produces a random speed.

              Note that the combination of the burst size and burst speed
              have dramatic effects on the display. For example, small burst
              size and high burst speed produces a short lived, but fast
              moving display.

star size:    the size of the star. GEM on the ST does not allow a
              continuous range of polymarker sizes, but increases in steps
              of 11 pixels. This value should therefore be increased in
              multiples of 11. Much the best results are obtained with the
              smallest size (use 1) but try the others. Again, a parameter
              set to zero produces a randomly chosen size.

star colour:  The colour the star is drawn in. On mono systems this should
              always be set to 1 (other values have no effect). On ST medium
              resolution systems, it can have the value from 1 to 3
              inclusive; on 16 colour systems, from 1 to 15. If set to zero,
              the colour is randomly chosen.

star type:    the 'stars' are actually the standard GEM polymarkers. The
              best effects are with type 3 (asterisk), or type 5 (cross) but
              you can try other types. These are:

              1 = dot (.)
              2 = plus sign (+)
              3 = asterisk (*)
              4 = square
              5 = cross (x)
              6 = diamond

              If set to zero, the shape is randomly chosen.

The 'stars' effect can be used in conjunction with a background picture,
grid or fill pattern (see below). They may also be used along with sprites,
but a background picture (or grid or fill pattern) AND stars AND sprites all
together will produce unwanted effects with random pixels scattered over the
screen. This is a result of the method used to draw the sprites and the
stars.

Any .INF file may contain more than one 'stars' command with different
parameters and these may be mixed with 'rays' commands (up to 25 stars or
rays commands may be included). These commands are executed sequentially.

3.6 RAYS

Syntax:       rays <burst size>, <burst speed>, <ray length>, <ray colour>

Example:      rays 25,3,3,0

This command is very similar to the 'STARS' command but produces a series of
'rays' radiating outwards rather than stars. The parameters are:

burst size:
burst speed:
ray colour:   these three parameters are identical to those used in the
              STARS command.

ray length:   this is the length of the ray in pixels. It can be any value
              from 1 upwards; if set to zero, a random length is generated.

3.7 STARFIELD

Syntax:       starfield <number of stars> <star colour> <delay>

Example:      starfield 32,3,0

This turns on a simple moving 'star field' effect. The parameters are:

number of
 stars:       the number of stars used in the starfield. The maximum is 64.
              Fewer stars make a faster display, but more stars may be more
              effective. A good number is 32.

star colour:  the colour number used to draw the stars; must be 1 for mono,
              1-3 for medium resolution or 1-15 for low resolution.

delay:        a simple delay timer to slow down the effect if desired. Zero
              gives the least delay (i.e. the fastest effect).

This command really shouldn't be used in conjunction with a background
picture, grid or fill pattern as in the current version it will gradually
erase the background. Also, it will not work in conjunction with the STARS
or RAYS commands as it requires all the computer's time to operate. So, if
your .INF file has a STARFIELD command after a STARS command, you only get
one 'stars' effect and then you are locked into the starfield. If the
STARFIELD command comes first you won't ever see the stars effect. You can
of course use STARFIELD in conjunction with sprites and this can look very
effective.

(iii) Sprite commands

3.8 SPRITE


Syntax:       sprite <sprite number>, <horizontal speed>, <vertical speed>,
              <sprite colour>, <screen top limit>, <frame change rate>

Example:      sprite 1,4,4,1,10,0

This is the command to move a sprite on screen. DarkLord can display up to 3
sprites simultaneously. Note that the command does not actually display the
sprite - for that you need the DATA command (see below).

The parameters are:

sprite
 number:      A number from 1 to 3. If outside this range an error is
              generated and the command will not be acted upon.

horizontal
 speed:       The speed with which the sprite moves across the screen
              horizontally. (The units are pixels per vertical blank
              interval. A monochrome monitor has a higher refresh rate than
              colour monitors, so any given value will produce slightly
              greater speeds in high resolution.) If set to zero, the sprite
              will not move in this direction. The maximum value is 31, and
              speeds higher than this will be set to 31 (this is way fast
              enough!).

vertical
 speed:       As for the horizontal speed, but in a vertical direction. A
              maximum value of 31 again applies.

sprite
 colour:      This value has no meaning in monochrome (high resolution)
              mode; the sprite colour is the opposite of the background
              colour. The parameter must be supplied though or an error is
              generated.

              In medium resolution it may have the value 1 or 2. These
              numbers refer to the colour plane into which the sprite data
              is written, rather than a colour number. (What about the third
              colour? This is not available - see the 'technical notes'
              below.)

              In low resolution there are 4 colour planes, so the colour can
              range from 1 to 4. In both colour modes, a value of zero
              selects the colour plane randomly.

screen top
 limit:       The sprites are moved by a vertical blank interrupt (VBI)
              routine (the time when the electron gun which draws the screen
              has switched off and is returning to the top left corner of
              the screen). This makes for smooth, flicker-free movement.
              Unfortunately the time available is limited. When drawing more
              than one sprite, it is possible that the sprite will be drawn
              when the electron beam is back on and starting to redraw the
              screen. This has the effect that the sprites may flicker when
              drawn at the very top of the screen. This problem doesn't
              always occur. It is more likely to happen if:

              - you have more than one sprite on screen;

              - you have other programs installed before DarkLord which also
              use a VBI;

              - you are using a monochrome monitor, where the VB interval is
              shorter due to the higher screen refresh rate;

              - you have loaded a background picture with the PICTURE
              command, or have used the GRID or FILL commands. The reason
              for this is that in order to avoid destroying the picture,
              DarkLord saves the area of the screen into which the sprite is
              to be drawn, and restores it to erase the sprite. This extra
              work takes more time, which is not needed if no picture is
              loaded or background drawn.

              The only way around this is either to use fewer sprites or to
              prevent the access of sprites to the very top of the screen,
              which is the purpose of this command. The single parameter is
              the number of lines from the top of the screen into which the
              sprite will not move. The exact value required will vary
              between different systems, so some trial and error will be
              necessary for your system. The value can be different for each
              sprite and you will find that the value needs to be larger
              (i.e. there is a greater restriction on access to the top of
              the screen) for sprite 3 than for sprite 2 or 1. I agree that
              this is something of a kludge and I am currently trying to
              find a way around the problem.

frame change
 rate:        DarkLord has the facility to change the appearance of the
              sprite thus allowing simple animation. Up to 6 frames per
              sprite are allowed in this version. This parameter governs how
              rapidly DarkLord switches between frames, and is actually a
              delay timer; the lower its value, the faster the change
              occurs. A reasonable choice is usually around 2-4. DarkLord
              will show the frames in order in which you supplied them in
              the .INF file, then switch back to frame 1 again. To see an
              example of this, load the file 'SPINNERS.INF' supplied with
              the package.

              If you are only going to have one frame for the sprite then
              this parameter is clearly irrelevant. It must be supplied
              however or an error message results, but it can be set to any
              value you like.

You should note that the start position of all sprites in the current
version of DarkLord is the top left hand corner of the screen. Sprites are
treated as partially transparent objects. Whatever is on the screen will
'show through' those parts of the sprite which are drawn in the background
colour.

3.9 DATA

Syntax:       data <sprite number>, <number of frames>, <32 hex longwords of
              data>

Example:      data 1,1
              00000000 00000000 00199800 00199800
              00199800 00199800 00199800 00199800
              00199800 00199800 00199800 00199800
              00399c00 00399c00 00799e00 00799e00
              00f99f00 01f99f80 03f99fc0 07f99fe0
              1ff18ff8 1ff18ff8 1fe187f8 1fe187f8
              1fc183f8 1f8181f8 1f0180f8 1c018038
              00000000 00000000 00000000 00000000

This is the command to load the data which makes up the sprite shape (the
example data above is the Atari fuji symbol from the supplied DARKLORD.INF
file). The parameters are:

sprite
 number:      As for the SPRITE command (see above).

number of
 frames:      The number of frames that will be used. A value of zero hides
              the sprite. The maximum value is 6, anything greater and an
              error results.

If an error is detected in a DATA command line, the line is not accepted as
valid. When DarkLord reads the lines of sprite data which follow an
erroneous command it assumes these are command lines, and will generate a

series of errors. A single error in a DATA command may therefore cause an
apparent long string of errors! Don't be confused by this.

After the DATA command (i.e. on the next and succeeding lines - do not put
sprite data on the same line as the DATA command) comes the sprite data
itself. This is in ASCII format and takes the form of 32 blocks of
hexadecimal characters with each block representing one line (32 bits) of
sprite data. You can have one block per line, e.g.:

    ff1027ab
    fe1139a0

or more than one, with the blocks separated by spaces, e.g.:

    ff1027ab fe1139a0 cf12e309

There are some restrictions on how this data can be displayed. Comment lines
and blank lines can be interspersed with the lines of data, but no other
DarkLord commands must be included until the data is complete. The reason is
that command lines will be treated as data lines and DarkLord will attempt
to extract data from them; if they include valid hex digits (0-9, A-E), as
they probably will, you may end up with very strange looking sprites! In
addition the command lines which have been used for data will not have been
read as commands, and the remaining data lines may not be required if
DarkLord has found all the data it wants, so errors will result as the
program tries to interpret these as commands. You can of course have more
commands after the data section if you wish.

You MUST ensure that all the required data is provided. When a DATA command
is encountered, DarkLord will not stop until it has found all the data it
needs, even if this means getting it from perfectly valid command lines. If
in spite of that it cannot find all the required data, an error message will
be displayed.

How do you get your sprite data into this format? I realise that it isn't
the most friendly way of creating sprite data. Unfortunately there is no
standard sprite file format on the ST, although some programs (e.g. STOS
Basic) can create sprite files. I felt it was important that anyone could
use this feature of DarkLord without having to buy another piece of software
to do so. The obvious answer of course was to write a sprite editor, but I
wanted to concentrate on DarkLord itself for the time being. Maybe in the
next version...

There are two ways in which to create your sprites. The sprites are simply
32 x 32 pixel blocks (i.e. 32 lines of 32 pixels). The hard way to create
them is to draw them on graph paper. Outline a block of 32 x 32 squares and
draw your sprite by filling in the squares. When you are happy with it,
starting from the top left hand corner and moving across the paper write
down a '1' for every filled in square and a '0' for every blank square. At
the end of the line you have a 32 bit binary number (for example,
10111001111000111001010101110011). Repeat this for all 32 lines. These
numbers can be converted into hex using one of the numerous public domain
calculators (split the binary number into 4 8-digit blocks if necessary).

The easy way is to use the superb font editor, Fontkit Plus (available from
the ST Club, 19.95 UKP). This is the procedure:

i)       Run Fontkit+, and select .RSC images when the dialog box appears.

ii)      A grid will be displayed which by default should be 32 x 32 pixels,
         but check this and alter it if necessary.

iii)     Edit the image using the Fontkit+ drawing tools.

iv)      Save the image into the character buffer by pressing Control-S.
         This is ESSENTIAL. If you don't do this, you will not save any data
         when you save the file to disk.

v)       Save the image to disk in case you want to edit it again.

vi)      Select 'Hex list' from the Options menu; Fontkit+ prompts you for a
         file name and writes an ASCII file containing the sprite data in
         hex format, as 64 16-bit hex words.

vii)     Turn the 64 hex words into 32 longwords of 32 bits each by using a
         text editor; all you have to do is delete the space between pairs
         of words. For example, part of the file created by Fontkit+ might
         look like:

              ff01 23ac aaee ffff

         After deleting spaces, it looks like:

              ff0123ac aaeeffff

It's still quite an involved procedure but Fontkit+ makes drawing your
sprites a simple matter, and that is the difficult part. You need to repeat
this procedure for each frame of each sprite you intend to display.

(iv) General commands

3.10 DELAY

Syntax:       delay <delay time>

Example:      delay 180

This is the time delay after which, if there have been no keypresses, mouse
movements or button clicks, printer or serial port activity, DarkLord
becomes active. If you don't include this command in your .INF file, the
counter is set to 180 seconds (3 minutes). The minimum time is 30 seconds.

The single parameter is the delay time in seconds.

3.11 CYCLE

Syntax:       cycle <cycle time>

Example:      cycle 30

Normally, DarkLord sets the screen background colour to black and leaves it
there. However, if you have loaded a picture (or used the GRID or FILL
commands) then it might be displayed on the screen for a considerable time,
which rather negates the point of a screen saver! Therefore if a picture is
loaded DarkLord will normally cycle through the various colours at a set
interval (60 seconds). If you don't like this feature you can turn it off
with this command by passing a parameter of 0 (i.e. CYCLE 0). If you would
like this command to operate even if you have a blank background, you can do
that as well. In that case the parameter is the time in seconds after which
the colours, including the background colour, will be cycled through the
whole of the current palette (not just the first four colours if in medium
resolution). High resolution will of course just cycle between black and
white. Note that the minimum allowed cycle time is 15 seconds.

The cycled colour palette is not reset when DarkLord returns control to the
main program, so that when it becomes active again the colours are as they
were when it was last active.

4. Default values

When run, or before loading a new .INF file, a number of default parameters
are set. These are:

    delay time 180 seconds (3 minutes);
    the screen is cleared;
    no sprites;
    no graphic effects;
    colour palette is set to the existing palette, then changed to a black
     background and if necessary a white foreground;
    colour cycling is turned off;
    DarkLord is enabled (i.e. if you previously disabled it, it is re-
     enabled).

5. Technical notes

(i) Compatibility

Since DarkLord is a desk accessory, it will only work with those programs,
fortunately the majority, which use the AES events system. These include all
(I assume) those which display a true GEM menu bar, and some (all?) of those
programs which are essentially one large dialog box. TOS-type programs
effectively disable accessories while they run. DarkLord has been run with
the following programs and seems to be OK:

Neodesk            1st Word Plus       Fontkit Plus 3
Lattice C 5.5      Devpac 2            K-RSC resource editor
Superbase Pro      K-Spread 4          Calligrapher (original version!)
Timeworks DTP (version 1)              Tempus 2
Knife ST           Touch Up            Hyperdraw
K-Graph 3          Arcshell 2.6a       Fastcopy Pro

It does not work with (but does not crash):

Uniterm (but does work on the 'Help' screen, when a GEM menu is used)
Protext (unless you switch to the Desk Accessory menu)
Cixread 3
Degas Elite (works on the main menu screen, does not work on the drawing
screens)

It coexists with various desk accessories and auto-folder programs, of which
the only ones tested so far are:

Accessories:

Multidesk          G Plus accessory    NeoControl accessory
Image Copy         Rat Trap            X-Control

Auto folder:

G Plus             Hramdsk (HiSoft ram disk)
UIS III            Quick ST 3

(ii) Brief technical details

DarkLord produces its effects in two ways. It installs a vertical blank
interrupt (VBI) routine which takes care of all the sprite handling, the
colour cycling and delay timing. Background effects such as a loaded
picture, grid or fill are set up once only, when the accessory first runs or
when an .INF file is loaded. The stars, rays and starfield effects are
produced by the main program and so can run concurrently with the sprites.

The program hijacks several system vectors for its own use, these are:

    the ikbdsys and mousevec interrupt vectors to sense keypresses and mouse
    movements;

    one vertical blank interrupt slot;

    the BIOS (trap #13) vector;

    the GEMDOS (trap #1) vector.

DarkLord conforms to the XBRA protocol for accessories which alter system
vectors and it obeys the '11 commandments' suggested by Codehead software
for stealing vectors. All patched vectors call the original routine on exit.
It restores the original vectors on a change in colour resolution and
therefore should not crash in these circumstances.

To save processing time, sprites are written into one colour plane only, so

cannot be multicoloured. The screen on an ST is a bitmap with either 1 (high
resolution), 2 interleaved (medium) or 4 interleaved (low) colour planes.

In medium resolution, this means that 4 colours can be displayed on screen
at the same time; but the exact colour of any point depends on whether bits
are set in none (background colour), one, or both colour planes. By using
only one colour plane, sprites can only be 1 of 2 different colours
(excluding the background colour of course); the third colour is produced by
writing the sprite data into both colour planes, which would take twice as
long. In low resolution there are four planes and the sprite can therefore
be one of four colours; the other 11 (again excluding background colour) are
not available since the sprite data would have to be written into two or
more planes to obtain these colours.

6. Future developments

This version of DarkLord is bug-free as far as I have been able to test it,
but it may have problems or incompatibilities of which I am unaware. It
never writes anything to disk so should never destroy data on disk. I would
be pleased to hear of any problems and bugs (hopefully not!) and
particularly ideas for future developments. The user interface works but is
not very attractive at present. This will look nicer in future versions. The
sprite handling could also be improved; it would be nice to have sprite
collision detection and more control over frame changing (for example, to
change frames when the sprite changes direction).

I can be contacted on the CIX conference system (spedler@cix) or write to:

    Steve Pedler
    12 Rudby Close
    Gosforth
    Newcastle upon Tyne
    NE3 5JF
    England
