RISCOS.com

www.riscos.com Technical Support:
Programmer's Reference Manual

 

Video


Introduction

The new architecture uses a new video controller - VIDC20. Using this gives a much improved video capability over the previous generation of computers that used VIDC1 or VIDC1a chips. In particular, it supports pixel depths of up to 32bpp (bits per pixel) on a much wider range of monitor types.

The video system was substantially changed in RISC OS 3.5, so that VIDC20 can be used to its full capabilities. There are new ways of selecting and specifying screen modes and monitor types. The sprite format has been extended to allow sprites that use the new screen modes. Many calls have been extended to support these new features, particularly in the kernel (including OS_SpriteOp calls) and in ColourTrans.

In RISC OS 3.6, further minor extensions have been made to the video system: in particular, support has been added for palettes in the new sprite format.

Full details are in the rest of this chapter. The information in this chapter applies from RISC OS 3.5 onwards, unless otherwise stated.

Furthermore, support for JPEG files has been added in RISC OS 3.6. This is described separately, in the chapter JPEG images.

Overview

New ways of selecting modes

There are new ways of specifying and selecting screen modes, to take account of the much wider range of screen modes potentially available. See Mode selection.

Many calls have been extended to use these new methods; see their individual entries in the Technical details. A few calls have been added where existing calls could not be extended, or to provide functionality not present in RISC OS 3.

Monitor configuration stored in files

The new architecture can support a much wider range of monitors than in the past.

At start-up the monitor type, screen mode and sync are set from configured values, as in RISC OS 3. However, the new architecture only detects bit 0 of the monitor lead ID, so auto-configuration of monitor type, screen mode and sync is no longer so flexible (see Service_MonitorLeadTranslation).

These defaults are then overridden by information read from a monitor-specific file, each of which stores the full range of modes available for a specific monitor. For full details, see ModeInfo files, and The ScreenModes module.

New sprite format

The RISC OS 3 sprite format has been extended to support the new pixel depths that are available. The new format is defined in New format of a sprite.

OS_SpriteOp calls have also been extended to work with the new sprite format; see Changes to OS_SpriteOp. Calls that create sprites will - where possible - create an old format sprite. This is to ease exchange of files with machines running older versions of RISC OS.

ColourTrans extended to support new modes and sprites

ColourTrans calls have been extended to support the changes to other parts of the video software. For full details see Changes to existing ColourTrans SWIs.

New PaletteV reason codes

The PaletteV software vector has been enhanced by the addition of extra reason codes. These are for block reading and writing of the palette, and setting up gamma correction tables for RGB values being programmed into the palette. PaletteV has been enhanced by the addition of extra reason codes. For a full description see PaletteV changes, and the description of the new reason codes on PaletteV.

All 8 bits of colour numbers are significant

All 8 bits of a colour component are now significant. Do not work in four bit quantities and fill in the lower nibble either by setting it to zero or by copying the upper nibble. This technique still works, but only allows access to sixteen of the possible 256 intensities.

Technical details

Mode selection

Because of the increased number of colours and the range of resolutions available, using a mode number to define screen modes has become limiting. (There was a maximum of only 128 modes, with just 64 available to Acorn.) To bypass this limitation a number of different methods are now used to define modes. These methods and their terminology are summarised below.

Mode numbers

The mode numbers used in earlier versions of RISC OS are still supported.

Mode selectors

A mode selector is a word-aligned structure that defines a particular mode. This includes its resolution, numbers of colours, frame rate and other variables.

A mode selector has the following format:

Offset Value
0 mode selector flags:
bit 0 = 1 (see Distinguishing mode selectors from sprite areas)
bits 1 to 7 = format specifier (zero for this format)
bits 8 to 31 = other flags (reserved - must be zero)
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 => use highest rate available
20 pairs of [mode variable index, value] words; 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 OS_ReadModeVariable.

Mode specifiers

A mode specifier is a word passed to a SWI to specify a mode. A mode specifier may be either a mode number (0 - 255), or a pointer to a mode selector (greater than 255). The range of the value determines which it is.

Mode strings

Mode strings are a textual form of mode selection, used by several Wimp calls and the command *WimpMode, as well as the Display manager utility.

A mode string has the following syntax:

Syntax Meaning
Xnnnn X resolution (nnnn is three or four digits)
Ynnnn Y resolution (nnnn is three or four digits)
Cccc Colours (ccc = 2, 4, 16, 64, 256, 32T, 32K, 16M)
Gggg Greys (ggg = 4, 16, 256)
EXn X EIG factor (n = 0 to 3, smaller values make text larger)
EYn Y EIG factor (n = 0 to 3, smaller values make text larger)
Ffff Frame rate (Hz) (fff is two or three digits)

For example:

X640 Y512 C16 Mode 20 (nb not supported by all monitors)
X640 Y480 C16 EX0 EY0 Mode 27 with extra-large text
X320,Y480,C64 VIDC 1 style 8bpp, VGA with rectangular pixels
  • The parameters G and C cannot be specified together.
  • Parameters EX and EY are optional and the default size is used if they are not given.
  • Parameter F is optional; if it is omitted a value of -1 is used, which uses the highest frame rate available.

The Display manager utility only changes modes using *WimpMode. A mode selection string is constructed when the user clicks on OK in the window. If you want to use a mode number, you can enter it instead of a mode string. For example you can enter 15 to select the old mode 15.

ModeInfo files

ModeInfo files 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.

  • 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 or tabs followed by the hash character '#' are treated as comments and ignored.
Header

The file always starts with the following two lines:

file_format: format
monitor_title: title

where:

format must be 1 for this format file
title is a textual description of this type of monitor

