Pyromaniac

Pyromaniac PRM: Graphics Mode Specification

Pyromaniac PRM: Graphics Mode Specification

RISC OS PyromaniacGraphics Mode Specification

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:

InterfaceUsage
OS_ReadModeVariableRead values for a given mode.
OS_CheckModeValidReturn whether the mode specified can be selected.
OS_ScreenModeOperations on the graphics mode
ColourTrans_*ForModeColour operations for a given mode
OS_SpriteOpSprite creation operations may be supplied modes
Sprite HeaderDefines the type of data within a sprite
Wimp_SetModeSelects 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 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
0Set (indicator that this is a new format sprite, together with set bits in bits 27-31)
1-13Horizontal dots per inch, should be 180, 90, 45, 23/22, 11
14-26Vertical dots per inch, should be 180, 90, 45, 23/22, 11
27-30

Sprite type :

ValueMeaning
0Old format mode word (mode is a standard number)
11 bpp
22 bpp
34 bpp
48 bpp
515 bpp in 16bit values
624 bpp in 32bit values
7CMYK
824 bpp compact format (allocated but not used)
9JPEG data (allocated but not used)
10-15Reserved

31Set: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:

OffsetContents
0

mode selector flags:

Bit(s)Meaning
01 (this differentiates it from a sprite pointer)
1-7mode specifier format (0 for this format)
8-31other flags (reserved - must be zero)
4x-resolution (in pixels)
8y-resolution (in pixels)
12colour data format and depth:
ValueMeaning
01 bpp
12 bpp
24 bpp
38 bpp
415 bpp in 16 bit values
524 bpp in 32 bit values
16frame rate (in Hz); -1 => use highest rate available
20pairs of [mode variable index, value] words; there may be any number of these, including zero
n1 (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:

ParameterMeaning
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.