Wimp.Sprites

New calls

        Wimp_SpriteOp
        Wimp_BaseOfSprites

        *IconSprites <filename>
        window areaCBptr = 1 ==> use common sprite area
          icon areaCBptr = 1 ==> use common sprite area

Overview

To allow for sharing of sprite data between wimp tasks, the Wimp supports a set of shareable sprites, which is used by the Wimp utilities, and can also be used by applications. The area is split in two: one area is held in ROM, and the other is held in the RMA - the Wimp will use the RMA sprites in preference, but will revert to the ROM area if the relevant sprite is not found. A special call has been provided to access these sprites, and there is a *command to add more sprites into the area, which copes with extending the RMA block suitably.

(See also Wimp.Colours to see how sprites are coped with in the different screen modes, and Wimp.Icons for the Sprite+Text icon facility).

Loading sprites

        Wimp_SpriteOp
        Entry:  R0 = 11 (SpriteReason_MergeSpriteFile)
                R2 --> name of sprite file
        Exit:   sprites merged into the common sprite area
                the sprite area may have moved as a result

        *IconSprites <filename>

The *iconsprites call simply calls Wimp_SpriteOp, and is provided as a simple means of loading sprites from a boot file.

Accessing Sprites

        Wimp_SpriteOp
        Entry:  R0 = reason code (as for OS_SpriteOp)
                R1 doesn't matter
                R2.. parameters for OS_SpriteOp
        Exit:   R2.. = results from OS_SpriteOp
        Error:  "Bad parameter passed to Wimp in R0" if invalid reason code

The reason codes passed to Wimp_SpriteOp are exactly analagous to those passed to OS_SpriteOp, except that the Wimp will not allow any operations other than MergeSpriteFile which modify the contents of the sprite area. For all read operations, the Wimp will attempt to perform the operation on the RMA sprite area, and if the error "Sprite does not exist" is returned, will try the operation on the ROM sprite area.

Note that only bits 0..7 of R0 are used: &100 is always added to this value, so R2 always points to the sprite name, rather than the sprite itself.

In addition, another SWI is provided which allows the inquisitive application to find out where the sprite areas are located. Since the address of the RMA sprite area can change whenever more sprites are merged into it, however, the address should be re-read whenever it is needed. Wimp_SpriteOp should always be used in preference to this SWI, if possible.

        Wimp_BaseOfSprites
        Exit:  R0 --> base of ROM sprite area
               R1 --> base of RMA sprite area
               note that the RMA sprite area can move about subsequently

Using the common sprites in icons

A more usual way of accessing the common sprite area is to program the 'areaCBptr' field in a window, or the areaCBptr field in an indirected sprite icon:

        Wimp_CreateWindow
        Entry:  R1 --> window definition
                R1!64 = 0 ==> use system area for sprite icons
                      = 1 ==> use common sprite area
                      > 1 ==> use specified sprite area

        Icon block:
                + 0..15 = bounding box
                + 16    = flags
                          bit 1 set ==> icon contains a sprite
                          bit 8 set ==> icon data is indirected
                + 20    = pointer to sprite name / sprite definition
                + 24    = sprite area pointer (see above)
                + 28    = length of name block
                        = 0 ==> block!20 is a sprite pointer
                        > 0 ==> block!20 is a sprite name pointer

The latter facility allows for icons within a window to have different sprite areas associated with them, which is particularly useful when dealing with sprites in the icon bar (which is shared between many tasks).

Wimp's use of sprites

See the chapter 'Wimp.Colours' for a description of how the Wimp handles sprites in modes with other than 16 colours.