This may be followed by an optional line to control DPMS power saving (see Monitor power saving):

DPMS_state: state

where:

state

must be 0, 1, 2 or 3

Under RISC OS 3.6 or later, the first two lines may instead be followed by an optional line to indicate the file is for an LCD panel:

lcd_support: value

where:

value

must be 1 (single panel) or 2 (dual panel)

Mode definitions

The header is followed by any number of mode definitions, as follows:

startmode
  mode_name: mode_name
  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
endmode

where:

mode_name is a textual name for the mode for use in menus and such. The mode name field must be present; however, the mode name itself may be blank, which prevents the mode appearing on menus (eg the Display Manager's Resolution menu.)
x-resolution is the number of pixels displayed across the screen
y-resolution is the number of displayed rasters
hsync is the width of the hsync pulse
hbpch is the width of the horizontal back porch
hlbdr is the width of the left hand border
hdisp is the number of displayed pixels horizontally, which is normally the same as x-resolution)
hrbdr is the width of the right hand border
hfpch is the width of the horizontal front porch
vsync is the width of the vsync pulse
vbpch is the width of the vertical back porch
vtbdr is the width of the top border
vdisp is the number of displayed rasters vertically (normally the same as y-resolution)
vbbdr is the width of the bottom border
vfpch is the width of the vertical front porch
pixel_rate is the pixel rate 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

All values on the h_timings line are in units of pixels, and all values on the v_timings line are in units of raster lines.

Note: VIDC20 imposes restrictions on these 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 data sheet for details of further restrictions.

ModeInfo files are used by the new ScreenModes module; see The ScreenModes module.

Distinguishing mode selectors from sprite areas

In earlier versions of RISC OS, certain SWI calls (e.g. ColourTrans ones) were passed screen modes either as mode numbers, or as pointers to sprite areas from which the sprite's screen mode was read. The two were differentiated by their values.

These calls now also accept a pointer to a mode selector, which must be distinguished from a pointer to a sprite area. This is done by examining the first word of the area pointed to. The first word of a sprite area is the size of the area; since the area must be word aligned, bit 0 of this word will always be 0.For this reason a mode selector always has bit 0 of its first word set, thus ensuring it can be distinguished from a sprite area.

The ScreenModes module

VIDC20 supports a much wider range of monitors than did VIDC1, with a wide range of available line frequencies. Supporting these requires a new mechanism, without which RISC OS would have had to define many new monitor type numbers.

Monitors are now supported using ModeInfo files held on hard disc. Each file holds the timings for a full set of screen modes on a particular monitor. A new ScreenModes module provides a * Command - *LoadModeFile - to load one of these files. If the file contains valid information, the ScreenModes module then calls OS_ScreenMode 3 to set the current MonitorType to 7 (file).

This makes available all the screen modes defined in the file, while removing all modes defined in any previously loaded file.

Desktop screen modes

Colours

The following colour options are supported on the desktop:

  • 1 bpp (monochrome)
  • 2 bpp (grey)
  • 4 bpp (grey)
  • 4bpp (colour)
  • 8 bpp (palette set to correspond with default VIDC1 operation - using tints)
  • 8 bpp (palette set to provide 256 grey levels)
  • 16 bpp (palette fixed, can only be used for Gamma correction)
  • 32 bpp (palette fixed, can only be used for Gamma correction).

This table shows how the bits per pixel value corresponds to the number of colours available:

Bits per pixel Number of colours
1 2
2 4
4 16
8 256 (or 64)
16 32 thousand
32 16 million
Screen memory

The limits of the capabilities of the VIDC20 depend upon the amount of screen memory available. The new architecture can use either DRAM or VRAM based screen memory.

  • VRAM based screen memory can be 1MB or 2MB in size.
  • DRAM based screen memory is limited to 1MB. There is the same trade-off as in RISC OS 3 between the bandwidth used for video and that used for other purposes, such as running applications.
Screen resolutions

The following are the maximum screen resolutions that the desktop supports. These figures are maximum limits, and are for guidance only; some monitors will not be able to display all these resolutions. Your software should not assume that any particular combination is possible.

Using DRAM as screen memory
1024 × 768 4 bpp
800 × 600 8 bpp
768 × 288, or 480 × 352 16 bpp
384 × 288 32 bpp
Using 1MB of VRAM as screen memory
1280 × 1024 4 bpp
1024 × 768 8 bpp
800 × 600 16 bpp
768 × 288, or 480 × 352 32 bpp
Using 2MB of VRAM as screen memory
1280 × 1024 4 bpp
1280 × 1024 8 bpp
1024 × 768 16 bpp
800 × 600 32 bpp

The Display manager utility allows a selection of pre-defined modes to be chosen; custom modes can also be used and defined.

Grey level modes and the Wimp

The Window Manager now allows the selection of 16 and 256 level grey scale modes in the desktop.

In 16 grey-level modes the first eight desktop 'colours' are the same shades of grey as in normal 16 colour modes, and the next eight 'colours' provide interpolated greys. This means that the logical colours do not decrease in brightness monotonically.

In 256 grey-level modes the palette is set up so that a pixel value of 0 is black, 255 is white, and the values between form a linear grey scale.

New format of a sprite

The sprite format has been extended to incorporate the new modes. The new format avoids the problems that could be caused in previous versions of RISC OS by binding sprite files to a mode number not available on the viewing computer. The new format uses different sprite types for different pixel depths.

The old sprite format is still fully supported. RISC OS distinguishes between new and old format sprites by examining the top bits of the word that specified the sprite mode in the old format. These bits were always zero for the old format; in the new format these are used to store the (non-zero) sprite type.

