; > &.Doc180.Kernel.ModeExtend

Title:          Mode extensions/1
Version:        0.02
Started:        21-Mar-88
Last updated:   28-Sep-88

In RISC OS 2.00 it is possible to load modules which provide additional
screen modes and additional monitor types. To provide this facility a number
of new services are offered:-

Service_ModeExtension (&50)
---------------------------

in:     R1 = Service_ModeExtension
        R2 = mode number that information is requested for
        R3 = monitor type (or -1 for don't care)

out:    (If not claimed)
        All registers preserved

        (If claimed)
        R1 = 0
        R2 preserved
        R3 -> VIDC list
        R4 -> workspace list

Format of VIDC list (all word values)
-------------------------------------

Offset          Value

0               0 (indicates format of list, to allow for new VIDCs at a
                later date)
4               VIDC base mode
8               VIDC parameter
12              VIDC parameter
.               .
.               .
n               -1

The VIDC base mode is the number of an existing operating system screen mode
which is used to determine the values of VIDC registers not explicitly
mentioned in the list. The VIDC parameters are in the form that would be
written to the hardware ie the top 6 bits specify which register is
programmed and the remainder specify the value to be programmed in that
register. However, bits 6 and 7 of the control register should be set to 0 as
these will be modified by the MOS to take the configured sync and the *TV
interlace setting into account. Similarly the vertical parameters for border
start, display start, display end and border end are modified by the MOS to
take the *TV vertical offset into account.

VIDC parameters below &80000000 are ignored, since these correspond to
palette registers (determined by the workspace base mode) and sound registers
(not part of the display system).

Format of workspace list (all word values)
------------------------------------------

Offset          Value

0               0 (indicates format of list)
4               Workspace base mode
8               Mode variable index
12              Mode variable value
16              Mode variable index
20              Mode variable value
.               .
.               .
n               -1

The workspace base mode is the number of an existing operating system screen
mode which is used to determine the values of mode variables not explicitly
mentioned in the list. The mode variable indices are the same as for
SWI OS_ReadModeVariable.

Note: for the palette to be set properly, a workspace base mode should be
chosen which has the appropriate palette.

When the service is received, the module should check that R2 contains a mode
that it knows about and that R3 holds a monitor type that is suitable for
that mode. If not, the service should be passed on. If R3 holds -1 then the
MOS is making a general enquiry about that mode (eg to determine the attributes
of a sprite defined in that mode) so the module should only check R2.

Note that it is possible for a mode to have two or more different sets of
VIDC parameters for different monitor types, but the workspace parameters
MUST be the same, as the mode number is used as an identifier in sprites and
in calls such as OS_ReadModeVariable.


Service_ModeTranslation (&51)
-----------------------------

in:     R1 = Service_ModeTranslation
        R2 = mode number that requires translation
        R3 = monitor type

out:    (If not claimed)
        All registers preserved

        (If claimed)
        R1 = 0
        R2 = substitute mode
        R3 preserved

This service is offered during a call to OS_CheckModeValid or a screen mode
change, if the selected mode is not available with the current monitor type
(this having been ascertained by offering Service_ModeExtension) and the
monitor type is not one known to the MOS (ie not in the range 0..3). If the
monitor type passed in R3 is known to the module, then the module should
discover what the attributes of the mode in R2 are (by calling
ReadModeVariable) and then choose a mode which is suitable for this monitor
type and is closest in attributes to the selected mode. This mode number
should be returned in R2.

Service_PreModeChange (&4D)
---------------------------

in:     R1 = Service_PreModeChange
        R2 = selected mode (before possible translation)

out:    (Case 1)
        All registers preserved
        This is the normal action for a module which does not want to
        interfere.

        (Case 2)
        R1 = 0 (service claimed)
        R0 = 0
        This implies that the module does not want the mode change to take
        place, and has taken an alternative action.

        (Case 3)
        R1 = 0 (service claimed)
        R0 -> error block
        This implies that the module does not want the mode change to take
        place, and wishes to return the error pointed to by R0

        (Case 4 - possibly to be removed)
        R1 preserved
        R2 = new mode
        This implies that the module wants to substitute a mode for the
        specified mode. This is not a very good way of doing it, as other
        modules further down the chain will be offered the service with this
        new mode. The Service_ModeTranslation mechanism described above should
        be used by modules providing new monitor types.