Priority sprite pool
====================

The concept of priorities for sprites was introduced in RISC OS 4 as a minor
extension to the standard ROM/RAM shared Wimp sprite pools. This allowed
users to configure the ROM pool as taking priority over application
installed sprites. The intention with this facility was to ensure that a
safe, consistant set of sprites were used and that applications which
replaced components of the system sprites would be forced to use the default,
consistent set.

Whilst the principle was sound, it failed to take into account the fact that
users wish to configure their system to look how they want it to and not
how any other company might like them to. Thus, for many users this was not
far enough. In order to accomodate this, Select introduces the concept of
the 'Priority Sprite Pool'. This pool is intended solely for use by users
and designers of system customisation tools (generally known as 'theme
managers'). Applications outside of this category should not use modify the
Priority Sprite Pool.


Technical details
-----------------

The contents of the Priority Sprite Pool always override any sprites
installed in either the ROM or RAM sprite pools, regardless of the
configuration of the standard sprite priorities (*Configure
WimpSpritePrecedence). It would be most common for users to select ROM
sprite precendence and then to use the Priority Sprite Pool to override
the ROM settings with their own customisations.

The Priority Sprite Pool is held in a dynamic area, managed in the same
manner as the standard Wimp sprite pool. Because sprites may come from
either the Priority Sprite Pool, the ROM sprite pool, or the original
RAM sprite pool, it is necessary to use new calls to locate these pools.
Two new calls have been added to the WindowManager to allow the extra
pool to be accessed.

As with the standard RAM sprite pool, write operations should not be
performed on the pool.


Use of the system sprite area
-----------------------------
Although the Window Manager supports the use of the System Sprite Area by
applications supplying 0 as the sprite area, such use is now regarded as
obsolescent and may be removed in a future version of the WindowManager.



Commands
--------

*IconSprites

Syntax:
  *IconSprites [-priority] <file> | -priorityclear

The *IconSprites command will add sprites to either the standard Wimp sprite
pool, or the Priority Sprite Pool. If the -priority option is supplied, the
file specified will be added to the Priority Sprite Pool; otherwise it will
be added to the standard sprite pool. The -priorityclear option is intended
for 'theme' managers to reset the pool to its initial state in order to
assert a new set of customised sprites.



SWIs
----

Wimp_ReadSysInfo 19 [BaseOfSprites2]
=> R0 = 19
<= R0 = priority sprite pool
   R1 = 'high' priority sprite pool
   R2 = 'low' priority sprite pool

This call provides information about the sprite areas used for looking up
sprites in the order they are used. This call is provided for information
only. If specific sprites are required, clients should use Wimp_Extend 13.
Clients wishing to perform searches of the sprite pools without Wimp_Extend
13 should examine the pools in R0, R1, then R2 in that order.

See also:
  Wimp_ReadSysInfo 16, Wimp_BaseOfSprites


Wimp_Extend 13 [GetSpriteAddress]
=> R0 = 13
   R1 = 0 to search the sprite sprite area
        1 to search the Wimp sprite area
        pointer to sprite pool to search
   R2 = sprite name to find
<= R1 = pointer to sprite pool
   R2 = pointer to sprite

This SWI is used to locate a sprite in the same manner that the Window
Manager does. The sprite pool specified in R1 will be searched first,
followed by the priority sprite pool, then the 'high' priority sprite pool
and finally the 'low' priority sprite pool. If the sprite is not found
an error will be returned. Because this SWI can use the WindowManager's
cached tables of sprites it will be faster than a manual search of each of
the pools. 