Sprite Control Block

The Sprite Control Block has this format for new sprite types:

Bytes Meaning
0 - 3 Offset to next sprite
4 - 15 Sprite name, up to 12 characters with trailing zeroes
16 - 19 Width in words - 1
20 - 23 Height in scan lines -1
24 - 27 * 0 (reserved for future use)
- no left hand wastage is allowed on new format sprites
28 - 31 Last bit used (right end of row)
32 - 35 Offset to sprite image
36 - 39 Offset to transparency mask, or offset to sprite image if no mask
40 - 43 * New sprite mode word:
Bits Meaning
27 - 31 Sprite type:
0 => OLD TYPE; SEE Format of a sprite for format
1 - 31 => new type; these are defined below
14 - 26 Vertical dpi; should be 180, 90, 45 or 22
1 - 13 Horizontal dpi; should be 180, 90, 45 or 22
0 1; see Distinguishing sprite modes and mode selectors
44... Palette data (optional)

* These words have changed from the old format of sprite control block.

Sprite types

Sprite types are as follows.

Type Meaning
0 Backward compatible mode - see Format of a sprite
1 1bpp image; 1bpp mask; palette not supported by RISC OS 3.5
2 2bpp image; 1bpp mask; palette not supported by RISC OS 3.5
3 4bpp image; 1bpp mask; palette not supported by RISC OS 3.5
4 8bpp image; 1bpp mask; palette not supported by RISC OS 3.5
5 16bpp image; 1bpp mask; palette not supported by RISC OS
6 32bpp image; 1bpp mask; palette not supported by RISC OS
7 Allocated for CMYK, but not supported within RISC OS
8 Allocated for 24bpp, but not supported within RISC OS
9 - 31 Reserved for future expansion
Pixel formats for 16 and 32bpp sprites

The formats of pixels in 16 and 32bpp sprites is as follows:

16bpp sprites
Bit Use
0 - 4 Red
5 - 9 Green
10 - 14 Blue
15 Reserved (set to 0)
32bpp sprites
Bit Use
0 - 7 Red
8 - 15 Green
16 - 23 Blue
24 - 31 Reserved (set to 0)
Mask data structure

Whatever the depth of image, the mask for new type sprites is 1 bit per pixel. Each row of mask bits begins word aligned. The layout of mask bits is identical to the layout of a 1bpp sprite's image data.

Sprite palettes

RISC OS 3.5 does not support palettes for new type sprites, and will generate an error if it finds one.

RISC OS 3.6 adds support for palettes in new type sprites that have up to 8bpp. It does not support palettes in 16 or 32bpp sprites. The format of the palette data is the same as for old type sprites.

Distinguishing sprite modes and mode selectors

You can now specify modes in some calls using either a mode specifier (i.e. a mode number, as before, or a pointer to a mode selector), or a new sprite mode word. The passed value is treated as a mode number if it is less than 256. The other two cases must be distinguished somehow. It is for this reason that bit 0 is set for a new sprite mode word; this bit is always clear in a pointer to a mode selector, since they must be word-aligned.

New software vectors

PaletteV has been enhanced by the addition of extra reason codes. For a full description see PaletteV.

Block read and write

There are new reason codes for block reading and writing of the palette. A number of other calls have been extended to use these reason codes in preference, before falling back to older methods of reading the palette should this fail.

Gamma correction

A further reason code can be used to set up gamma correction tables for RGB values being programmed into the palette.

Claiming PaletteV

Not all PaletteV claimants support this code, so care must be take in the use of these calls. The correct behaviour for a claimant is to return all calls, but only set R4 to 0 for those it knows. This avoids problems with different PaletteV claimants processing some reason codes and passing on others it does not understand.

New Service Call

A new service call has been added:

Changes to existing Service Calls

Service_ModeExtension

Service_ModeExtension now uses a new format of VIDC list that is independent of the video controller used. There is no support for the old formats of VIDC list used in earlier versions of RISC OS, which included values corresponding directly to VIDC1 register formats. In particular, this means that old mode extend modules will not work under RISC OS 3.5 or later. For more information see Service_ModeExtension.

Service_ModeTranslation

This service call has been 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.

Service_MonitorLeadTranslation

The new architecture can only detect the state of the ID0 pin, and so the defaults set by this service call have been changed. New defaults are:

ID0 Monitor type Sync type Default mode
H 0 (TV standard) 1 (composite) 12
1 0 (TV standard) 1 (composite) 12
0 3 (VGA) 0 (separate) 27

Mono VGA monitors are interpreted as TV standard monitors, so this class of monitor requires manual configuration before use. Other monitor types are detected and an appropriate mode is selected.

Changes to existing VDU calls

VDU 17 and VDU 18

These calls have not been extended to work in 16bpp or 32bpp modes; in such cases they will behave as if in an 8bpp mode. This makes the calls no longer useful, and you should instead use OS_SetColour and OS_SetColour. The colour number to be used can be found by using ColourTrans_ReturnColourNumber.

VDU 19

In 16bpp and 32bpp modes, the palette is altered for gamma matching only. VDU 19 should not be used in these modes. It is no longer necessary to duplicate nibbles - all 8 bits of the colour component are significant.

VDU 22

This call has not been altered, and so no longer allows all display modes to be chosen. You should no longer use VDU 22; for full access to the screen modes available on the computer you should instead use OS_ScreenMode.

VDU 23,17,0-3

This call works for all 8bpp screen modes, but is of little use for modes having a full 256 colour palette.

VDU 25

These calls to plot circles do not work properly with 180 × 45 or 45 × 180 screen modes.

New kernel SWI

