![[Burning Cog]](../../../icons/pyromaniac.png){kind=icon}
Introduction and Overview
Graphics modes can be specified in a number of ways, which have been added to with each iteration of the Operating System. Originally only mode numbers were allowed, but hardware improved and more flexibility was required, so the mode specification was extended.
Graphics modes may be supplied to a number of interfaces, most of which will eventually come down to a call to OS_ReadModeVariable. Some of the interfaces that you may find using mode specifications are:
| Interface | Usage |
|---|---|
| OS_ReadModeVariable | Read values for a given mode. |
| OS_CheckModeValid | Return whether the mode specified can be selected. |
| OS_ScreenMode | Operations on the graphics mode |
| ColourTrans_*ForMode | Colour operations for a given mode |
| OS_SpriteOp | Sprite creation operations may be supplied modes |
| Sprite Header | Defines the type of data within a sprite |
| Wimp_SetMode | Selects the mode used by the Window Manager |
Technical details
Mode specifiers
Mode specification is always through a single 32bit word value known as a mode specifier. This allows it to be supplied in many of the places that a mode number was used in earlier interfaces. This mode specifier can represent a number of ways of describing a mode. The following mode specifier formats are defined:
- Mode number
- Sprite mode word
- Sprite pointer
- Mode selector
These can be distinguished by the following algorithm:
- If the mode specifier is < 256:
- This is a mode number, and shadow bank selection.
- The mode number is in the low 7 bits, and shadow bank selection is given in bit 7.
- If the mode number is not recognised Service_ModeExtension is issued to determine the mode's parameters.
- Modes up to 7 are supported from the BBC onwards.
- Shadow modes are supported from the Master onwards (although they are less reliable from RISC OS 3.6 onwards)
- If the mode specifier has bit 0 set, this is a sprite mode word:
- Sprite mode words are given in the sprite header, but may also be supplied to many of the mode functions (except for display selection).
- They only contain the DPI (and thus eigenfactors), and type of data within the sprite. No resolution information is available.
- Sprite mode words are supported from RISC OS 3.5 onwards.
- If the mode specifier has bit 0 and 1 clear, this is a pointer to data,
whose meaning is differentiated by the value of the first word.
- If the first word has bit 0 clear, the data is a sprite (the mode specifier
is a sprite pointer):
- Sprite pointers allow information about the width and height to be included in the information, and allow the use of palette data as well. These types of mode specification are usually only used with ColourTrans_*operations.
- Sprite pointers are supported from RISC OS 3 onwards.
- If the first word has bit 0 set, the data is a mode selector:
- Mode selectors expose the base specifications for the mode and modifications to mode variables.
- Mode selectors allow for extended formats, but only a single format is currently defined.
- Mode selectors are supported from RISC OS 3.5 onwards.
- If the first word has bit 0 clear, the data is a sprite (the mode specifier
is a sprite pointer):
- If the value has bit 0 clear and bit 1 set, this is an invalid mode specification.
Mode numbers
Mode numbers may be extended through the Service_ModeExtension interface. This allows new numbered modes to be defined, either completely or based on other modes.
Sprite mode words
Sprite mode words allow some of the parameters of the mode to be determined, but because they do not include resolution information they cannot be selected. Sprite mode words are only supported from RISC OS 3.5 onwards.
The sprite mode word format has undergone a few revisions. The current definition of the sprite mode word is:
| Bit(s) | Meaning | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Set (indicator that this is a new format sprite, together with set bits in bits 27-31) | |||||||||||||||||||||||||
| 1-13 | Horizontal dots per inch, should be 180, 90, 45, 23/22, 11 | |||||||||||||||||||||||||
| 14-26 | Vertical dots per inch, should be 180, 90, 45, 23/22, 11 | |||||||||||||||||||||||||
| 27-30 | Sprite type :
| |||||||||||||||||||||||||
| 31 | Set: | Alpha channel data present. May not be set for type 0 sprites | ||||||||||||||||||||||||
| Clear: | Binary mask data present | |||||||||||||||||||||||||
For sprite types 1-4, the palette is only supported from RISC OS 3.6 onwards.
Although the DPI value should be the values defined above, values outside these may be supported. Certain interfaces, such as PlotSpriteTransformed, may use this information to render the sprites to the correct size for the display. Other interfaces, such as OS_ReadModeVariable and PlotSpriteScaled, may quantise these DPI values to the closest eigenfactor.
CMYK format sprites are supported from Select 2 onwards. JPEG data has been supported by third party extensions.
Mode selectors
A mode selector is a word-aligned structure that defines the properties of a mode. This includes its resolution, numbers of colours, frame rate and other mode variables.
A mode selector has the following format:
| Offset | Contents | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | mode selector flags:
| ||||||||||||||
| 4 | x-resolution (in pixels) | ||||||||||||||
| 8 | y-resolution (in pixels) | ||||||||||||||
| 12 | colour data format and depth:
| ||||||||||||||
| 16 | frame rate (in Hz); -1 => use highest rate available | ||||||||||||||
| 20 | pairs of [mode variable index, value] words; there may be any number of these, including zero | ||||||||||||||
| n | -1 (terminator) | ||||||||||||||
Mode variables may be given in any order, although it is recommended that they be supplied in ascending order. Repeating a variable definition has undefined behaviour.
Mode strings
To allow modes to be described within a string specification, a mode string is able to be supplied to various interfaces. Mode strings must be converted to a mode specifier before they can be used with many interfaces. OS_ScreenMode allows these mode strings to be converted to and from mode specifiers.
The mode string takes the form of a space or comma separated list of parameters. Each parameter is a sequence of alphabetic characters defining the parmeter, followed by a number sequence and possible qualifiers.
The mode string parameters have the following format:
| Parameter | 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 |
Up to RISC OS Select 3, the X and Y resolution must be values from 100-9999. From Select 3 inwards, any value other than 0 may be supplied, although support for resolutions above 16384 may not be reliable.
Teletext mode selection and character width/height is supported from RISC OS Select 3 onwards.
Selection of modes with 64 colours results in an old-style VIDC 1 mode selection of a 256 colour mode with 192 derived colours. Prior to Select 3, selection of 'C256' would result in a the old-style VIDC 1 mode being selected.
The OS_ScreenMode interface for converting and selecting mode strings is supported from RISC OS Select 3 onwards.
*WimpMode supports selecting mode strings from RISC OS 3.5 onwards.