Copyright M-) Acorn Computers Ltd. 1993 0197,290/FS Issue E **Live**
Medusa Screen Mode Selection API Functional Specification
=========================================================
-----------------------------------------
| Drawing No : 0197,290/FS |
| Issue : D **Live** |
| Date : 7th April 1993 |
| Author : Tim Dobson |
| Sheets : |
| Last Issue: D |
-----------------------------------------
Contents
--------
1 History
2 Outstanding issues
3 Overview
4 Technical Background
4 1/2 User Interface
5 Programmer Interface
5.1 New SWIs
5.1.1 OS_ScreenMode
5.2 Extensions to existing SWIs and commands
5.2.1 OS_ReadModeVariable
5.2.2 OS_CheckModeValid
5.2.3 OS_Byte (&87)
5.2.4 ColourTrans SWIs
5.2.5 Wimp_SetMode
5.2.6 *WimpMode
5.3 Extensions to Service_ModeExtension
5.4 Extensions to Service_ModeTranslation
5.5 New service call Service_EnumerateScreenModes
5.6 New module: ScreenModes
5.6.1 Overview
5.6.2 *LoadModeFile
5.6.3 MonitorType 7 (File)
5.7 Changes due to hardware differences on Medusa platforms
5.7.1 Monitor lead ID
5.8 Grey-scale modes
5.9 Gamma correction
5.10 External video cards
6 Data formats
6.1 File format for filetype ModeInfo
7 Development Test Strategy
8 Future enhancements
Appendix A (in separate file)
Screen mode timings
1. History
==========
TMD 11-Feb-93 Started
Issue A TMD 24-Feb-93 Released for initial review
---------------------------------------------------------------------------
Issue B TMD 26-Feb-93
Updated with comments from JRoach, AGlover, CWhyte, MChallis
---------------------------------------------------------------------------
Issue C TMD 07-Apr-93
Issue about SWI number for OS_ScreenMode removed - spec now says it will
be allocated later.
Description of mode selector flags modified and expanded.
Description of extensions to Service_ModeExtension expanded.
Clarified that VIDC lists type 0 and 1 are not supported (ie existing mode
extend modules will not work).
Removed remaining references to Jordan.
Description of mode selector flags and mode provider flags expanded.
Format of block returned from screen mode enumeration service and SWI has
been changed to include size field.
Section added about default values of mode variables.
Section added about grey scales.
Section added about gamma correction.
Section added about external video cards.
Appendix A containing screen mode timings added.
Mode selector format changed to include desired frame rate, as is
enumeration block format.
Default monitor type for monitor ID 0 changed to 3 (VGA) (was 4 (SVGA)).
DAC control bit added to video control parameters list (and entries
renumbered).
Extensions to Service_ModeTranslation added.
Section on new monitor types removed.
Section on ScreenModes module added.
Section on filetype "ModeInfo" format added.
Screen mode is now always returned in the format it was selected.
New OS_ScreenMode reason code added to select current monitortype.
Section added on changes to ColourTrans SWIs.
Section added on changes to Wimp_SetMode.
Section added on changes to *WimpMode.
Service_ModeExtension and Service_EnumerateScreenModes changed to include
passing in of total video memory size, and registers for OS_ScreenMode(2)
updated to keep in step.
---------------------------------------------------------------------------
Issue C TMD 07-Apr-93
Add mode name to ModeInfo file and corresponding field in
Service_EnumerateScreenModes records.
Extend test strategy to match changes in issue C
Add section on !Configure changes - sorts out last two outstanding issues
---------------------------------------------------------------------------
Issue D JSR 23-Apr-93
Final tidying up for AMR:
Notes on how to select shadow screens
---------------------------------------------------------------------------
Issue E JSR 26-May-93
Input from implementation:
OS_ScreenMode SWI number is &65
Frame rate in mode specified may be given as -1 to allow a first match
scheme
Modification to Service_EnumerateScreenModes to allow partial enumeration
of screen modes
Correction to OS_ScreenMode reason 3
---------------------------------------------------------------------------
2. Outstanding issues
=====================
3. Overview
===========
In RISC OS 2 and 3, screen modes are selected by sending the VDU sequence
(22, n) where n is the screen mode number. Since this interface is a byte
wide interface, n is limited to 8 bits. Since bit 7 is interpreted as a
"shadow mode" indicator, there are only in fact 128 different screen modes
available by this interface. Of these 64 are allocated to Acorn, the others
being available for third parties or the user.
This creates a problem for the Medusa version of RISC OS, as VIDC20 supports
higher resolution screen modes, and a wider selection of pixel depths (ie
16- and 32-bit per pixel modes). If all the resolutions we wish to support
on Medusa were represented by one new mode number for each available pixel
depth, the number of screen modes would exceed 64 (RISC OS 3.1 already uses
modes 0 to 46).
Therefore a new way of selecting modes is provided.
In addition, the RISC OS mode extension system needs to be modified. In RISC
OS 2 and 3, modules which provide extra screen modes currently respond to
services, returning lists which contain values to be programmed into VIDC1.
Since VIDC20 is capable of generating screen modes which VIDC1 cannot, a new
list format is necessary to take advantage of these capabilities.
Due to resourcing constraints, the code to support old-style formats will
not be written for Medusa.
Because the range of line frequencies available on monitors varies so
widely, it has been decided that rather than create a plethora of new
monitortype numbers to cope with this, a new ScreenModes module will be
created, which reads the timings for the full set of screen modes from a
file on the hard disc.
A new file format has been defined for this.
4. Technical background
=======================
A "mode selector" is a word-aligned structure of the following format:-
Offset Value
0 mode selector flags
bit 0 = 1 (always)
bits 7..1 = format specifier (zero for this format)
bits 31..8 = other flags (must be zero currently)
4 x-resolution (in pixels)
8 y-resolution (in pixels)
12 pixel depth (0=1bpp,1=2bpp,2=4bpp,3=8bpp,4=16bpp,5=32bpp)
16 frame rate (in Hz) (-1 means 'use first match')
20 pairs of words (mode variable index, value)
(there may be any number of these, including zero)
n -1 (terminator)
(The mode variable indexes mentioned here are the same numbers which specify
mode variables in SWI OS_ReadModeVariable).
A "mode specifier" is either a mode number (in the range 0..255) or a
pointer to a mode selector (>255). The range of the value determines which.
4 1/2. User Interface
=====================
The user interface described here is that of the Screen dialogue of
!Configure. Please find attached the file Templates which gives the
replacement Screen dialogue. From top to bottom there are 5 fields:
Monitor type: this selects the type of the monitor attached to the computer.
Menuing here will bring up a menu with all the monitor types available
listed on it. The menu will be:
+-------------------------+
| Monitor type |
+-------------------------+
| CGA (15kHz) |
| Multiscan (15kHz-35kHz) |
| VGA (31kHz) |
| SVGA (31kHz-35kHz) |
| SVGA (31kHz-48kHz) |
| XGA (31kHz-64kHz) |
| XGA (31kHz-78kHz) |
| Auto |
+-------------------------+
This being the list of ModeInfo files supplied in the directory
!Configure.Monitors with Auto added to the end. The menu button to the right
of this field will also bring up this menu. The configured monitor will be
ticked, unless the configured monitor isn't one of the !Configure.Monitors
files.
Colours: and Resolution: select the mode in the same way as the mode
selector does (see 0197,254/FS). If monitor Auto is selected then both these
fields will come up 'Auto' - you won't be able to change them and the menus
won't be available.
Blank delay: This works in the same way as the RISC OS 3.1 Blank delay field
in !Configure, except its action is only applied if either of Save or OK is
applied.
Vertical adjust: This is the same as the RISC OS 3.1 Vertical adjust field
except that it isn't writeable and its effect is only applied if either of
Save or OK is pressed.
Below these fields are the following action buttons:
Default: This causes machine default values to be filled in. The default
values will match the factory shipped values.
Save: This saves the settings such that when the machine restarts it comes
up with the chosen values.
Cancel: Left click - quit the box, no further action. Right click - fill in
the values in force when the box was last openned/Saved/OKed.
OK: Apply the values in the box, but don't save them.
[ Implementation details:
A predesktop Obey file should be constructed to action the saved values -
this forms the saving of the values. *LoadModeFile should be used for the
monitor type and *WimpMode for the mode.
To avoid duplication of default setup !Configure should take a copy of the
current configuration if it finds it hasn't already got a copy.
The Monitors directory inside !Configure should contain the ModeInfo files
without any special directory structuring. The file names should be chosen
to give the desired menu ordering.
]
5. Programmer Interface
=======================
5.1 New SWIs
============
5.1.1 OS_ScreenMode (&65)
-------------------------
The SWI number for this call will be allocated at a later date, and the
functional specification updated to reflect the allocation.
This performs various actions relating to screen modes.
On entry, r0 gives a reason code which determines which operation is
performed.
Reason code 0: Select screen mode
On entry: r0 = 0 (reason code)
r1 = mode specifier
On exit: All registers preserved
This selects the given screen mode.
If a mode number 'n' is given, then the existing mechanisms are used to
select this mode, exactly as if VDU 22,n were issued.
If a pointer to a mode selector is given, then any mode variables which
are not specified are given sensible defaults, based on the specified
resolution and pixel depth. Note that the relevant information is copied
away by RISC OS, so mode selector structures need not remain valid after
the call has returned.
If a pointer to a mode selector was given, but the specified mode cannot be
selected for any reason, then an error is always returned. Note that this
is different behaviour from mode selection by number, which can select a
substitute mode in certain cases.
The way that RISC OS works out the mode variables for a given screen mode
is different when a mode selector is used:
When given a mode number, if it is recognised by RISC OS then the mode
variables for that mode are loaded from its internal tables; if it is not
recognised then Service_ModeExtension is issued and the module which
responds to this passes back a workspace list which contains a base mode
(which must be known to RISC OS) and a list of changes to mode variables.
When passed a pointer to a mode selector, however, the mode variables are
initialised to defaults based on the information in the mode selector
block, viz. the x and y resolutions and the pixel depth. Any mode variables
specified in the mode selector block override these defaults.
The default values for these mode variables are as follows:
Variable Default value
ModeFlags 0
ScrRCol (xres >> 3) -1
ScrBRow (yres >> 3) -1
NColour 1, 3, 15, 63, &FFFF, &FFFFFFFF
for pixdepth = 0 to 5 respectively
XEigFactor 1
YEigFactor 1
LineLength (xres << pixdepth) >> 3
ScreenSize ((xres*yres) << pixdepth) >> 3
YShftFactor 0
Log2BPP pixdepth
Log2BPC pixdepth
XWindLimit xres-1
YWindLimit yres-1
Service_ModeExtension still gets issued in the mode selector case, but only
if RISC OS does not know the video timings for the resolutions/pixel
depth/frame rate asked for, and in this case the module responding provides
only timing and other hardware control information, and not any mode
variable values.
See section 5.3 below for further information on changes to
Service_ModeExtension.
Note that in the case where pixdepth=3, the default value of NColour is 63.
This means that by default, the palette in 256-colour modes behaves as it
does on VIDC1-based machines, ie palette entries get modified in groups of
16. This is so that programs which expect the old behaviour will
work without modification in these modes.
To gain access to fully-palette-programmable 256 colour modes, the
following variables should be overridden with these values:-
Variable Value
ModeFlags 128
NColour 255
Under these conditions, all 256 palette entries become programmable,
although the initial palette setting is identical.
You might notice that there is no explicit way of selecting a shadow
screen mode. In order to get this effect the program should ensure there is
sufficient memory in the screen dynamic area before switching screen banks.
If there is sufficient memory then switching banks will work without a
hitch.
Reason code 1: Return mode specifier for current screen mode.
On entry: r0 = 1 (reason code)
On exit: r1 = mode specifier
If the screen mode was selected by mode number, then this call
returns that number, otherwise it returns a pointer to a mode selector.
Reason code 2: Enumerate screen modes.
This call provides a front end to Service_EnumerateScreenModes. It fills in
r3 (the current monitortype), r4 (the memory bandwidth available) and r5
(the total amount of video RAM), and then issues the service. See the
section on Service_EnumerateScreenModes for more details.
On entry: r0 = 2 (reason code)
r2 = enumeration index
r6 = pointer to block to return data into, or 0 to just
count entries
r7 = size of block if r6<>0, or zero if r6=0
On exit: r1 = 0 if service claimed, otherwise r1 non-zero.
r2 = updated enumeration index
r6 = updated block pointer
r7 = size of remaining free area in block
All other registers are preserved.
Note: if r6=0 on entry to this SWI, then no data is returned, but r2 will
have been updated to the number of entries that would have been returned,
and r7 will have been decremented by the number of bytes that would have
been put into the block, therefore -r7 is the size of block that will be
needed to hold all the entries.
Each entry stored is of the following format:-
Offset Value
0 size of entry in bytes (24 for this format)
4 mode provider flags:
bit 0 = 1 (always)
bits 7..1 = mode info format specifier (zero for this
format)
bits 31..8 = additional mode info flags (must be zero)
8 x-resolution (in pixels)
12 y-resolution (in pixels)
16 pixel depth (as per mode selector)
20 frame rate (Hz) (to the nearest integer)
In the future it is possible that different format entries may be returned
by modules, therefore callers of this SWI should check that bits 7..0 of the
mode provider flags contain 1 before extracting the other information in
this block. If these bits contain a different value which is not recognised
by the caller, then the entry should be skipped by adding on the size field
at offset 0. For format checking purposes, bits 31..8 should be ignored.
Reason code 3: Select current monitortype
This call is provided for internal use by the ScreenModes module. It sets
the current monitortype value, which is used by RISC OS when various
services are issued. This call does NOT change the value configured in CMOS
RAM.
On entry: r0 = 3 (reason code)
r1 = monitortype value to set, or
-1 to restore to configured value
On exit: All registers preserved
Note that SWI OS_ReadSysInfo(1) now returns the current monitortype value,
rather than the configured value.
5.2 Extensions to existing SWIs and commands
--------------------------------------------
5.2.1 OS_ReadModeVariable
-------------------------
On RISC OS 3 this call is passed one of the following in r0:
a) mode number, or
b) -1, indicating current screen mode.
For Medusa this has now been extended to one of the following:
a) mode number, or
b) pointer to mode selector, or
c) new format sprite mode word, or
d) -1, indicating current screen mode.
Cases b) and c) are distinguishable because bit 0 of the new format sprite
word is always set, whereas it must be clear in case b) because mode
selectors always start on a word boundary.
5.2.2 OS_CheckModeValid
-----------------------
This call now accepts any mode specifier in r0, not just a mode number. In
addition, the returned substitute mode may be a pointer to a mode
specifier.
5.2.3 OS_Byte(&87) (Read character under cursor, and screen mode)
-----------------------------------------------------------------
This call will now return a pointer to a mode selector, if the current
screen mode was selected that way.
5.2.4 ColourTrans SWIs
----------------------
The following SWIs:-
ColourTrans_ReturnGCOLForMode
ColourTrans_ReturnColourNumberForMode
ColourTrans_ReturnOppGCOLForMode
ColourTrans_ReturnOppColourNumberForMode
previously took a mode number (or -1 for the current mode) as an input
parameter. In all cases they now accept a general mode specifier, or -1.
The following SWIs:-
ColourTrans_SelectTable
ColourTrans_SelectGCOLTable
ColourTrans_ReadPalette
ColourTrans_GenerateTable
previously took a mode number, or -1 for the current mode, or a sprite area
pointer. The sprite area pointer case was distinguished by the value being
greater than or equal to 256 (since mode numbers are only byte quantities).
In all cases they now accept a general mode specifier, or -1, or a sprite
area pointer. This raises the issue of how a pointer to a mode selector is
distinguished from a pointer to a sprite area. However, the first word of a
sprite area contains the size of the sprite area, which must be a whole
number of words, therefore bits 0 and 1 will be clear, whereas the first
word of a mode selector is the flags word which always has bit 0 set, thus
they are distinguishable.
5.2.5 Wimp_SetMode
------------------
This call previously took a mode number in r0 on input. It now accepts a
general mode specifier. In the case of a pointer to a mode specifier, the
WindowManager module makes a copy of the whole structure to use on future
mode changes, not just a copy of the pointer.
5.2.6 *WimpMode
---------------
This command now allows the mode to be specified either as a number, or in
the form of a mode description string, which is a textual form of a mode
selector. This is also reflected in the mode chooser application, which
also allows this form.
The format of this string is described in the Medusa Video
Software Functional Specification (0197,254/FS) from issue 1.08 onwards.
5.3 Extensions to Service_ModeExtension
---------------------------------------
When this service is issued on RISC OS 3, the registers are as follows:-
On entry: r1 = Service_ModeExtension (&50)
r2 = mode number
r3 = monitor type (-1 for don't care)
On exit: All registers preserved if not recognised, else
r1 = 0
r2 is preserved
r3 -> VIDC list (type 0 or 1)
r4 -> workspace list
On RISC OS for Medusa, the registers are as follows:-
On entry: r1 = Service_ModeExtension (&50)
r2 = mode specifier
r3 = monitor type (-1 for don't care)
r4 = memory bandwidth available (in bytes/second)
r5 = total amount of video RAM in system (in bytes)
On exit: All registers preserved if not recognised, else
r1 = 0
r2 is preserved
r3 -> VIDC list (type 3)
r4 -> workspace list if a mode number was passed in, or
r4 = 0 if a pointer to a mode selector was passed in
Note that returning a workspace list is only relevant if a mode number is
passed in - if a pointer to a mode selector is passed in, RISC OS can work
out what the mode variables should be for that mode, therefore there is no
need to return a workspace list, and r4 should be set to zero on exit.
If a pointer to a mode selector is passed in, the module should check that
bits 7..0 of the mode selector flags hold the value 1. If they hold a
different value, this implies that the structure of the rest of the mode
selector may be different, so the module should pass the service on, unless
it recognises the new format.
For format checking purposes bits 31..8 of the mode selector flags should
be ignored, as these will only pass in extra information which may be of
use to some modules.
The mode selector could contain -1 as the frame rate, in which case the
first matching mode should be used.
RISC OS 3 supports two formats (types 0 and 1) of VIDC list (the first
word of the list is the format type). Both these types include values which
correspond directly to VIDC1's register formats.
These formats are NOT supported on Medusa. This means that mode extend
modules for RISC OS 2 and 3 WILL NOT WORK.
A new format list (type 3) is available on Medusa RISC OS, which aims to be
independent of the video controller used. The format is as follows:-
Offset Value
0 3 (format of list)
4 pixel depth (0=1bpp,1=2bpp,2=4bpp,3=8bpp,4=16bpp,5=32bpp)
8 horizontal sync width (in pixels)
12 back porch
16 left border
20 display size
24 right border
28 front porch
32 vertical sync width (in rasters)
36 back porch
40 top border
44 display size
48 bottom border
52 front porch
56 pixel rate (in kHz)
60 sync polarities
bit 0 set => Hsync inverted
bit 1 set => Vsync inverted
bits 2-31 must be zero
NB if composite sync is configured in CMOS, the syncs
will not be inverted
64 video control parameters list
n -1 (terminator)
The video control parameters list which is on the end of this list contains
pairs of words (control parameter index, value), terminated by a -1 word,
which control various additional VIDC registers and bits in registers, as
follows (refer to VIDC20 data sheet for detailed explanations of terms):-
Control Parameter
Index Description Values
1 LCD mode 0 => disable, 1 => enable
2 LCD dual-panel mode 0 => disable, 1 => enable
3 LCD Offset Register 0 0 to 255
4 LCD Offset Register 1 0 to 255
5 Hi-res mode 0 => disable, 1 => enable
6 DAC control 0 => disable, 1 => enable (default)
7 RGB pedestal enables bit0=R, bit1=G, bit2=B
8 External Register [7:0] 0 to 255
9 hclk select/specify See note a) below
10 rclk frequency See note b) below
Notes
-----
a) This value, if non-zero, forces RISC OS to select hclk as its clock
input, and the value itself indicates to RISC OS what frequency is expected
to be coming in on this pin (in kHz). RISC OS will then set up the internal
divider to try to achieve the pixel rate specified in the main body of the
list (normally you would make this the same, so that RISC OS would select
divide by 1). The frequency is also used by RISC OS to compute the FIFO load
position.
If the value is zero, then RISC OS uses rclk or vclk as per normal.
b) This value, if non-zero, tells RISC OS that the frequency coming in on
the rclk pin is not 24MHz, but is in fact the value specified (in kHz). This
knowledge is then used by RISC OS to determine the moduli values for the
specified pixel rate and the FIFO load position. In addition, the value is
stored in VDU variable VIDCClockSpeed, which is read by the sound system to
determine what value to program the Sound Frequency Register with (since the
sound system is driven by rclk).
It is expected that the control parameters list will normally contain no
entries at all for normal video operation - only for special applications is
this needed.
[ Implementation details:
Note: RISC OS needs to compute the moduli for the Frequency Synthesizer
Register, based on the requested pixel rate. This requires that either the
operating range of the VCO is known at assembly time, or some kind of
"biofeedback" code is written which times the output from VIDC using the
vsync input.
]
Two additional parameters are supplied on entry to Service_ModeExtension,
namely the video bandwidth available on the machine, in units of
bytes/second, passed in R4 on entry, and the total amount of video RAM in
the system, in bytes, passed in R5 on entry.
These are useful because the Medusa range of machines encompass a wide range
of video capabilities, from DRAM-only machines through to machines with 1 or
2 Mbytes of VRAM. Supplying this parameter allows a mode provider to check
that a given screen mode at the specified frame rate can be achieved with
the machine's video bandwidth and its amount of video RAM.
A mode provider should only respond to this service if the mode being
selected would use no more video bandwidth than the amount in R4, and no
more video memory than the amount in R5.
[ Implementation detail:
Since it is impossible for the machine to measure the video bandwidth
available, RISC OS will supply one of 3 fixed values, based on whether the
machine is fitted with 0, 1 or 2 Mbytes of VRAM respectively.
]
5.4 Extensions to Service_ModeTranslation
-----------------------------------------
On RISC OS 3 this service passes in a mode number which is unavailable on
the current monitortype, and passes back a substitute mode number.
On Medusa, this is extended to allow the substitute mode passed back in r2
to be an arbitrary mode specifier.
However, the input mode will only ever be a mode number, as a mode change
controlled by a pointer to a mode selector never uses a substitute mode.
5.5 New service call Service_EnumerateScreenModes (reason code &8D)
-------------------------------------------------------------------
The function of this service call is to allow "mode chooser" applications to
find out what resolutions at what pixel depths are available.
Applications should not issue this service call directly - they should
instead call OS_ScreenMode with reason code 2 (see above for details).
On entry: r1 = &8D (reason code)
r2 = enumeration index
r3 = monitor type
r4 = memory bandwidth available (in bytes/second)
r5 = total amount of video RAM in system (in bytes)
r6 = pointer to block to return data into, or 0 to just
count entries
r7 = size of block if r6<>0, zero if r6=0
On exit: r2 = updated enumeration index
r6 = updated block pointer
r7 = updated size of block
This service call provides a means whereby modes can be enumerated. It can
be issued in two ways: the first to find out how many modes there are,
and how much space is needed to store all of them; the second to actually
enumerate them into a buffer. The enumeration form can be done as a
partial enumeration so that a fixed size buffer can be used.
The following descriptions are from the point of view of the caller:
Finding out how many modes there are and how much space they need:
On entry: r1 = &8D (reason code)
r2 = 0 (enumeration index)
r3 = monitor type
r4 = memory bandwidth available
r5 = total VRAM
r6 = 0
r7 = 0
On exit: r2 = -(number of modes)
r7 = -(amount of space needed for them)
other registers preserved
Doing a (partial) enumeration:
On entry: r1 = &8D (reason code)
r2 = number of modes to skip
r3 = monitor type
r4 = memory bandwidth available
r5 = total VRAM
r6 = pointer to block
r7 = size of block
On exit:
Block big enough case:
r1 = &8D
r2 = -(number of modes in block)
r6 = pointer to byte after last filled in byte
r7 = amount of unused space in block
Block too small case:
r1 = 0 (Service_Serviced)
r2 = -(number of modes in block)
r6 = pointer to byte after last filled in byte
r7 = amount of unused space in block
As a client of this service call your algorithm should be:
Repeat
r2 = total number of entries processed so far (ie is 0 first time round)
r6 = pointer to block
r7 = size of block
Call OS_ScreenMode reason 2 (Enumerate screen modes)
Process block contents (from block to r6 returned from OS_ScreenMode)
Until r1 returned from OS_ScreenMode was non-0
As a module which wishes to respond to this service call your algorithm
should be:
For each mode that wants to be returned
If r2 > 0 Then
do nothing, ie skip it
Else
If r6<>0 Then
(enumeration case - filling in block)
If r7 >= entrysize Then
store entry at r6
r6 += entrysize
Else
(not enough space for next mode)
r1 = 0 (Service_Serviced)
Return (service call claimed)
EndIf
EndIf
r7 -= entrysize
EndIf
r2 -= 1
Next
Return (service call passed on)
The registers are updated as follows:-
r1 = preserved (block didn't overflow) or 0 (block
overflowed)
r2 = updated enumeration index (decremented by 1 for each
entry considered)
r3-r5 are preserved
r6 = block pointer, updated to point after all entries
stored in the block (or stays at 0)
r7 = size of remaining free area in block (or gets
decremented by amount of space needed by the entries
that would have been put into the block had r6 been
non-0)
The module should return information on all modes that it provides that work
on the specified monitor type and which require no more than the specified
memory bandwidth, and no more video memory than the specified amount.
For each such screen mode, the module stores the following information in
the block:-
Offset Value
0 size of entry in bytes (24 for this format)
4 mode provider flags:
bit 0 = 1 (always)
bits 7..1 = mode info format specifier (zero for this
format)
bits 31..8 = additional mode info flags (must be zero)
8 x-resolution (in pixels)
12 y-resolution (in pixels)
16 pixel depth (as per mode selector)
20 frame rate (Hz) (to the nearest integer)
24 mode name. This will be 0-terminated and then padded with 0s
until it is word aligned. For unnamed modes this
will simply be a single word whose value is 0.
5.6 New module: ScreenModes
---------------------------
5.6.1 Overview
--------------
VIDC20 supports a much wider range of monitors than did VIDC1.
Because the range of line frequencies available on monitors varies so
widely, it has been decided that rather than create a plethora of new
monitortype numbers to cope with this, a new ScreenModes module will be
created, which reads the timings for the full set of screen modes from a
file on the hard disc.
Files containing screen mode information will have the filetype "ModeInfo".
The number for this will be allocated at a later date, and the functional
specification updated to reflect the allocation.
The format for these files is described in section 6.1 below.
5.6.2 *LoadModeFile
-------------------
Syntax: *LoadModeFile <filename>
This command loads a file of type "ModeInfo" into memory, and if the file
contains valid information, sets the current monitortype to 7 (file) (using
OS_ScreenMode(3)). This then makes available all the screen modes defined
in the file, while removing all modes defined in any previously loaded
file.
5.6.3 MonitorType 7 (File)
--------------------------
This new monitortype is reserved for exclusive use by the ScreenModes
module. When a file is loaded by the module, the current monitortype is set
to this, which effectively replaces all the screen modes defined in the ROM
by the modes defined in the file, because the kernel does not respond to
this monitortype.
5.7 Changes due to hardware differences on Medusa platforms
-----------------------------------------------------------
5.7.1 Monitor lead ID
---------------------
In order to reduce cost, Medusa platforms can only detect bit 0 of the
monitor lead ID.
The tables below show the old and the new mappings from monitor lead ID to
monitor type, mode and sync type.
Mapping for existing machines
-----------------------------
ID Bits
3210 Description Monitor Screen Sync
type mode type
X101 Mono VGA 3 27 0
X110 Colour VGA 3 27 0
X010 Colour SVGA 1 27 0
XH11 Comp.Multisync 1 27 1
X11H TV standard 0 12 1
Other ? 0 12 1
Mapping for Medusa series machines
----------------------------------
ID Bit
0 Description Monitor Screen Sync
type mode type
0 VGA capable 3 27 0
H TV standard 0 12 1
1 TV standard 0 12 1
Other TV standard 0 12 1
Because of the existence of the ScreenModes module, determining the monitor
type from the monitor lead ID is much less important.
Effectively the ID is only useful in setting up an initial screen mode,
before the ModeInfo file for the user's monitor has been loaded.
5.8 Grey-scale modes
--------------------
The RISC OS kernel will not provide any extra support for grey-scale modes.
The WindowManager module will be extended to allow the selection of 16- and
256-level grey scale modes in the desktop - this will be implemented by the
Wimp explicitly programming the palette after the mode change. In the
256-level case it will have to select a 256-colour mode with a fully
programmable palette by the means described in section 5.1.1.
5.9 Gamma correction
--------------------
RISC OS now allows an application to supply tables to perform gamma
correction on RGB values being programmed into the palette. There are three
256-byte tables, one for each of red, green and blue.
Before being output to VIDC, the red component of the physical colour (in
the range 0 to 255) is used as an index into the red gamma correction
table - the value obtained is the gamma corrected red value to be
programmed into VIDC.
In a similar fashion the green and blue components are looked up in their
respective tables.
The contents of the tables are set up by a call to PaletteV, as follows:-
On entry: r0 -> gamma-correction table for red (must be word-aligned)
r1 -> gamma-correction table for green (--------""--------)
r2 -> gamma-correction table for blue (---------""--------)
r4 = 9 (reason code)
On exit: r4 = 0 => the video drivers support gamma correction, and
the tables have been copied into system workspace
r4 <> 0 => the video drivers do not support gamma correction
5.10 External video cards
-------------------------
No additional support is provided in RISC OS for video cards. It is
believed that the existing interfaces provide enough hooks for these to be
added.
The main requirement that an external video card has is to be able to
redirect RISC OS's bitmap to an area of RAM on an expansion card. This
would be in EASI space, and consequently it can allow full 32-bit access.
This means that provided that RISC OS's screen address can be changed to
point to somewhere in EASI space, the normal graphics primitives will work
correctly.
It is envisaged that the mechanism used to change screen address would be
to switch VDU output into a sprite, where the sprite is situated in EASI
space. This would require that there is some RAM immediately before the
start of the bitmap, to hold the sprite area and sprite headers.
An additional complication is the mouse pointer: its position can be polled
on vsync by the external card drivers, and then whatever hardware on
the card is producing the screen pointer can be updated with its new
position.
6. Data formats
===============
6.1 File format for filetype ModeInfo
-------------------------------------
Files of type ModeInfo contain definitions of all the screen modes
available on a particular monitor. The mode definitions are written in
plain text, so the files can be edited using !Edit.
Spaces and tab characters (&09) are allowed anywhere in the file except in
the middle of keywords or numbers.
Lines starting with any number of spaces followed by the hash character "#"
are treated as comments and ignored.
The file consists of the following two lines:
file_format: <format>
monitor_title: <title>
followed by any number of mode definitions, where
<format> must be 1 for this format file
<title> is a textual description for this type of monitor
and a mode definition is as follows:
startmode
x_res: <x-resolution>
y_res: <y-resolution>
h_timings: <hsync>, <hbpch>, <hlbdr>, <hdisp>, <hrbdr>, <hfpch>
v_timings: <vsync>, <vbpch>, <vtbdr>, <vdisp>, <vbbdr>, <vfpch>
pixel_rate: <pixel rate>
sync_pol: <sync polarities>
mode_name: <mode name>
endmode
where
<x-resolution> is the number of pixels displayed across the screen
<y-resolution> is the number of displayed rasters
The h_timings line controls the horizontal timings, as follows:
<hsync> is the width of the hsync pulse in pixels
<hbpch> is the width of the horizontal back porch in pixels
<hlbdr> is the width of the left hand border in pixels
<hdisp> is the number of displayed pixels horizontally (normally the same
as <x-resolution>)
<hrbdr> is the width of the right hand border in pixels
<hfpch> is the width of the horizontal front porch in pixels
The v_timings line controls the vertical timings, as follows:
<vsync> is the width of the vsync pulse in rasters
<vbpch> is the width of the vertical back porch in rasters
<vtbdr> is the width of the top border in rasters
<vdisp> is the number of displayed rasters vertically (normally the same
as <y-resolution>)
<vbbdr> is the width of the bottom border in rasters
<vfpch> is the width of the vertical front porch in rasters
<pixel rate> is the pixel rate required, in kHz
<sync_polarities> is a number indicating what kind of sync signals are
required, as follows:
0 => hsync normal, vsync normal
1 => hsync inverted, vsync normal
2 => hsync normal, vsync inverted
3 => hsync inverted, vsync inverted
4 => composite syncs
<mode name> is a textual name for the mode for use in menus and such. The
mode name field must be present, although the <mode name> itself may be
blank.
Note: VIDC20 imposes restrictions on the above parameters. In particular,
all the horizontal timing values must be multiples of 2, and the horizontal
total = hsync + hbpch + hlbdr + hdisp + hrbdr + hfpch must be a multiple of
4. See the VIDC20 specification for details of further restrictions.
7. Development test strategy
============================
PHTester scripts will be constructed to test the following SWIs/reason
codes:
OS_ScreenMode
Reason 0
Mode numbers 0-255 will be tried
A valid mode selector will be constructed and each of its
parameters will be adjusted individually to be:
Completely out of range
Just out of range
Just in range
The mode selector with all parameters in range will also be tried
Reason 1
For all the above selections reason 1 will be issued and the results
displayed assuming the correct behaviour of reason 1.
Reason 2
With the machine set up with a known set of screen modes this reason will
be issued and the results displayed assuming correct behaviour.
Reason 3
This reason will be issued with normal values and with -1 and the results
displayed.
OS_ReadModeVariable
Two different mode numbers and five different mode specifiers will be
tried. All mode variables will be obtained using all of these. The
resulting mode variable values will be displayed. The mode specifiers must
exercise 16 and 32bpp modes as well as 4 and 8 bpp modes.
OS_CheckModeValid
The same set of mode selectors as OS_ScreenMode was tried with will be
tried on OS_CheckModeValid. The results will be displayed.
OS_Byte (&87)
The same set of mode selectors as OS_ScreenMode was tried with will be
tried on OS_Byte (&87). The results will be displayed.
Service_ModeExtension
The same set of mode selectors as OS_ScreenMode was tried with will be
tried on Service_ModeExtension. The results will be displayed. This will
be performed with a known machine setup.
Service_EnumerateScreenModes
With a given machine setup Service_EnumerateScreenModes will be issued to
obtain all possible screen modes. This will also be issued with a limited
block size to test that the block doesn't get overflowed.
A responder to Service_EnumerateScreenModes will be written which will
generate each of the control indexes with each of the valid values (for
small range indexes) and control values at each end of the ranges and in
the middle (for wide range values such as LCD Offset Register 0).
ColourTrans SWIs
These will be tried with the range of mode specifiers prepared above as
well as with the full range of mode numbers. The sprite area pointer tests
are expected to be exercised as part of the general video enhancements
work.
Wimp_SetMode and *WimpMode
*WimpMode will be tried with mode numbers - range checking will be tested,
and mode description strings - a reasonable variety tried.
Wimp_SetMode will be tested to make sure it generates mode specifiers
correctly. All mode description string parameters will be tried
independantly and then mixed in a number of reasonable varieties.
Service_ModeTranslation
A module will be written to substitute a fixed mode specifier. This will
check for correct response to this service call.
*LoadModeFile
Valid ModeInfo files for all the RISC OS 3 monitor types will be prepared
and tried. One of these will be corrupted with duff field values (each
field will be corrupted on its own) and tried on *LoadModeFile.
Monitor ID
CGA, MultiSync, VGA and SVGA monitors will be tried to ensure the monitor
ID algorithm gives a usable screen mode.
Gamma Correction
A BASIC application to generate gamma correction tables will be written to
try this feature. This will be supplied in the Diversions directory.
User Interface
A mouse script will be prepared to exercise this part of !Configure.
All buttons will be pressed with both click and adjust. This will be tried
with a sensible Monitors directory as well as an empty one and a full one.
It will be tried with both and absent and present defaults file inside
!Configure. It will be tried with the configured setting being one of
!Configure's files and with it being another file.
8. Future enhancements
======================
With the interfaces described above, it is possible to create a module
which reads screen mode parameters from a file on initialisation. We would
probably want to include some kind of editor which allows the user to test
out new modes she has created.
Medusa RISC OS does not understand VIDC lists type 0 or 1 returned from
Service_ModeExtension. This may be added at a later date.
-- End of screen mode selection API --