The following new kernel SWI has been created. It is defined in full at the end of this chapter:

  • OS_ScreenMode performs miscellaneous operations for screen mode handling. R0 provides a reason code which determines which operation is performed.

Changes to existing kernel SWIs

OS_Byte 135

The returned mode may now be a mode specifier.

OS_Word 9

You should no longer use OS_Word 9 to read the pixel logical colour.

OS_Word 11

ColourTrans_ReadPalette in preference to this call.

OS_Word 12

Use ColourTrans_WritePalette in preference to this call.

OS_ReadModeVariable

You can now specify the mode using a mode specifier or a new sprite mode word.

A new ModeFlag has been assigned; bit 7 is set to show that an 8bpp mode uses a full palette. Such modes also return 255 for NColour, whereas old-style 8bpp modes still return 63.

If you are using a new sprite mode word, the values returned for certain VDU variables depends on its sprite type ('T' below), and its horizontal and vertical dpi ('hdpi' and 'vdpi' respectively):

Name No. Returned value
NColour

3

T=1 => 1_ T=2 => 3_ T=3 => 15_ T=4 => 63 OR 255_ T=5 => 65535_ T=6 => &FFFFFFFF

XEigFactor

4

hdpi=22/23 => 3_ HDPI=45 => 2_ HDPI=90 => 1_ HDPI=180 => 0

YEigFactor

5

vdpi=22/23 => 3_ VDPI=45 => 2_ VDPI=90 => 1_ VDPI=180 => 0

Log2BPP

9

T=1 => 0_ T=2 => 1_ T=3 => 2_ T=4 => 3_ T=5 => 4_ T=6 => 5

Log2BPC

10

T=1 => 0_ T=2 => 1_ T=3 => 2_ T=4 => 3_ T=5 => 4_ T=6 => 5

OS_CheckModeValid

This call now accepts a mode specifier in R0, not just a mode number. In addition, the returned substitute mode may be a mode specifier.

OS_Plot

See VDU 25,144-167.

OS_SetColour

This call now has two extra flag bits defined in R0. You can now read or write the text and graphics foreground/background colours. The new flags are:

bit 6 set => R1 = TEXT COLOUR_ CLEAR => R1 = graphics colour
bit 7 set => READ COLOUR_ CLEAR => set colour

When setting the colour all the flags are used. As before, you can specify graphics colours using a pattern block or a colour number; text colours must be specified as colour numbers.

When reading the colour only the foreground/background flag and the text/graphics flag are used. For graphics colours you must supply a pattern block, whereas text colours are returned in R1 as colour numbers.

The values returned can be passed straight back to OS_SetColour to restore the colour.

New OS_SpriteOp reason code

The following new reason code has been added to OS_SpriteOp. It is defined in full at the end of this chapter:

Changes to OS_SpriteOp

OS_SpriteOp calls support new type sprites wherever appropriate. This is assumed, and not stated below for each call.

Support for particular features has only been added as they have become legal in RISC OS. In particular:

  • Since RISC OS 3.5 did not allow new type sprites with a palette, you cannot use its OS_SpriteOp calls to create them. RISC OS 3.6 allows new type sprites with up to 8bpp to have a palette, and so you can use the relevant calls to create such sprites.
  • However, even though new type sprites with a mask were legal under RISC OS 3.5, a few of its calls did not accept such sprites. These calls are specifically noted below.
Forcing a mode number when creating sprites

Calls that create sprites will - where possible - create an old format sprite. This is to ease exchange of files with machines running older versions of RISC OS. In doing so, they may have to force the current mode from one specified by a mode selector back to a mode number. The following modes are used:

1bpp 2bpp 4bpp 8bpp
90 × 45 dpi 0 8 12 15
45 × 45 dpi -- 1 9 13
90 × 90 dpi 25 26 27 28

Combinations not shown in the above table (including 45×45dpi at 1bpp) cannot be forced back to a mode number, and must always use the new sprite types.

Use of translation tables and palette entries

In general you must supply a translation table when plotting a sprite with 8bpp or less to a 16 or 32 bpp mode. However, a few calls (noted in their descriptions below) provide a new flag to force sprites to be plotted using their palette entries rather than translation tables. The sprites must have full palette entries for you to do this.

Under RISC OS 3.5 only, when plotting an 8bpp sprite with a full palette to a 16 or 32bpp mode, it is plotted from its palette entries. However, for compatibility we suggest that you do not rely on this, but instead use the new flag where relevant.

OS_SpriteOp 15 - Create sprite

On entry R6 can now be a mode number (as before), or a sprite mode word, or a pointer to a mode selector.

OS_SpriteOp 31 - Insert row
OS_SpriteOp 32 - Delete row
OS_SpriteOp 33 - Flip about x axis
OS_SpriteOp 35 - Append sprite

Under RISC OS 3.5 these calls do not accept new type sprites that have a mask. This restriction has been removed from RISC OS 3.6 onwards.

Note that OS_SpriteOp 35 will generate an error if you attempt to append a sprite with a 1bpp mask to one with a non-1bpp mask.

OS_SpriteOp 36 - Set pointer shape

This call accepts type 0 - 4 sprites. It does not accept types 5 and 6.

OS_SpriteOp 37 - Create/remove palette

Under RISC OS 3.5 this call accepts new type sprites. It generates an error if you try to create a palette, but does nothing if you try to remove one; this is because RISC OS 3.5 does not support new type sprite palettes.

RISC OS 3.6 allows new type sprites with up to 8bpp to have a palette. This call therefore can create or remove palettes from such sprites. New type sprites of a greater depth (ie > 8bpp) are still accepted, but treated just as in RISC OS 3.5, since such sprites are still not allowed to have a palette.

