
MODULE SPECIFICATION: BootFX

This module provides additional services, primarily aimed at adding visual
effects to the boot sequence. It is intended to be built into a ROM image so
that it can start operating as soon after machine booting starts as possible.

It also provides a more general facility to any RISC OS programs for plotting
graphical progress bars (potentially, using the same theme as the boot
sequence).


=============================================================================

BOOT SEQUENCE FACILITIES

BootFX will not perform any of the boot sequence enhancements if the
configured language (*Status Language) does not map onto the Desktop module
(*ROMModules).

The initial actions, during the ROM init phase, are to switch the text cursor
off and plot a logo JEPG centred on screen. This is a low fidelity image
because the screen mode at this point is usually very low resolution.

On any subsequent mode changes, a high fidelity splash screen JPEG is plotted
full-screen and a progress bar positioned on top of it. It is up to the
subsequent boot sequence to animate/update the progress bar (via the
BootCommands' *Repeat command). The text window (VDU 28) is also adjusted to
an appropriate position for the splash screen layout.

Finally, when Service_DesktopWelcome (0x7C) is broadcast, the splash screen
is re-plotted and then discarded (so no further plotting on mode changes will
happen). Also note, the text window will not be adjusted on any mode changes
after Service_DesktopWelcome. BootFX claims the service call to stop the old
desktop banner from appearing.

Note: the initial logo JPEG, splash screen JPEG, progress bar sprites and the
text window co-ordinates are all built-into BootFX for a given UserIF. At
present, only UserIF "Raspberry" is supported.


=============================================================================

GENERAL FACILITIES

The BootFX progress bar plotting facility is intended to be generally useful,
rather than only of use to the boot sequence. It can be accessed using either
*commands or SWI calls.

In order to help with themeing, BootFX creates the path variable BootFX$Path
which points into its Resources directory. This makes it easy to get at the
progress bar sprite file used by the boot sequence. At the time of writing,
only the "Raspberry" theme is implemented, and that only in 24 bits per pixel
at EX1, EY1. This file is called "BootFX:Bar24".


=============================================================================

*COMMANDS

BootFX provides a number of *commands for control of progress bar loading and
plotting. These should be avoided in a multitasking environment because only
one progress bar can exist at a time in that context.

-----------------------------------------------------------------------------

*BootFX_BarLoad <filename>

Load a (new) progress bar sprites file. When the desktop starts, BootFX will
discard any loaded progress bar sprites in order to reduce memory use. As
such, even if you want to use the same progress bar as the boot sequence, you
need to load them first. For example:

  *BootFX_BarLoad BootFX:Bar24

The progress bar sprite file must contain three sprites (in any order):

  "border" - the area around the edge of the progress bar, with the central
             area masked to transparent

  "fill" - the central (empty) are of the progress bar - corresponding to the
           masked part of "border" - but with the edges masked out (so it is
           the same size as "border")

  "bar" - as per "fill" but showing a fully occupied progress bar (100%)

Look at the Bar24 sprites file as an example. The dimensions of the progress
bar do not need to match that example. All sprites within the file must be of
the same type (e.g. dpi, palette, eigen values, colour depth, etc).

BootFX supports the progress bar sprite file being squashed using the Acorn
!Squash application (BootFX decompresses the file into a dynamic area called
"BootFX sprites" when loading).

-----------------------------------------------------------------------------

*BootFX_BarDisplay <x> <y>

This displays a progress bar (at 0%) with its origin (bottom-left corner) at
the specified OS co-ordinates. You should do this before making any updates
to the percentage.

-----------------------------------------------------------------------------

*BootFX_BarUpdate <percentage>

Updates the displayed progress bar to the specified percentage. Values are
constrained to the range 0..100. At the time of writing, decreasing
percentages are not supported and may result in redraw errors.

-----------------------------------------------------------------------------

*BootFX_BarFree

Release any memory associated with the progress bar (and reset the position
to 0,0).

-----------------------------------------------------------------------------

*BootFX_Debug

Output debugging information, primarily about what memory has been allocated
by BootFX and what its current state is.


=============================================================================

SOFTWARE INTERRUPTS

Clients of BootFX should use the SWI interface in order to manage progress
bars in their own programs. This will allow multiple progress bars to
co-exist in a multitasking environment, for example.

The normal sequence is:

  * SWI BootFX_BarLoad
  * SWI BootFX_BarDisplay
  * While updating:
    * SWI BootFX_BarUpdate
  * SWI BootFX_BarFree

Note: in window redraw loops, you may need to call SWI BootFX_BarDisplay to
re-plot invalidated areas of the progress bar as SWI BootFX_BarUpdate only
replots the area required to cover the movement of the progress bar between
the old percentage and the new one.

On return from the SWI call, all registers are preserved unless otherwise
stated.

-----------------------------------------------------------------------------

BootFX_BarUpdate (0x59140)

In...
  R0 = flags (unspecified bits should be zero)
    0 - if set, don't wait for vsync before plotting
  R1 = progress bar handle
  R2 = percentage to update progress bar to
Out...
  All preserved

This call will update the progress bar by replotting only the area needed to
change from the previous percentage to the new percentage. In order to do
this, it will modify the current graphics window (VDU 24) so you will need to
restore that yourself after the call if this is important (e.g. in a Wimp
redraw loop).

See also *BootFX_BarUpdate.

-----------------------------------------------------------------------------

BootFX_BarLoad (0x59141)

In...
  R0 = flags (unspecified bits should be zero)
    0 - if set, R2 is a pointer to scale factors
  R1 = pointer to zero-terminated filename
  R2 = pointer to scale factors (if flag bit 0 set), as per "plot scaled"
       SpriteOps
Out...
  R0 = progress bar handle

Load the specified sprites file (which may be squashed) and return a handle
for all subsequent SWI calls using this progress bar. For the default
sprites, use the "BootFX:Bar24" file.

See also *BootFX_BarLoad.

-----------------------------------------------------------------------------

BootFX_BarDisplay (0x59142)

In...
  R0 = flags (unspecified bits should be zero)
  R1 = progress bar handle
  R2 = x co-ordinate (OS units)
  R3 = y co-ordinate (OS units)
Out...
  All preserved

Plot the progress bar at the specified OS co-ordinates. Note: this call may
affect the state of the current graphics window (VDU 24). Subsequent calls to
SWI BootFX_BarUpdate will use the co-ordinates specified by this call (and
will only plot the changed area).

See also *BootFX_BarDisplay.

-----------------------------------------------------------------------------

BootFX_BarFree (0x59143)

In...
  R0 = flags (unspecified bits should be zero)
  R1 = progress bar handle
Out...
  R1 = set to NULL

Release all memory used by the specified progress bar and invalidate the
handle.

See also *BootFX_BarFree.

-----------------------------------------------------------------------------

BootFX_BarReadInfo (0x59144)

In...
  R0 = flags (unspecified bits should be zero)
  R1 = progress bar handle
Out...
  R0 = current percentage
  R1 = x origin (OS units)
  R2 = y origin (OS units)
  R3 = width (OS units)
  R4 = height (OS units)

Return information about the specified progress bar. Width and height take into
account any scale factors that were provided to SWI BootFX_BarLoad.
