Introduction and Overview
The SWI OS_ScreenMode SWI has been updated to perform a number of additional functions since those documented within RISC OS PRM 5a. These are primarily in the areas of acceleration and multi-display support. The full list of OS_ScreenMode reason codes is as follows :
| Reason | Operation |
|---|---|
| 0 | Select mode by number or specifier |
| 1 | Return current mode |
| 2 | Enumerate modes |
| 3 | Select monitor type |
| 4 | Configure acceleration |
| 5 | Perform screen cache clean |
| 6 | Force screen cache clean |
| 7 | Count number of screen banks available |
| 8 | Select display bank |
| 9 | Select VDU driver bank |
| 10 | Copy between banks |
| 11 | Select display device |
| 12 | Read details about display device |
| 13 | Decode mode string to mode specifier |
| 14 | Encode mode specifier as mode string |
| 15 | Select mode by string |
The following additional calls are reserved for display drivers and their support code :
| Reason | Operation |
|---|---|
| 255 | Register display driver |
| 254 | Deregister display driver |
| 253 | Read maximum display driver |
Technical Details
VSync handling
The display driver should only enable VSync interrupts and call the VSync dispatch routine once it has been selected through the VideoV 'select display' entry point. When another display device is selected the driver should release and disable its interrupts. On receipt of an interrupt the driver should clear the interrupt flag and call the VSync dispatch function. The VSync dispatch routine is described under VSyncDispatch.
Display device descriptor block
The display device descriptor block is a tag/value block which is used to describe the features, capabilities and other information for a display device. The tag for each block is a 4 byte word, interpreted as follows :
| Bit(s) | Meaning | |
|---|---|---|
| 0-23 | Identifier number | |
| 24-31 | Length of the value, in words, excluding the tag word | |
The following identifiers are defined :
| Identifier | Meaning |
|---|---|
| 0 | End of tag list. 0 words long. This tag indicates that no further tags are present. |
| 1 | Device name. Variable number of words. This tag provides a zero-terminated string identifier to associate with this device. This is NOT a user-specified display device descriptor. It is the device descriptor unique to the hardware. Values for this might be 'VIDC', 'ViewFinder', 'SM501', or similar. Where possibly multiple devices are available (eg ViewFinder podules) it is strongly recommended that the name be suffixed by a hash followed by the unique sequence identifier (eg 'ViewFinder#0'). The sequence identifier need not be a decimal number, but it should be unique for the instance of the hardware - no two identifiers should be present at any one time. For a USB or network device, a logical location might be specified. |
| 2 | Features word. 1 word long initially (multiple words may be defined in future and should be assumed to be zero where not specified and not faulted where not understood). This tag provides a flags word describing the features provided by the display device. The following bits are allocated within the features word: no bits currently defined. |
| 3 | Display format capabilities word. Variable length. This tag provides a list of the depths which the driver is capable of supporting. One word is used for each display format: 0 = 1bpp, 1 = 2bpp, 2 = 4bpp, 3 = 8bpp, 4 = 16bpp, 5 = 32bpp, 6 = CMYK (matches with Sprite ordering), 7 = YUV, 8 = 16bpp reverse bit order. Other values are undefined. Values 6-8 are not expected to be supported by the operating system as yet. |
| 4 | Bandwidth limitations. 1 word long. This word defines the limitations on bandwidth for any mode selected. This value should be 0 to treat each mode selection on its merits in VetMode. FIXME: The details of the bandwidth limitation values need to be documented. |
| 5 | Physical memory limitations. 1 word long. This word defines the amount of memory available to the display system. This value is used to validate mode selection. |
| 6 | Expected mode alignments. 2 words long. These words define the x and y alignments expected, in bytes and lines, by the display driver. For example, if the display driver expects all mode selections to be on quad-word alignments, and that modes be a multiple of 32 lines, the values would be 16,32. The OS does not allow modes to have line lengths which are less than word-aligned. Values may be 0 to treat each mode selection on its merits in VetMode. This value is used to validate mode selection, and may provide mode substitutions. |
| 7 | Device model. Variable length. This tag is intended to provide a means by which the driver can provide more specific information about the model of the hardware that it is driving. It is intended that it be used to describe the particular hardware in order that it can be displayed to the user. This can allow the user to better describe any problems to suppliers. |
| 8-&7FFFFF | These tag values are undefined. |
| &800000-&FFFFFF | Display device specific information. Variable length. These tags are specific to the named hardware device. In order to interpret these values, clients MUST check that the named hardware device matches that of a known value. |
Mode strings
The mode string can take the general form specified in PRM5a-103. However, this has been extended to allow for other features which are now provided by the graphics system. The general form of the string is a space (or, less commonly, comma) separated sequence of character tagged strings. The full syntax currently supported is :
| Tag | Meaning |
|---|---|
| X# | X resolution in pixels |
| Y# | Y resolution in pixels |
| C# | Number of colours (# = 2, 4, 16, 64, 256, 32T, 32K, 16M) |
| G# | Number of greys (# = 4, 16, 256) |
| T# | Teletext mode, with specified number of colours (# as C) |
| EX# | X eigen factor (# = 0, 1, 2, 3) |
| EY# | Y eigen factor (# = 0, 1, 2, 3) |
| F# | Frame rate in Hz |
| TX# | Teletext display width in characters |
| TY# | Teletext display height in characters |
# represents a decimal number, possibly suffixed by a magnitude.
In addition, a base mode number may be specified followed by the parameters to modify, for example "28 C32K" for a 16bit colour version of the mode 28 resolution.
The resolution (X, Y) and number of colours (C, G or T) are mandatory. C64 is used to select old style VIDC 1 modes.
Under earlier versions of the Operating System (Select 3 and earlier), the desktop display manager tool used C256 to select a 64 colour mode. This has been changed. When C256 is selected a 256 colour mode is now used.
PaletteV
In addition to the extensions provided within RISC OS 3.5 for bulk palette changes and gamma correction the PaletteV reasons have been extended with explicit calls for the managing the video controller's power and for managing the screen's state. These calls were initially added for portable devices and may be useful in the future to provide additional power management functions.
SWI Calls
Client SWIs
The following reason codes are for use by clients.
| R0 | = | 0 (reason code) |
| R1 | = | Mode number, or mode specifier |
This SWI is used to select a screen mode for the current display. Consult PRM 5a 134.
| R0 | = | 1 (reason code) |
| R1 | = | Mode number, or pointer to read only mode specifier |
This SWI is used to read the screen mode for the current display. Consult PRM 5a 137.
| R0 | = | 2 (reason code) |
| R1 | = | Mode number, or pointer to read only mode specifier |
This SWI is used to enumerate the screen modes available. Consult PRM 5a 138.
| R0 | = | 3 (reason code) |
| R1 | = | Monitor type |
This SWI is used to change the monitor type in use by the system. The ScreenModes module uses this to force its defined screen modes. It is reserved for internal use.
| R0 | = | 4 (reason code) | |||||||||||||||
| R1 | = | Flags, or -1 to read current value:
| |||||||||||||||
| R2 | = | Number of VSyncs between automatic screen cleaning (1-3), or -1 to read current value | |||||||||||||||
| R1 | = | New flag state |
| R2 | = | New number of VSyncs between automatic screen cleaning |
This SWI is used to configure the acceleration in use by the current display driver.
| R0 | = | 5 (reason code) |
This SWI is used to clean the cache for the screen if necessary and not disabled.
| R0 | = | 6 (reason code) |
This SWI is used to clean the cache for the screen if necessary, whether disabled or not.
| R0 | = | 7 (reason code) |
| R1 | = | Number of available screen banks |
This SWI returns the number of screen banks which the current display driver is capable of providing for the current screen mode. The number of banks may change with system use depending on the driver. Drivers may allocate space in order to cache private data, or for other purposes, and this may affect the number of banks which are available. It is not possible to determine the number of banks that will be available in a mode because the requirements on the driver may change when changing to that mode.
| R0 | = | 8 (Select or read Display bank), 9 (Select or read Driver bank) |
| R1 | = | Bank number (1..maxbank) or 0 to read currently selected bank |
| R1 | = | Previous bank number |
| R2 | = | New bank number |
| R3 | = | New bank address |
These SWIs (reason codes 8 and 9) are used to either read or select the bank in use for the display or the VDU drivers. It performs the same operation as OS_Byte 112 and 113 (those calls are now directed to these OS_ScreenMode reason codes) but provides additional information. It is recommended that clients use the new OS_ScreenMode calls in preference to the older OS_Byte calls. If the bank number specified is out of range for the current driver (or its current memory configuration) the last available bank will be selected.
| R0 | = | 10 (reason code) |
| R1 | = | Source bank (1..maxbank) |
| R2 | = | Destination bank (1..maxbank) |
This SWI is used to copy the entire contents of a screen bank to another bank. The banks specified need not be the current or display banks. The copy operation may be accelerated where drivers are capable of this.
| R0 | = | 11 (reason code) |
| R1 | = | Display number, or -1 to read current number |
| R1 | = | Previous (or current, if reading current number) display number |
This SWI is used to either select a new display device or to read the currently configured display device.
| R0 | = | 12 (reason code) |
| R1 | = | Display number, or -1 for current display |
| R2 | = | Display descriptor identifier to read, or 0 to return entire descriptor |
| R3 | = | Pointer to buffer to fill |
| R4 | = | Size of buffer, or 0 to read size of buffer required |
| R4 | = | Size of data written, or size of buffer needed; 0 if no such identifier exists within the descriptor |
This SWI is used to read details from the display device descriptor used during registration of the driver. Clients which need to know details about the display system which are not supplied through the standard APIs may use this call to read the descriptor directly.
| R0 | = | 13 (reason code) |
| R1 | = | Pointer to mode string |
| R2 | = | Pointer to mode specifier to fill in |
| R3 | = | Size of mode specifier |
| R0 - R3 | = | Preserved, or error if failed to convert |
This SWI is used to convert a mode string into a mode specifier. See the section on 'Mode strings' above for more details. If the specifier block is not large enough for the mode specifier an error will be returned. Because of the differences in the specifier string due to installed extensions, it is not possible to return the expected size of the specifier. Clients should expect to use at least 4 additional mode variables (NColours, Mode Flags, X Eigen Factor, Y Eigen Factor) in addition to the mode specifier header and terminator. Mode numbers may be given as a prefix to the string in order to base a new mode on a pre-existing mode.
Where mode numbers are used the closest mode string will be returned. In particular the old style modes where special mode flags are set (bits 0-6) will be returned with a string which describes the base mode only without those special features.
| R0 | = | 14 (reason code) |
| R1 | = | Pointer to mode specifier |
| R2 | = | Pointer to mode string to fill in |
| R3 | = | Size of mode string |
| R3 | = | Negative size of buffer required, if not big enough; 0 if string was filled in |
This SWI is used to encode a mode string from a mode specifier. It performs the opposite translation to that of OS_ScreenMode 13. Because of limitations in the mode string format (some variables are not encoded fully within the string) the operation may not be symmetric.
| R0 | = | 15 (reason code) |
| R1 | = | Pointer to mode string |
This SWI is used to select a mode given a mode string. Internally this is implemented as a conversion to a mode specifier (OS_ScreenMode 13) and mode selection (OS_ScreenMode 0), and is provided for convenience.
Display Driver SWIs
The following reason codes are for use by display drivers and their support code.
| R0 | = | 255 (reason code) |
| R1 | = | Pointer to display device descriptor block |
| R0 | = | Display number allocated |
| R1 | = | Pointer to VSync dispatch routine |
| R2 | = | R12 workspace pointer for VSync dispatch routine |
| R3 | = | 1 to select display, 0 to perform no action on return |
This SWI is called by display driver modules to register a new display driver as being available during its initialisation, after claiming vectors. Drivers should store the display number allocated such that they may be triggered when they are called on VideoV.
If the display allocated was previously selected, or was configured as the default, the Kernel will return 1 to indicate that the display should be selected. Drivers should call OS_ScreenMode 11 (Select display device) to select the newly registered device. If an error is returned from this call the driver may decide to select an alternative screen mode to use with OS_ScreenMode 0 (Select mode).
If no suitable mode can be selected the driver should deregister itself and shut down.
| R0 | = | 254 (reason code) |
| R1 | = | Display number |
| R0 - R1 | = | Preserved |
This SWI is used by a device driver on finalisation (or at any other point) to indicate that the display driver is no longer available. It should deregister itself in this manner after releasing VideoV.
| R0 | = | 253 (reason code) |
| R1 | = | Maximum display number |
This SWI is used to read the highest display number allocated by the video system. Display numbers increase from 0 and thus a complete list of the drivers available can be read by iterating from 0 to the number returned from this call.
Entry Points
| R0 | = | Display number to generate VSync for |
| R12 | = | Workspace pointer for VSync dispatch routine |
| R0 - R12 | preserved | |
The VSync dispatch routine is called by a display driver on receipt of a VSync interrupt for a display which has been selected.
Software vectors
| R0 | = | 0 to uninvert, 1 to invert |
| R4 | = | 10 (reason code) |
| R4 | = | 0 if claimed |
This vector is called to set the inversion state of the output, specifically intended for use with LCD panels. It is not implemented within current versions of RISC OS.
| R4 | = | 11 (reason code) |
| R4 | = | 0 if claimed |
This vector is called to cause the display to be dimmed. Its parameters are not defined and it is not supported by current versions of RISC OS.
| R4 | = | 12 (reason code) |
| R4 | = | 0 if claimed |
This vector is called to power down the video hardware for the current display driver. The use of this call should be restricted to necessary circumstances.
| R4 | = | 13 (reason code) |
| R4 | = | 0 if claimed |
This vector is called to enable power to the video hardware for the current display driver. The use of this call should be restricted to necessary circumstances.