OS_SpriteOp 45 - Insert column
OS_SpriteOp 46 - Delete column
OS_SpriteOp 47 - Flip about y axis

Under RISC OS 3.5 these calls do not accept new type sprites that have a mask. This restriction has been removed from RISC OS 3.6 onwards.

OS_SpriteOp 52 - Put sprite scaled

Bit 4 of R5, if set, forces a 1, 2 or 4bpp sprite to be plotted into 16 or 32bpp using its palette entries rather than a translation table. The sprite must have a full palette.

From RISC OS 3.6 onwards two further flags have been added:

  • Bit 5 of R5, when set, indicates that a wide translation table is being used. The table is 1 byte wide when plotting into less than 8bpp, 2 bytes wide for 16bpp, and 4 bytes wide for 32bpp. This is similar to the action of bit 4 of R5 in ColourTrans_SelectTable.
  • Bit 6 of R5, when set, makes RISC OS use dithering when plotting a 16 or 32bpp sprite to a reduced depth. This bit is otherwise ignored.
OS_SpriteOp 53 - Put sprite greyscaled

From RISC OS 3.6 onwards this call is no longer available. If you attempt to call it, the Sprite Extend module generates an appropriate error.

OS_SpriteOp 54 - Remove lefthand wastage

This call will not accept new type sprites that have a mask. However, you should never need to call it for new type sprites, since they are not allowed to have any lefthand wastage.

OS_SpriteOp 56 - Put sprite transformed

Bit 4 of R5, if set, forces a 1, 2 or 4bpp sprite to be plotted into 16 or 32bpp using its palette entries rather than a translation table. The sprite must have a full palette.

From RISC OS 3.6 onwards, bit 5 of R5, when set, indicates that a wide translation table is being used. The table is 1 byte wide when plotting into less than 8bpp, 2 bytes wide for 16bpp, and 4 bytes wide for 32bpp. This is similar to the action of bit 4 of R5 in ColourTrans_SelectTable.

OS_SpriteOp 57 and 58 - Insert/delete rows/columns

Under RISC OS 3.5 these calls do not accept new type sprites that have a mask. This restriction has been removed from RISC OS 3.6 onwards.

Changes to existing Wimp SWIs

Wimp_SetMode

This call now accepts a mode specifier in R0. If this is a pointer to a mode selector, the Wimp copies the mode selector, so you can then re-use the memory.

Changes to existing ColourTrans SWIs

ColourTrans has been extended to support the new 16bpp and 32bpp modes. Facilities have been provided to allow behaviour in these depths to be backwards compatible.

All ColourTrans calls will now accept a mode specifier rather than a mode number, where appropriate. Most ColourTrans calls that use GCOLs will use 16 or 32 bit values for 16 or 32bpp modes. Only the exceptions are noted below.

ColourTrans_SelectTable
ColourTrans_GenerateTable

The table size generated by an application attempting to map down from a 16 or 32bpp to a 1-8bpp mode would be excessively large, so ColourTrans does not return full translation tables in these cases. There is no longer a relationship between the size of the table returned by ColourTrans and the number of colours in the source mode. You must determine the size of the table before requesting it.

The revised translation table functionality is:

Source Mode
1, 2, 4, 8 bpp 16, 32 bpp
Destination Mode 1, 2, 4, 8 bpp See note 1 below See note 2 below2
16, 32 bpp See note 3 below See note 4 below
  1. This is the existing RISC OS 3.1 algorithm unchanged.
  2. This returns a structure including a pointer to a 32 KB table mapping from 5 bits per primary colour to a colour number in the destination screen mode.

    0 Word = &2E4B3233 ('32K.')
    4 Pointer to table
    8 Word = &2E4B3233 ('32K.')

    The guard words each side of the pointer allow SpriteExtend to check whether the translation table passed to it is of this form, or is a direct look up table.

  3. This returns a byte, representing a colour. This behaviour has been chosen to provide a safe route for those applications which assume that the size of the table in bytes will always be the same as the number of colours in the source mode. In 16bpp, two bytes per colour are returned. In 32bpp a word per colour is returned.

    From RISC OS 3.5 onwards a new flag, bit 4 of R5, instructs the call to return >8 bits per colour in a pixel translation table if the destination mode is >8bpp, rather than to return bytes (indicating that the caller is aware that the colours/bytes relationship no longer holds true).

    R5 = flags:

    bit 4 set => return > 8 bits per colour rather than bytes

    If bit 4 is not set, a table will be returned as if the target mode is 8bpp.

  4. This does not generate a look up table. When plotting between these bpp modes only bit stretching/packing is performed.
ColourTrans_SelectTable
ColourTrans_SelectGCOLTable
ColourTrans_GenerateTable

From RISC OS 3.5 onwards, if R2 specifies a mode and R1 is -1, the table uses the default palette for the given mode. This is because the current palette may be unsuitable for the given mode. You can usually get back the old behaviour by using bit 1 of R5.

ColourTrans_SelectGCOLTable
ColourTrans_GCOLToColourNumber
ColourTrans_ColourNumberToGCOL

These calls have not been extended to use 16 or 32 bit GCOL numbers.

ColourTrans_ReadPalette
ColourTrans_WritePalette

These calls process palette entries as words which contain 24 bit colour descriptions. The whole palette must be read, modified and written back.

The bottom byte of the palette entry contains the supremacy bits; all 8 bits are reserved. In 32bpp modes bits 7 - 4 are used; in other modes only bit 7 is used. ColourTrans and the kernel now support this. (The kernel only expects one bit of supremacy and ignores the rest.)

