File        : ReadMe
Date        : 07-Jun-97
Author      :  A.Thoukydides, 1997
Description : Information about Crazy Pointer.


INTRODUCTION

This program is inspired by MouseP written by Andrew Bolt and published in
the June 1997 *Info section of Acorn User; it consists of a relocatable
module that gives the hardware pointer a similar appearance to Andrew's
pointer.


LOADING THE MODULE

To try the new look pointer simply double-click on the module in a filer
window. The pointer should now turn to face the direction it is being moved
in, and wobble for a while when the pointer stops moving. The caret pointer
that is used when moving over some writable icons, and the popup menu
pointer, have also been modified in a similar manner.

The new pointer may be installed more permanently by copying the module into
either the !Boot.Choices.Boot.PreDesk or !Boot.Choices.Boot.Tasks
directories. The module will then be loaded automatically every time that the
computer is switched on or reset.


CONFIGURATION

A single *command is provided to configure the pointer wobble:

    *CrazyPointerWobble [-nowobble] [[-friction] <value>]
                        [[-spring] <value>] [[-force] <value>]

The possible arguments are:

    -nowobble           Disable the pointer wobble. This results in a pointer
                        that just rotates to follow movements.
    
    -friction <value>   The amount of friction. Increasing this value stops
                        any wobble quicker.
    
    -spring <value>     The strength of the spring restorative force.
                        Increasing this value makes the pointer wobble faster.
    
    -force <value>      The scaling between mouse movements and the effect on
                        the wobble. Increasing this value makes the wobble
                        more sensitive to slow motions of the mouse.

The three numeric values are specified on a logarithmic scale in the range
0 to 10, with a value of 5 being the default.


TECHNICAL DETAILS

The pointer shape is updated on every vertical sync event. This provides a
smooth animation (a different image for every frame refresh), that even works
outside the desktop and while applications are not multitasking. The
alternative of using a WIMP task that updates the pointer on null events was
considered, but not used because it would result in jerky movements and slow
the desktop down more.

The disadvantage to updating the pointer from an interrupt routine is that
the SWIs that can be used are limited; for example it isn't possible to 
redirect output to a sprite and use VDU operations to draw the pointer shape.
To overcome these problems a set of primitive graphics operations have been
implemented, including a subroutine that can plot a general polygon in
any colour (including dithered patterns) from a list of coordinates. The
complete pointer is plotted using just two operations - the first fills the
central dark blue area, and the second draws the cyan border using the same
list of coordinates.

The desktop uses several different pointers in addition to the standard
shape, such as the double-click pointer, a caret for writable icons, and a
menu for pop-up menu buttons. The pointer shape can be redefined using two
SWIs: OS_SpriteOp 36 sets the pointer shape from a sprite, and OS_Word 21,0
sets the shape from a raw bit pattern. Both of these SWIs are intercepted by
module, performed by claiming SpriteV and WordV. When OS_SpriteOp 36 is
called, the sprite name is checked against a list of known pointer names; a
match results in the standard pointer being replaced.

The final problem with implementing the wobbly pointer in assembler is the
lack of floating point support. To overcome this problem, all sections of the
code that require real numbers have been written using fixed point values,
with each 32 bit value split into half with 16 bits of integer and 16 bits of
fraction. However, high accuracy is not required for this application, so
some of the calculations have been implemented for speed and simplicitly
rather than for precision.
