; > &.Doc180.Kernel.VduOutput

Title:          VDU output to sprites/1
Version:        0.07
Started:        11-Jan-88
Last updated:   28-Sep-88

Description of switching VDU output to sprites
-----------------------------------------------

In RISC OS 2.00 it is possible to switch VDU output to act directly on a
sprite, rather than the screen. Thus graphical operations and text printing
plot into the bitmap area of the sprite definition.

At the time output is switched, a save area may also be specified, in which
the VDU context will be saved when output is subsequently redirected away from
the sprite (normally back to the screen). When output to the same sprite is
required, the same save area can be specified again, and the VDU context will
be restored to the state when the sprite was left (eg if a graphics window was
defined when outputting to a sprite and then output was redirected back to the
screen and a new graphics window defined, on returning output to the sprite the
old graphics window will be restored).

If no save area is specified when selecting the sprite, or if the save area is
indicated as uninitialised, then the VDU context will be set to the default
state for the screen mode the sprite was created with (although the size of the
graphics area will be set to the size of the sprite).

In addition, it is possible to switch output to the screen using different
save areas, and thus create multiple screen contexts.

Calls to SWI OS_SpriteOp associated with switching output
---------------------------------------------------------

As is usual for calls to OS_SpriteOp, R0 contains a reason code which falls
into one of three groups:-

a) R0 = (&000 + n) implies the sprite is in the system sprite area;
   R1 is irrelevant, R2 -> sprite name

b) R0 = (&100 + n) implies the sprite is in a user sprite area;
   R1 -> user sprite area, R2 -> sprite name

c) R0 = (&200 + n) implies the sprite is in a user sprite area;
   R1 -> user sprite area, R2 -> sprite control block

1. Switching output to a sprite
-------------------------------

in:     R0 = k * &100 + SpriteReason_SwitchOutputToSprite (&k3C)
        R1, R2 indicate sprite as described above, according to the value of k
        R3 -> save area (must be word aligned)
         0 => no save area

out:    R0-R3 = old state

An uninitialised save area must be marked as such by setting its first word
to zero (once a save area has had variables stored in it, the MOS changes the
first word to a save area designator).

2. Switching output to the transparency mask of a sprite
--------------------------------------------------------

in:     R0 = k * &100 + SpriteReason_SwitchOutputToMask (&k3D)
        R1, R2 indicate sprite as described above, according to the value of k
        R3 -> save area (must be word aligned)
         0 => no save area

out:    R0-R3 = old state


3. Switching output to the screen
---------------------------------

in:     R0 = SpriteReason_SwitchOutputToSprite (&03C)
        R1 irrelevant
        R2 = 0
        R3 -> save area (must be word aligned)
         0 => no save area
         1 => MOS's save area

out:    R0-R3 = old state

The operating system maintains a save area for the screen's context which it
uses by default. However the user is at liberty to specify a different save
area for the screen (to create multiple screen contexts) or to specify no
save area for the screen.


4. Reading size of a suitable save area for a sprite's context
--------------------------------------------------------------

in:     R0 = k * &100 + SpriteReason_ReadSaveAreaSize (&k3E)
        R1, R2 indicate sprite as described above, according to the value of k

out:    R3 = size of required save area (in bytes)


5. Reading size of a suitable save area for a screen context
------------------------------------------------------------

in:     R0 = SpriteReason_ReadSaveAreaSize (&03E)
        R1 irrelevant
        R2 = 0

out:    R3 = size of required save area (in bytes)


Variables included in save area
-------------------------------

ECF patterns, BBC/native ECF flag, ECF origin

Dotted line pattern and length, and current position in pattern

Graphics foreground and background actions, colours and tints

Text foreground and background colours and tints

Graphics and text window definitions

Graphics origin

Graphics cursor and 2 previous positions

Text cursor position (and input cursor position)

Vdu status (VDU 2 state, page mode, windowing, shadowing, VDU 5 mode,
 cursor editing state, VDU disabled)

Vdu queue and queue ptr

Mode variables are reconstituted from the sprite mode number or the display
mode number as appropriate

Character sizes and spacings

Changed box coordinates and status

Wrch destinations flag

Spool handle

