Major internal replumbing.

Detail:

Extended the SWI interface to cope with multiple clients using BootFX to plot
progress bars (as originally intended). This did mean making a non-backwards-
compatible change to the BarUpdate SWI call (should only affect BootCmds).

Also fixed some minor bugs.

Finally, added a specification to the Docs directory and an example program
to the Tests directory.

Admin:

Implies BootCmds 1.46later.

Version 0.06. Tagged as 'BootFX-0_06'

.gitattributes

+*,ffb gitlab-language=bbcbasic linguist-language=bbcbasic linguist-detectable=true
 c/** gitlab-language=c linguist-language=c linguist-detectable=true
 h/** gitlab-language=c linguist-language=c linguist-detectable=true
 cmhg/** gitlab-language=cmhg linguist-language=cmhg linguist-detectable=true

Docs/Spec.txt

+
+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)
+  R1 = pointer to zero-terminated filename
+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.

Makefile

@@ -22,6 +22,13 @@ include CModule
 # Pass the current UserIF through to the C code
 CFLAGS += -DUserIF_${USERIF}
 
+${DIRS} ::
+	${MKDIR} squ
+
+clean ::
+	@IfThere squ Then ${ECHO} ${WIPE} squ ${WFLAGS}
+	@IfThere squ Then ${WIPE} squ ${WFLAGS}
+
 # Copy the splash screen JPEG and progress bar sprites for this UserIF for install into ResourceFS
 resources: resourcescustom
 	${CP} LocalUserIFRes:1920x1080 ${RESFSDIR}.1920x1080 ${CPFLAGS}
@@ -32,7 +39,8 @@ o.1920x1080: LocalUserIFRes:1920x1080
 	${RESGEN} SplashResources $@ LocalUserIFRes:1920x1080 Resources.${TARGET}.1920x1080
 
 o.Bar24: LocalUserIFRes:Bar24
-	${RESGEN} Bar24Resources $@ LocalUserIFRes:Bar24 Resources.${TARGET}.Bar24
+	${SQUASH} LocalUserIFRes:Bar24 squ.Bar24
+	${RESGEN} Bar24Resources $@ squ.Bar24 Resources.${TARGET}.Bar24
 
 o.Logo: LocalUserIFRes:Logo
 	${RESGEN} LogoResources $@ LocalUserIFRes:Logo Resources.${TARGET}.Logo

Resources/UK/Messages

@@ -6,5 +6,6 @@ E00:BootFX module could not claim enough memory
 E01:No sprites loaded. You must call *BootFX_Load first
 E02:Invalid or missing sprites file (must contain sprites called 'border', 'fill' and 'bar')
 E03:Splash screen JPEG file not found or not a JPEG.
+E04:Invalid BootFX progress bar handle.
 
 #{Default}

VersionNum

-/* (0.05)
+/* (0.06)
  *
  * This file is automatically maintained by srccommit, do not edit manually.
  * Last processed by srccommit version: 1.1.
  *
  */
-#define Module_MajorVersion_CMHG        0.05
+#define Module_MajorVersion_CMHG        0.06
 #define Module_MinorVersion_CMHG        
-#define Module_Date_CMHG                09 Oct 2012
+#define Module_Date_CMHG                10 Oct 2012
 
-#define Module_MajorVersion             "0.05"
-#define Module_Version                  5
+#define Module_MajorVersion             "0.06"
+#define Module_Version                  6
 #define Module_MinorVersion             ""
-#define Module_Date                     "09 Oct 2012"
+#define Module_Date                     "10 Oct 2012"
 
-#define Module_ApplicationDate          "09-Oct-12"
+#define Module_ApplicationDate          "10-Oct-12"
 
 #define Module_ComponentName            "BootFX"
 #define Module_ComponentPath            "bsd/RiscOS/Sources/Video/UserI/BootFX"
 
-#define Module_FullVersion              "0.05"
-#define Module_HelpVersion              "0.05 (09 Oct 2012)"
-#define Module_LibraryVersionInfo       "0:5"
+#define Module_FullVersion              "0.06"
+#define Module_HelpVersion              "0.06 (10 Oct 2012)"
+#define Module_LibraryVersionInfo       "0:6"

cmhg/bootfxHdr

@@ -60,6 +60,6 @@ swi-chunk-base-number:	BootFXSWI_Base
 
 swi-handler-code:	Module_SWI
 
-swi-decoding-table:	BootFX	BarUpdate
+swi-decoding-table:	BootFX	BarUpdate, BarLoad, BarDisplay, BarFree, BarReadInfo
 
 international-help-file:"Resources:$.Resources.BootFX.Messages"

h/BootFX

@@ -6,6 +6,30 @@
 #ifndef BOOTFX_H__
 #define BOOTFX_H__
 
+/** Internal error codes.
+ */
+#define BOOTFX_ERR_MALLOC_FAIL     (0x00)
+#define BOOTFX_ERR_NO_SPRITES      (0x01)
+#define BOOTFX_ERR_INVALID_SPRITES (0x02)
+#define BOOTFX_ERR_NO_JPEG         (0x03)
+#define BOOTFX_ERR_BAD_BAR_HANDLE  (0x04)
+
+/** Star command syntax error codes.
+ */
+#define BOOTFX_ERR_SYN_LOAD  (0xFF)
+#define BOOTFX_ERR_SYN_POS   (0xFE)
+#define BOOTFX_ERR_SYN_PLOT  (0xFD)
+#define BOOTFX_ERR_SYN_FREE  (0xFC)
+#define BOOTFX_ERR_SYN_DEBUG (0xFB)
+
+/** The path variable published by this module.
+ */
+#define BOOTFX_SYSVAR "BootFX$Path"
+
+/** This handle is used by BootCommands to update the default booting progress bar.
+ */
+#define BOOTFX_MAGIC_HANDLE (0xB007CED5)
+
 /** Some stuff that don't seem to be exported by other components (but really should be).
  */
 #ifndef JPEG_Info
@@ -30,25 +54,6 @@
 #define OSDA_Remove (1)
 #endif
 
-/** Internal error codes.
- */
-#define BOOTFX_ERR_MALLOC_FAIL     (0x00)
-#define BOOTFX_ERR_NO_SPRITES      (0x01)
-#define BOOTFX_ERR_INVALID_SPRITES (0x02)
-#define BOOTFX_ERR_NO_JPEG         (0x03)
-
-/** Star command syntax error codes.
- */
-#define BOOTFX_ERR_SYN_LOAD  (0xFF)
-#define BOOTFX_ERR_SYN_POS   (0xFE)
-#define BOOTFX_ERR_SYN_PLOT  (0xFD)
-#define BOOTFX_ERR_SYN_FREE  (0xFC)
-#define BOOTFX_ERR_SYN_DEBUG (0xFB)
-
-/** The path variable published by this module.
- */
-#define BOOTFX_SYSVAR "BootFX$Path"
-
 #endif
 
 /* SWI names from auto-generated CMHG file are appended here in the export_hdrs phase */