The palette entry passed through these calls is in the form &BBGGRRS0, where S is the supremacy mask nibble.

For ColourTrans_ReadPalette, you may set R1 to 0 on entry to make the call use the default palette.

ColourTrans_SelectTable

See ColourTrans_SelectTable/ColourTrans_GenerateTable and ColourTrans_SelectTable/ColourTrans_SelectGCOLTable/ColourTrans_GenerateTable.

New * Command

A new * Command is provided by the new ScreenModes module:

For more information see ModeInfo files and The ScreenModes module.

Changes to existing * Commands

*ScreenLoad
*ScreenSave

These calls are now far more likely to cause a mode change, and so reset the graphics window and other state. You should only use these calls to load and save an entire screen, rather than a part of the screen defined by the graphics window.

*WimpMode

This command now allows the mode to be specified either as a number or as a mode string. This is reflected in the Display manager application, which also allows this form.

*WimpMode is no longer supported when issued from a task window.

Software vectors


PaletteV
(Vector &23)

Called whenever the palette is to be read or written.

The reason codes below have been added in RISC OS 3.5. For information on other reason codes see PaletteV (Vector &23).

On entry

Register usage is dependent on a reason code held in R4:

Read palette entries

R0 = pointer to word aligned list of logical colours (words), or 0 R1 = type and number of colours:

bits 0 - 23 = number of palette entries to read
bits 24 - 31 = type of colour (16,17,18,24 or 25)

R2 = pointer to word aligned buffer to receive 1st flash colour (&BBGGRRxx) - device colours
R3 = pointer to word aligned buffer to receive 2nd flash colour (&BBGGRRxx) - device colours
R4 = 7 (reason code)

Write palette entries

R0 = pointer to word aligned list of logical colours (words), or 0
R1 = type and number of colours:

bits 0 - 23 = number of palette entries to write
bits 24 - 31 = type of colour (16,17,18,24 or 25)

R2 = pointer to word aligned list of device colours (&BBGGRRxx)
R4 = 8 (reason code)

Gamma correction tables

R0 = pointer to word aligned gamma correction table for red
R1 = pointer to word aligned gamma correction table for green
R2 = pointer to word aligned gamma correction table for blue
R4 = 9 (reason code)

On exit
Gamma correction tables

R4 = 0 => THE VIDEO DRIVERS SUPPORT gamma correction, and the tables have been copied into system workspace
R4 [NOT EQUAL] 0 => the video drivers do not support gamma correction

Other reason codes

R4 = 0 => operation complete

Use
Reason code 7

The memory pointed at by R2 and R3 is filled with words giving the device colour for each flash state. Where only one specific flash state was requested, the information for the other flash state is not filled in.

If no list of logical colours is given (R0 is 0 on entry) and the colour type is 16, 17 or 18, then the call returns the number of palette entries requested starting from the first logical colour - this allows a number of consecutive colours to be read without needing to set up a list.

If the colour type is 16 (read both flash states) and R3 is 0, the area pointed at by R2 is used for both flash states (in the order first state, second state, first state, etc).

Reason code 8

If no list of logical colours is given (R0 is 0 on entry) and the colour type is 16, 17 or 18 on entry then the number of palette entries specified by R1 is written consecutively starting from the first logical colour.

When the colour type is 16 the device colour entries pointed at by R2 should be in the order first state, second state, first state etc.

Reason code 9

This call sets up 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. Likewise, the green and blue components are looked up in their respective tables before being output.

Service calls


Service_ModeExtension
(Service Call &50)

Allow soft modes

On entry

R1 = &50 (reason code)
R2 = mode specifier that information is requested for
R3 = monitor type (or -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 claimed)

If claimed:
R1 = 0
R2 preserved
R3 = pointer to VIDC list (type 3)
R4 = pointer to workspace list if mode specifier was a mode number, or 0 if mode specifier was a pointer to a mode selector

Use

This service call is issued when information is needed on a particular mode: for example on a mode change, or when mode variables are read. The description below is for RISC OS 3.5 and later only; for details of this service call under earlier versions of RISC OS, see Service_ModeExtension.

In RISC OS it is possible to load modules which provide additional screen modes and additional monitor types. Such modules must claim this call and return the requested information if they recognise the passed mode and monitor type, and if the mode being selected would use no more than the specified video bandwidth and video memory. Otherwise they should pass on the call.

A module that is checking if it recognises a mode selector must examine its format specifier, held in bits 0 - 7 of the flags word (at offset 0). If the module does not recognise the format, it must pass on the service call.

The mode selector could contain -1 as the frame rate, in which case the matching mode with the highest frame rate should be returned.

If R3 holds -1 then RISC OS is making a general enquiry about that mode (eg to determine the attributes of a sprite defined in that mode) so the module should only check R2.

The returned VIDC list consists of a series of words. The first word specifies the format of the list, so this can be altered to cope with new hardware such as new versions of VIDC. RISC OS 3 supports VIDC lists in formats 0 and 1; these include values that directly correspond to VIDC1 register formats. These formats are not supported on RISC OS 3.5 and later; mode extend modules for RISC OS 2 and 3 will not work.

VIDC list: format 3

A new format list (type 3) is used from RISC OS 3.5 onwards, which is independent of the video controller used:

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 (in pixels)
16 left border (in pixels)
20 display size (in pixels)
24 right border (in pixels)
28 front porch (in pixels)
32 vertical: sync width (in rasters)
36 back porch (in rasters)
40 top border (in rasters)
44 display size (in rasters)
48 bottom border (in rasters)
52 front porch (in rasters)
56 pixel rate (in kHz)
60 sync polarities when composite sync not configured:
bit 0 set => Hsync inverted
bit 1 set => Vsync inverted
bits 2 to 31 reserved (must be zero)
64 video control parameters list
n -1 (terminator)

