|
OS_ScreenMode changes
The 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 :
OS_ScreenMode 0 - Select mode by number or specifier
OS_ScreenMode 1 - Return current mode
OS_ScreenMode 2 - Enumerate modes
OS_ScreenMode 3 - Select monitor type
OS_ScreenMode 4 - Configure acceleration
OS_ScreenMode 5 - Perform screen cache clean
OS_ScreenMode 6 - Force screen cache clean
OS_ScreenMode 7 - Count number of screen banks available
OS_ScreenMode 8 - Select display bank
OS_ScreenMode 9 - Select VDU driver bank
OS_ScreenMode 10 - Copy between banks
OS_ScreenMode 11 - Select display device
OS_ScreenMode 12 - Read details about display device
OS_ScreenMode 13 - Decode mode string to mode specifier
OS_ScreenMode 14 - Encode mode specifier as mode string
OS_ScreenMode 15 - Select mode by string
The following additional calls are reserved for display drivers and their support code:
OS_ScreenMode 255 - Register display driver
OS_ScreenMode 254 - Deregister display driver
OS_ScreenMode 253 - Read maximum display driver
Client SWIs
OS_ScreenMode 0 (Select mode by number or specifier)
On entry
R0 = 0
R1 = mode number, or mode specifier
This SWI is used to select a screen mode for the current display. Consult PRM 5a 134.
OS_ScreenMode 1 (Return current mode)
On entry
R0 = 0
On exit
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.
OS_ScreenMode 2 (Enumerate screen modes)
On entry
R0 = 0
On exit
R1 = mode number, or pointer to read only mode specifier
This SWI is used to enumerate the screen modes available. Consult PRM 5a 138.
OS_ScreenMode 3 (Select monitor type)
On entry
R0 = 0
On exit
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.
OS_ScreenMode 4 (Configure acceleration)
On entry
R0 = 4
R1 = flags. , or -1 to read current value
bit 0 = set to suspend cached screen until mode change
bit 1 = set to suspend screen cleaning
bit 2 = set to disable hardware acceleration
Other = reserved, must be 0
R2 = number of VSyncs between automatic screen cleaning (1-3), or -1 to read current value
On exit
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.
OS_ScreenMode 5 (Perform a screen cache clean)
On entry
R0 = 5
This SWI is used to clean the cache for the screen if necessary and not disabled.
OS_ScreenMode 6 (Force a screen cache clean)
On entry
R0 = 6
This SWI will clean the cache for the screen if necessary whether disabled or not.
OS_ScreenMode 7 (Count number of banks)
On entry
R0 = 7 (Count number of banks)
On exit
R1 = number of available screen banks
This SWI returns the number of screen banks 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 which may affect the number of banks available. It is not possible to determine the number of banks that will be available in a mode because the requirements of the driver may change when changing to that mode.
OS_ScreenMode 8, 9 (Select, or read, display or driver bank)
On entry
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
On exit
R1 = previous bank number
R2 = new bank number
R3 = new bank address
These SWIs 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.
OS_ScreenMode 10 (Copy bank)
On entry
R0 = 10 (Copy bank)
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.
OS_ScreenMode 11 (Select display device)
On entry
R0 = 11
R1 = display number, or -1 to read current number
On exit
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.
OS_ScreenMode 12 (Read display device details)
On entry
R0 = 12
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
On exit
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.
OS_ScreenMode 13 (Decode mode string to a mode specifier)
On entry
R0 = 13
R1 = pointer to mode string
R2 = pointer to mode specifier to fill in
R3 = size of mode specifier
On exit
All registers 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' below 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.
OS_ScreenMode 14 (Encode mode string from a mode specifier)
On entry
R0 = 14
R1 = pointer to mode specifier
R2 = pointer to mode string to fill in
R3 = size of mode string
On exit
R3 = -ve 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.
OS_ScreenMode 15 (Select mode by mode string)
On entry
R0 = 15
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
OS_ScreenMode 255 (Register display device)
On entry
R0 = 255
R1 = pointer to display device descriptor block
On exit
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.
OS_ScreenMode 254 (Deregister display driver)
On entry
R0 = 254
R1 = display number
On exit
All registers 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.
OS_ScreenMode 253 (Read maximum display driver)
On entry
R0 = 253
On exit
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.
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 has the following interface :
On entry
R0 = display number of generate VSync
R12 = workspace pointer for VSync dispatch routine
On exit
All registers preserved
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, interpretted as follows :
bits 0-23 = Identifier number
bits 24-31 = Length of the value, in words, excluding the tag word
The following identifiers are defined :
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, thus :
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.
Value 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. (q.v. Bandwidth limitations details we need
to provide for limiting the modes we can display)
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 :
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.
PaletteV 10 (Invert LCD)
On entry
R0 = 0 to uninvert, 1 to invert
R4 = 10 (reason code)
On exit
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.
PaletteV 11 (Dim screen)
On entry
R4 = 11 (reason code)
On exit
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.
PaletteV 12 (Disable video hardware)
On entry
R4 = 12 (reason code)
On exit
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.
PaletteV 13 (Enable video hardware)
On entry
R4 = 13 (reason code)
On exit
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.
|
![[Select]](../imgs/seldoc.png)