The video control parameters list (at offset 64) does not normally contain entries for normal video operation. These are only needed for special video operation. The list contains pairs of words (control parameter index, value) terminated by a -1 word. These control additional VIDC registers, bits in registers, and monitor power savings. These are described in the following table. Refer to the VIDC20 data sheet for detailed explanations.

Control index Parameter description Values
1 LCD mode 0 => DISABLE_ 1 => enable
2 LCD dual-panel mode 0 => DISABLE_ 1 => enable
3 LCD offset register 0 0 - 255
4 LCD offset register 1 0 - 255
5 Hi-res mode 0 => DISABLE_ 1 => enable
6 DAC control 0 => DISABLE_ 1 => enable (default)
7 RGB pedestal enables bit 0 = R, bit 1 = G, bit 2 = B
8 External register [7:0] 0 - 255
9 Reserved --
10 Reserved --
11 DPMS power saving 0 - 3; see Monitor power saving
Workspace list

Returning a workspace list is relevant only if a mode number is passed in. If a pointer to a mode selector is passed in, RISC OS works out what the mode variables should be, there is no need to return a workspace list, and R4 is set to zero on exit.

All values are words in the workspace list; its format is:

Offset Value
0 0 (indicates format of list)
4 Workspace base mode
8 Mode variable index
12 Mode variable value
16 Mode variable index
20 Mode variable value
... ...
n -1

The workspace base mode is the number of an existing operating system screen mode which is used to determine the values of mode variables not explicitly mentioned in the list. The mode variable indices are the same as for the SWI OS_ReadModeVariable.

General notes

Modules can provide their own palette programming routines, including setting of the default palette, by claiming PaletteV. For more details see PaletteV, PaletteV and Service_ModeChanging.

The new computers fitted with VIDC20 vary in their video capabilities. The monitor type, video bandwidth and video RAM parameters allow a mode provider to supply screen modes with identical resolutions but different frame rates, tuned to the particular monitor and computer combination being used. However, any workspace parameters returned must be the same, as the mode number is used as an identifier in sprites and in calls such as OS_ReadModeVariable.

This service call is not issued for combinations that RISC OS itself already supports.

Monitor types are allocated by Acorn. There are no monitor types pre-reserved for general use by users.


Service_EnumerateScreenModes
(Service Call &8D)

Enumerates the available screen modes

On entry

R1 = &8D (reason code)
R2 = number of modes to skip
R3 = monitor type
R4 = memory bandwidth available (in bytes/sec)
R5 = total amount of video RAM in system (in bytes)
R6 = pointer to block to return data, or 0 to just count entries
R7 = size of block (in bytes) if R6 [NOT EQUAL] 0, or 0 if R6 = 0

On exit

R1 = 0 if claimed (further valid modes are available, but would not fit in block); else preserved
R2 = - (number of modes filled in)
R3 - R5 preserved
R6 = pointer to byte after last one filled in, or preserved if 0 on entry
R7 = amount of unused space in block, or - (amount of space needed in block) if R6 = 0 on entry

Use

This service call enumerates the available screen modes. Modules return information on all modes they provide that work on the specified monitor type and which require no more than the specified memory bandwidth and video memory.

OS_ScreenMode 2 provides a front-end for applications; you should use it rather than issuing this service call yourself.

By setting R6 and R7 to zero, clients can find the amount of space required to hold all returned modes; they can then issue the call again to actually read the information. Alternatively, clients can use a fixed size buffer, and repeatedly issue the call until it is no longer claimed. When using this method, R2 on entry - the number of modes to skip this iteration - should be set to:

(previous R2 on entry) - (R2 on exit)

This is the same as:

(number of modes skipped last time) + (number of modes filled in this time)

Each mode returned in the block is of the following format:

Offset Value
0 size of entry in bytes (24 for this format)
4 mode provider flags:
bit 0 = 1
bits 1 - 7 = mode info format specifier (zero for this format)
bits 8 - 31 = additional mode info flags (must be zero)
8 x-resolution (in pixels)
12 y-resolution (in pixels)
16 pixel depth (as for mode selector)
20 frame rate (in Hz, to the nearest integer)
24 mode name, null terminated, and then padded with nulls until it is word aligned.
(For unnamed modes this will simply be a single word whose value is 0.)

Future modules may use different mode info formats, therefore callers should check bits 0 - 7 of the mode provider flags before extracting the other information in this block. If the caller doesn't recognise the mode info format for an entry, then it can skip the entry by using the size field at offset 0. For format checking purposes, bits 8 - 31 should be ignored.

Mode-providing modules that wish to respond to this service call should use this algorithm:

For each mode that they want to return
  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)

This service call is only issued under RISC OS 3.5 and later.

SWI calls


OS_SpriteOp 17
(SWI &65)

Checks the validity of a sprite area

On entry

R0 = 17
R1 = pointer to control block of sprite area

On exit

R0, R1 preserved

Use

This checks the validity of a sprite area. Other OS_SpriteOp calls do not make such checks, since it would slow them down too much. Instead it is your application's responsibility to make this call. You would typically call it once after loading a sprite file, to satisfy yourself of the data's integrity. For efficiency, you should not make this call within a redraw loop.

The validation treats offsets as unsigned numbers, and is as follows:

  • The offset to the first sprite is word aligned, and lies within the 'used' part of the sprite area
  • The offset to the free area is word aligned, and lies within the sprite area
  • FOR each sprite
    DO
    • The offset to the next sprite is word aligned, and lies within the 'used' part of the sprite area
    • The first bit used is 0 for a new type sprite, or is in the range 0 - 31 for an old type sprite
    • The last bit used is in the range 0 - 31
    • The offset to the image is word aligned, and lies within the sprite
    • The offset to the mask is word aligned, and lies within the sprite
    • The space allowed for the sprite image is sufficient to hold an image of the given width, height, and bpp (assumed to be 1bpp if the sprite's mode number is unknown)
    • The space allowed for the sprite mask is sufficient to hold one of the given width, height, and bpp (1bpp for a new type sprite, or assumed to be 1bpp if the sprite's mode number is unknown) OD

If the sprite area is invalid in some way, an error is generated in the usual way for a SWI; the V flag is set on exit, and R0 points to an error block.

Sprites with an unknown mode number are still allowed, because such sprites can usefully occur in sprite files.

These checks do not exclude sprites that conform to the definition of sprite areas, but include unusual features such as an extension area, or an unconventional palette size.

This call is only available from RISC OS 3.6 onwards.

Related SWIs

OS_SpriteOp 10, OS_SpriteOp 11

Related vectors

SpriteV


OS_ScreenMode
(SWI &65)

Performs miscellaneous operations for screen mode handling

On entry

R0 = reason code
Other registers depend upon the reason code

On exit

R0 preserved
Other registers depend upon the reason code

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This SWI performs miscellaneous operations for screen mode handling.

The particular action of OS_ScreenMode is given by the reason code in R0 as follows:

R0 Action
0 Selects a screen mode
1 Returns the mode specifier for the current mode
2 Enumerates the available screen modes
3 Reserved for system use

This call is only available from RISC OS 3.5 onwards.

Related SWIs

None

Related vectors

None


OS_ScreenMode 0
(SWI &65)

Selects a screen mode

On entry

R0 = 0 (reason code)
R1 = mode specifier

On exit

All registers preserved

Use

This call selects the given screen mode.

Mode number used

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 the mode number 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; the module which responds to this passes back a workspace list, which contains a base mode (that must be known to RISC OS) and a list of changes to mode variables.
  • In certain circumstances a substitute mode can be used
Mode selector used

If a pointer to a mode selector is given, then a new mechanism is used:

  • The mode variables are set from the values given in the mode selector block. Any mode variables which are not specified are given sensible defaults, based on the specified x and y resolutions and the pixel depth (see below). Note that RISC OS copies away the relevant information, so mode selector structures need not remain valid after the call has returned.
  • If the specified mode cannot be selected for any reason, then an error is always returned.

The default values for any unspecified 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 if yres >= xres/2, or 2 if yres < xres/2
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, but only if RISC OS does not know the video timings for the resolutions/pixel depth/frame rate asked for. The module responding provides only timing and other hardware control information, and not any mode variable values.

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, i.e. palette entries get modified in groups of 16. This is so that programs which expect the old behaviour work in these modes without modification.

To gain access to fully-palette-programmable 256 colour modes, you should explicitly set these variables:

Variable Value
ModeFlags 128
NColour 255

All 256 palette entries then become programmable, although they are initially identical to those on a VIDC1-based machine.

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 and then switch screen banks.


OS_ScreenMode 1
(SWI &65)

Returns the mode specifier for the current mode

On entry

R0 = 1 (reason code)

On exit

R1 = mode specifier

Use

This call returns the mode specifier for the current screen mode.

If the current screen mode was selected by a mode number then that mode number is returned; otherwise a pointer to a mode selector is returned.


OS_ScreenMode 2
(SWI &65)

Enumerates the available screen modes

On entry

R0 = 2 (reason code)
R2 = value of R2 to pass to Service_EnumerateScreenModes
R6 = value of R6 to pass to Service_EnumerateScreenModes
R7 = value of R7 to pass to Service_EnumerateScreenModes

On exit

R1 = value of R1 returned by Service_EnumerateScreenModes
R2 = value of R2 returned by Service_EnumerateScreenModes
R6 = value of R6 returned by Service_EnumerateScreenModes
R7 = value of R7 returned by Service_EnumerateScreenModes

Use

This call provides a front-end to Service_EnumerateScreenModes. It fills in R3 (the current monitor type), R4 (the memory bandwidth available) and R5 (the total amount of video RAM), and then issues the service call.


OS_ScreenMode 3
(SWI &65)

This reason code is for system use only; you must not use it in your own code.


ScreenModes_ReadInfo
(SWI &487C0)

Reads the current monitor title

On entry

R0 = 0 (reason code => read current monitor title)

On exit

R0 = pointer to current monitor title

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call reads the current monitor title, as loaded from the current ModeInfo file. It is used by the Display Manager to show the monitor title in its title bar.

Future versions of RISC OS may add other reason codes to this call.

This call is only available from RISC OS 3.5 onwards.

Related SWIs

None

Related vectors

None

* Commands


*LoadModeFile

Loads a ModeInfo file into memory

Syntax

*LoadModeFile filename

Parameters

filename a valid pathname specifying a file

Use

This command loads a ModeInfo file into memory. If the file contains valid information, it sets the current monitor type to 7 (file). This then makes available all the screen modes defined in the file, while removing all modes defined in any previously loaded file.

This command is only available from RISC OS 3.5 onwards.

Example

*LoadModeFile adfs::MHardy.$.Modes.AKF50

Related commands

None


*VIDCBandwidthLimit

This command is for internal use only; you must not use it in your own code.

This command is only available from RISC OS 3.5 onwards.

This edition Copyright © 3QD Developments Ltd 2015
Last Edit: Tue,03 Nov 2015