RISCOS.com

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

 

VDU Drivers


Introduction

Though strictly speaking part of the character output system, the VDU drivers are quite complex, and deserve a chapter of their own. This chapter introduces the important concepts relating to the VDU, such as:

  • screen modes
  • graphics and text windows
  • colour palette
  • colour patterns
  • the mouse
  • putting text and graphics on the screen
  • multiple display pages

The Character Output described how to write to the VDU. This chapter describes what special effects occur when particular characters are sent.

There are also a large number of VDU specific commands that allow fine control of its operation.

There are five important aspects of VDU interaction which are not described in this chapter. These are:

  • the Font manager
  • the Window manager
  • the Draw module
  • Sprites
  • the ColourTrans module

These are implemented as modules separate from the RISC OS kernel, and are described in their own chapters.

Overview

The most important call relating to the VDU is OS_WriteC, as this is used in nearly all programs which have to output to the screen. Other calls can be used for more direct control of the VDU facilities.

The VDU display on RISC OS comes from the VIDC chip. This reads the contents of a block of memory and converts it into a form that can drive a video monitor.

VDU commands

This chapter differs from others in this manual in that, in addition to a list of SWIs and *commands, there is also a list of VDU commands. To issue VDU commands, simply use OS_WriteC to send characters to the VDU stream. All characters are strictly VDU commands, but those between 0 and 31, and 127 are of special interest because they cause special actions to take place. The others are simply printed on the screen as a character.

These special characters are used as commands. They can be followed by a sequence of characters, the length of which depends on the command. In some cases, the character on its own is sufficient, but it can require up to 9 following bytes to complete the command. These bytes are queued until the required number are in the queue before the command is executed.

To represent these sequences of characters sent to the VDU using OS_WriteC, a shorthand is used in this chapter. You will see VDU followed by numbers separated by commas. This represents each character being sent through OS_WriteC.

For example, VDU 65 sends character 65, an ASCII 'A', to OS_WriteC. VDU 17,3 sends character 17 followed by character 3.

Modes

RISC OS supports many different ways of displaying information on the screen. Each of these different ways is called a mode. The exact number of modes available depends on the type of monitor you have. They are all bit-mapped displays, in which one or more bits of screen memory control the colour of a dot, or pixel, on the screen. Two main characteristics distinguish the modes.

  • The resolution of a mode relates to the number of pixels which can be displayed horizontally and vertically.
  • The number of colours that can be displayed at once is determined by the number of bits used to store each pixel. Typically, this can be 1, 2, 4 or 8 bits, leading to 2, 4, 16 or 256 colours on the screen at once.

Between them, the resolution and number of colours determine the amount of screen memory used by a mode.

A complete list of the available modes is given in the description of VDU 22, which is the command that changes modes.

Text and graphics

There are two distinct types of object that the VDU drivers can draw onto the screen.

  • The text VDU deals with drawing text characters
  • The graphics VDU handles any arbitrary drawing of dots, lines, shapes, etc.
Windows

Different commands will act to either text or graphics areas. Each has a window, or area where their output will go. After a mode change, both text and graphic windows fill the screen and overlap each other exactly. There is no conflict in having them overlap, since the window is just a declaration of boundaries. Either window can be changed at any time to be any size. Any output to a window will be clipped to it. For example, if only part of a line appears in the graphics window, then only that part will be shown and the rest ignored.

A cursor is the place at which the next output will go. There are independent text and graphics cursors, which must remain inside their relevant window.

Various control commands are provided to affect the output in text and graphics windows. Examples of such actions are:

  • changing the colours in which output occurs,
  • moving the appropriate cursor,
  • clearing the window.
Text VDU

Text characters are patterns of pixels which are positioned on the screen at character-aligned positions. That is, the screen is treated like an array of character sized boxes, into which can go any printable character.

All text display is normally confined to the text window. All scrolling is confined to this region, sometimes called the scrolling window, because text can be scrolled within it. The graphics window cannot be scrolled automatically; but you can use block move to perform scrolling.

The text cursor shows the position on the screen of the next character to be displayed. This is usually a flashing underline. There can be a second cursor which is used with cursor editing (this is described later).

Note that there are some screen modes that will only display text.

Graphics VDU

The graphics VDU handles the drawing of objects such as points, lines, circles, ellipses, etc. The graphics window, like the text window, starts as the whole screen after a mode change. The graphics cursor, which is invisible, marks the last point at which a graphics operation ended.

Joining text and graphics

The VDU driver can be configured to print text at the graphics cursor instead of the text cursor. This means that text will be drawn using the current graphics cursor for positioning, and using the graphics colour, etc. The advantage of this mode is that it enables characters to be drawn at any pixel alignment, and to be clipped to the graphics window (important when you use the Wimp environment). The disadvantages are that the characters take longer to draw and scrolling is not available. Generally, when text is printed at the graphics cursor, this is referred to as VDU 5 mode because this is the command that enables it.

Cursor editing

Although the cursor editing facility isn't strictly part of the VDU drivers, its presence does have some interaction with the VDU.

Usually there is only one text cursor, but when you press one of the four cursor direction keys, cursor editing mode starts. There are now two cursors; the output cursor, which is now shown as a steady 'blob', and the input cursor, which is an underline flashing at twice the usual rate. The Copy key has the action of copying what is under the input cursor to the output cursor as if it was typed.

See the chapter entitled Character Input for a full description of these keys and their control.

Cursor editing mode is not available in VDU 5 mode, and it is cancelled when you send an ASCII 13 (carriage return) to the VDU stream. This is usually done when you press Return at the end of an input line.

Colours

The number of colours available on the screen at any time is either 2, 4, 16 or 256. When you first enter a mode, the default colours are assigned. These can subsequently be changed with the palette.

256-colour modes

In 256 colour modes, there are 64 different colours, and each colour may have four different shades, resulting in a total of 256 different colours.

Foreground and background

You may choose to display your text or graphics in a different colour from the defaults. To do this, there are commands to change the foreground and background of each. Usually, the foreground colour is that in which the text or graphics drawing is done, and the background colour is used for all other drawing, such as a screen clear. RISC OS can be changed so that the background colour is used for drawing if required.

The palette

Another important part of the VDU is the palette. This is the control of what colours appear on the screen. The palette is a table built into the VIDC chip which determines the relationship between the colour number stored in the screen memory (logical colour), and the actual colour information sent to the monitor (physical colour). Care should be taken not to confuse logical and physical colours. Thus, while colour 0 on RISC OS is black by default, it can be made to be any colour by changing how the palette maps it.

The palette is programmed in terms of the intensity of the signal on each of the red, green and blue guns in a colour monitor. These intensities have 4 bits each, which gives twelve bits altogether, hence the 4096 (212) physical colours. Flashing colours are accomplished by a logical colour having 2 physical colours associated with it. These are swapped at a programmable rate, causing flashing.

The palette also controls the colour of the border around the screen and the colours of the mouse pointer. These can be set independently of any other colour on the screen.

Tints

In 256 colour modes, each pixel is represented by an 8-bit value. Six bits are the logical colour, and the other two bits are the tint. The tint is a direct control of the amount of grey which is added to the base colour, to one of 4 levels.

The six bits in the logical colour set the basic colour from the range of different shades of colours provided by the palette. The tint is the fine control within this range.

ECF patterns

The Extended Colour Fill patterns are a means of increasing the apparent number of colours by producing a fine chequerboard mix of colours. This is of most use in modes where there are few colours available, because it gives the effect of having more colours on the screen than there are.

Four different ECF patterns are provided, and can be independently defined.

Normally, the origin of the ECF patterns is based on the bottom left corner of the screen. This can be changed, so that it aligns with any point on the screen, such as the current graphics window.

Bell

The VDU drivers control how the bell will sound. The bell is a sound that is made when the standard ASCII character 7 (Ctrl-G) is sent to the VDU. Its volume, pitch and duration can all be customised.

Mouse and pointer

The mouse is a device that is moved on a surface, rolling an internal ball, usually with several buttons. The pointer is a reflection on the screen of the mouse's movements. Normally, it appears as a small arrow, but can be programmed to be any shape. It is also possible to disconnect the pointer from the mouse and move the pointer to where the program wants it to be. This is useful when switching between windows under program control.

RISC OS provides control over how much the pointer moves in response to a mouse movement. This sensitivity control can be useful in situations where fine or coarse movement is required by different programs.

Screen configuration

Full control is given over how video information is generated. Depending on how it looks on screen, the display can be shifted up or down. Some monitors do not allow for this adjustment, so this facility is provided.

Also, the interlace can be switched on or off. Interlace means that images sent to a monitor alternate one scan line up and down on alternate frames. On a monitor which has a long persistence phosphor (images take some time to fade), an interlaced image eliminates the 'lined' effect of a screen image. On a short persistence screen interlace can cause a flicker, because the first image has faded before the second one is finished.

RISC OS supports many different kinds of monitor. Depending on the type of monitor used, only a subset of all possible modes are available on it. Thus there is a command to set which monitor is connected, so that incorrect modes are not accidentally entered.

Multiple banks

Normally, there is one bank of memory that is used for the screen. If it is changed, then this is reflected on the screen as it is refreshed by VIDC. Sometimes it is useful to write to one bank of screen memory, while another is displayed and then swap when finished. This produces an 'instant draw' effect, which is visually pleasing.

Whilst normally only two banks would be used for this kind of application, you can have as many banks as will fit in the allocated screen RAM area. This requires copies of the screen RAM requirements for each bank. For example, with two banks of screen memory, an 80K mode will require 160K.

Writing to the screen

Many different kinds of things can generate output on the screen, or more strictly speaking, the current screen bank. Text or graphics can be written, and many commands exist to alter where and how output will appear on the screen.

Writing text

Sending printable characters through OS_WriteC will result in it appearing at the text cursor position in the current window. It will wrap around to following lines when it reaches the right hand side of the window. Certain control commands can move the text cursor in all directions or to a given place in the window. Usually, the cursor moves right after a character is printed. This can be changed so it moves in any of the four directions.

Writing graphics

Many different kinds of graphics can be put onto the screen, such as:

  • circles, ellipses, arcs, segments, and sectors
  • triangles, rectangles and parallelograms
  • filled areas, such as all those above and any irregular shape
  • dots
  • solid and dotted lines
  • text in VDU 5 mode

See the chapter entitled Sprites to see how any sized array of pixels can be written to the screen.

As well as different shapes, there is control over how it is written over what is already on the screen. It can be configured to:

  • overwrite existing graphics,
  • OR with it,
  • AND with it,
  • exclusive OR with it,
  • invert it,

and so on.

As well as having control over the colour and writing mode, you can use any of the ECF patterns to write with.

Clearing the screen

The graphics or text windows can either be completely or partially cleared. This will be done with the current graphics or text background colour as appropriate.

Synchronised writing

There is a method under RISC OS of waiting until a Vsync event occurs and then writing to the screen. This can make screen update very smooth, as writing to the screen memory does not clash with the VIDC chip reading it to send to the monitor. If they do clash, then a 'tearing' can appear briefly. This is because one part of the memory being written to is displayed in its old state and the other part in the new.

Unless you plan to use multiple paging techniques, then this is a good way of achieving smooth animation.

Reading from the screen

As well as writing to the screen, it is possible to read some information back from it. There is a command to read a character from under the text cursor and work out what its ASCII value is. Cursor editing uses this facility.

You can also read the logical colour and tint of a point. Given that there is another call to return the palette setting for a colour, it is easy to combine the two and work out the 'real' colour of pixels on the screen.

The screen can be saved as a file, which can be subsequently treated as a sprite, or edited with Paint for example. There is a complementary command to load it back onto the screen.

Information about the VDU

There are a number of calls to get all kinds of information about the configuration and status of the VDU driver. Here is some of the information that can be read:

  • size and position of graphics and text windows
  • position of graphics and text cursors
  • description of current screen mode
  • size of screen memory
  • palette mapping
  • foreground and background text and graphics colours
  • banks used by VDU and screen
  • number of bytes queued for a VDU command being composed
  • number of lines printed since last page halt
  • in VDU 5 mode or not.

VDU extension vector

The normal VDU driver can be completely replaced with a custom driver if required. The VDU extension vector, called VDUXV, can be called instead of the normal VDU vector. This can be useful if you want to change the characteristics of screen output in a dramatic way.

Technical Details

VDU commands

As mentioned earlier, 'VDU' followed by a series of numbers separated by commas is used in this chapter to represent a character being sent to OS_WriteC. For convenience, we will use the shortcuts that BBC BASIC uses with its VDU statement. Here is a brief reminder of the syntax of that statement:

  • VDU n sends character n to OS_WriteC. VDU m,n sends ASCII m followed by ASCII n.
  • VDU n; sends the number n as two bytes, first n MOD &100, then n DIV &100. This sends 16-bit numbers to the VDU drivers; eg coordinates in graphics commands.
  • VDU n| sends n as a single byte, followed by eight 0 bytes. This is used as shorthand in calls in which not all of the parameter bytes are needed. As nine is the largest number of bytes required by any VDU sequence, ending the command with '|' guarantees enough bytes to complete it. Any extra zeros are ignored by the VDU drivers.

Of course, as long as the correct characters are sent to the VDU, it doesn't matter how they get there. For example, an assembly language equivalent to VDU 12 (clear screen) is:

SWI OS_WriteI+12

The effect is the same in both cases.

Screen modes

When changing mode, a great many things are initialised. For a complete list of these and other mode notes, see VDU 22.

*Configure Mode will set up the screen mode to be used after a hard reset.

When a program wishes to change mode, it must check that there is enough memory allocated for the screen for that mode and that the monitor being used is compatible with the mode. OS_CheckModeValid must be called to check these two things. If you don't, then VDU 22 will do it anyway, but it is better for the program to be aware of what's happening. If the mode requested cannot be used, OS_CheckModeValid will also return a suggestion for a mode to use in place of it.

Screen configuration

The computer can adjust its output to suit its attached monitor in a number of ways.

*Configure MonitorType is used to tell RISC OS to auto-detect the type of monitor connected from its lead, or - should it be unable to do so from hardware - to tell it explicitly what kind of monitor is attached. This command allows the system to subsequently disallow any modes that are not compatible with the attached monitor.

*Configure Sync will set up the vertical sync output of the video connector to be auto-detected, or to be vertical or composite sync. Different monitors may require either of these, though most use composite sync.

*Configure TV, *TV and OS_Byte 144 can all adjust the position of the video output up or down by several lines, and switch interlace on and off. VDU 23,0 can also control the interlace setting.

Multiple bank modes

There are two main commands that can be used to handle multiple banks of screen memory. OS_Byte 112 selects which bank of memory to send VDU output to. OS_Byte 113 selects which bank of memory is used by the VIDC hardware to write out to the screen. By using these two, it is simple to swap screens at will.

OS_Byte 250 reads the current OS_Byte 112 setting, and OS_Byte 251 reads the current OS_Byte 113 setting.

In order to use multiple banks, you will probably have to use *Configure ScreenSize to set the amount of memory to reserve for all the banks.

*Shadow exists mainly for compatibility with BBC/Master operating systems. Under RISC OS, it can select between two banks of memory to be used on the next mode change. OS_Byte 114 has the same effect as *Shadow. OS_Bytes 112 and 113 support the shadow system, but you are better off using bank numbers directly.

For those who want low level access to screen banks, OS_Word 22 allows setting the addresses of the VDU bank and the VIDC bank directly.

Colours

These are the colours as set up after a mode change:

Two-colour modes

0 = black
1 = white

Four-colour modes

0 = black
1 = red
2 = yellow
3 = white

16-colour modes

0 = black
1 = red
2 = green
3 = yellow
4 = blue
5 = magenta
6 = cyan
7 = white
8 = flashing black-white
9 = flashing red-cyan
10 = flashing green-magenta
11 = flashing yellow-blue
12 = flashing blue-yellow
13 = flashing magenta-green
14 = flashing cyan-red
15 = flashing white-black

256-colour modes

256 colour modes are treated differently from the others. Instead of using the standard 16 entry physical colour table, there are two systems which are used by different commands. The internal format is the less easy to use of the two. In it, the bits are structured as follows:

    Bit Meaning
    0 Bit 0 of palette index
    1 Bit 1 of palette index
    2 Bit 2 of palette index
    3 Bit 3 of palette index
    4 Red bit 3 (high)
    5 Green bit 2
    6 Green bit 3 (high)
    7 Blue bit 3 (high)

where the palette index (0 - 15) controls which VIDC palette entry is used, but with some bits of the palette entry then being overridden by the top 4 bits of the memory byte. With the default palette setting, this becomes:

    Bit Meaning
    0 Tint bit 0 (red + green + blue bit 0)
    1 Tint bit 1 (red + green + blue bit 1)
    2 Red bit 2
    3 Blue bit 2
    4 Red bit 3 (high)
    5 Green bit 2
    6 Green bit 3 (high)
    7 Blue bit 3 (high)

Each primary colour has 4 bits of intensity, but the two least significant bits (the tint bits) are shared between the three colours. Therefore, some intensities of a primary colour (for example, red) can only be obtained at the expense of adding in a certain amount of grey.

The second form for 256 colours, which is used by some commands is structured as follows:

    Bit Meaning
    0 Red bit 2
    1 Red bit 3 (high)
    2 Green bit 2
    3 Green bit 3 (high)
    4 Blue bit 2
    5 Blue bit 3 (high)
    6 Tint bit 0 (red + green + blue bit 0)
    7 Tint bit 1 (red + green + blue bit 1)

The tint is controlled separately in most commands; bits 6 and 7 are only used in the native ECF setting, which is not often used in 256 colour modes.

This format is converted into the internal format when stored, because that is what the VIDC hardware recognises.

To change colour

VDU 17 can be used to change the text colour. VDU 23,17,5| will exchange the text foreground and background colours.

VDU 18 can change the graphics colour, and much more than just that. Because graphics can interact with what is already is on the screen, then VDU 18 can set up the graphics to be ORd, ANDed, XORd, inverted and so on.

In 256 colour modes, VDU 23,17,0 - 3 can be used to set the tints to be used when next printing/plotting.

Palette

VDU 19 can be used to change the way that the palette defines the logical to physical colour relationship. It has many modes and as well as changing the logical colours, can also set the border, flashing and pointer colours. OS_Word 12 can also be used to write the palette.

VDU 20 will return the palette to the condition that it was just after a mode change. This would be used by a program just before finishing, if it had altered the palette during running.

If you want to read the palette setting of a colour, OS_ReadPalette or the BBC/Master compatible OS_Word 11 can be used.

Flashing colour

RISC OS will swap two colours at a programmed interval. If they are the same colour, then there is no noticeable effect. If they are different, then flashing will result. VDU 19 can individually set these colours to be any colour from the palette.

The speed at which flashing occurs can be controlled by OS_Bytes 9 and 10. They set the duration in video frames. VDU 23,9 and VDU 23,10 have the same effect as these calls. The duration settings can be read by OS_Bytes 194 and 195.

OS_Byte 193 allows a program to read or alter the flash counter. This is a decrementing counter that swaps colours when the count reaches zero.

ECF patterns

There are several different ways of changing ECF patterns. The main command is VDU 23,2-5. This can operate in two modes depending on the setting of VDU 23,17,4. Also, VDU 23,12-15 can be used for simpler patterns.

Colours and resolution

Both commands are passed 8 bytes that define the pattern. The number of pixels depends on how many colours are available in the screen mode you are using:

    Colours available Number of pixels set by each line
    VDU 23,2-5 VDU 23,12-15
    2 8 2
    4 4 2
    16 2 2
    256 1 1

You can see that while the number of pixels in the pattern diminishes, the number of potential colours increases.

256 colour patterns

As you can see, in a 256 colour mode, the pattern is simply a colour description for each line. VDU 23,2-5 uses the internal 256 colour map, while VDU 23,12-15 uses the simpler colour map. When stored, the internal form is used. This should be borne in mind if you use OS_Word 10 to read the ECF definitions.

VDU 23,12-15

This call uses a simpler pattern. The 8 parameters passed form a pattern as follows:

So it describes a simple 2 by 4 pattern for all but 256 colour modes. Here it is one colour per line, for all 8 lines, like VDU 23,2-5.

VDU 23,2-5

This call is more complex. It uses one line per parameter, and there is a direct trade-off between colours and resolution. Thus, for a 2 colour mode, it can display an 8 by 8 pattern of on or off pixels, in 256 colour mode, it can only generate 8 lines of a single different colour each.

VDU 23,17,4

VDU 23,17,4 is used to select between BBC/Master compatible mode and native RISC OS mode. These modes describe how ECF colour descriptions are mixed when using VDU 23,2-5. For some examples, see the chapter entitled Application Notes.

Initialisation

VDU 23,11 will reset the ECF pattern definitions to their default values. It will also reset the VDU 23,17,4 flag to the default BBC/Master compatible state.

Setting the origin

By default, patterns are written as if their bottom left hand corner is aligned with the bottom left hand corner of the screen. Using OS_SetECFOrigin, you can instead align an ECF pattern to any point on the screen, or to an object such as the graphics window. VDU 23,17,6 has the same effect as this call.

Bell

The bell can be made to sound by sending a VDU 7 to OS_WriteC.

To configure how it will sound:

*Configure Quiet will select a quiet volume, while *Configure Loud will select a loud volume.

Cursors

VDU 5 will link text and graphics cursors and cause all subsequent output to be printed at the graphics cursor position. This command can be cancelled using VDU 4. The text input cursor is normally displayed unless disabled by VDU 23,1. Both this and VDU 23,0 can be used to change the appearance of the cursor.

There are a number of VDU commands that affect the position of the text cursor directly:

  • VDU 30 - send the text cursor to its home position, which is usually the top left corner of the current window.
  • VDU 31 - set the text cursor to any position on the screen.
  • VDU 8 - backspace
  • VDU 9 - horizontal tab
  • VDU 10 - linefeed (ie move down)
  • VDU 11 - vertical tab (ie move up one line)
  • VDU 13 - move back to the start of the line
  • VDU 127 - delete (ie backspace, print a space then backspace again).

The position of the text cursor can be read with OS_Byte 134. If cursor editing is in progress, then OS_Byte 165 can be used to read the position of the output cursor, usually displayed as a solid blob.

Normally, when a character is printed, the cursor currently used will move to the right. This action can be controlled by VDU 23,16. It can set the cursor to move in any of four directions. It also controls how cursors act at the end of lines, and so on.

OS_RemoveCursors will remove the input and output cursors and store their state internally. A subsequent call to OS_RestoreCursors will restore them exactly. These calls are used mainly by low-level draw routines to avoid mixing the cursors with what is drawn on the screen.

OS_Word 13 will return the current and previous graphics cursor positions. Using OS_ReadVduVariables, even earlier coordinates can be read.

Mouse and pointer

When a mouse button is pressed or released a record is kept in the mouse buffer. OS_Mouse will read a mouse record from this buffer. It stores the position of the mouse, the state of its buttons and the time the record was put into the buffer. OS_Byte 128 can also be used for this as well as reading how much free space is in the mouse buffer.

OS_Word 21,3 will set the mouse position, so subsequent writes to the mouse buffer will assume the mouse is at the specified location, and move from there.

OS_Word 21,4 will read the unbuffered mouse position. That is, where it is at the moment of calling this function. This bypasses the buffer, so subsequent reads of the buffer may not tie up with this position. It is better to use one or the other method exclusively in a program.

Pointer

The ratio of mouse movement to pointer movement on screen can be controlled by OS_Word 21,2 or permanently set by *Configure MouseStep.

The pointer that appears on the screen can be defined in four shapes. OS_Word 21,0 can define the shape and colour of each of these. OS_Byte 106 is used to select which pointer to use, or switch it off completely. *Pointer can also be used to switch it on or off.

The pointer will be confined to the box defined by OS_Word 21,1. This would usually be set to the graphics window.

The pointer's position on the screen can be set with OS_Word 21,5 and read with OS_Word 21,6.

Getting information

There are many ways of extracting information about the state and configuration of the VDU system.

OS_Byte 217 will read the number of lines since the display was last stopped scrolling if it was in paged mode.

OS_Byte 218 returns how many bytes are in the VDU queue. This is used when a multiple byte VDU command is being collected.

OS_Byte 163 will return the current dot-dash line length and the amount of memory allocated for sprites. It can also set the dot-dash length.

OS_ReadDynamicArea is a better way to read the amount of memory allocated for system sprites - this call will also return the memory allocated for screen bank use.

OS_Byte 117 reads the VDU status. This involves:

  • whether the printer output is enabled
  • if paged scrolling is enabled
  • if in shadow mode
  • if in VDU 5 mode
  • if cursor editing
  • if the screen is disabled with VDU 21

OS_ReadVduVariables provides a large number of variables that can be read. OS_Byte 160 is a subset of this, kept for BBC/Master compatibility reasons. Almost all information about windows, cursors and colours can be accessed here. Two special variables provided are a pointer to a fast horizontal line draw routine and access to colour blocks.

OS_ReadModeVariable returns the fixed information about a mode, such as how many pixels across and down it is, and how many colours it supports.

Reading from the screen

OS_Byte 135 will read the ASCII value of the character at the text cursor position and also reads the current screen mode.

OS_ReadPoint will read the logical colour of a pixel. OS_Word 9 performs much the same function, but is kept mainly for compatibility with BBC/Master series.

*ScreenSave will copy the screen contents into a file where it can subsequently be edited with Paint or reloaded to the screen with *ScreenLoad.

Writing to the screen

Output to the screen can be disabled by VDU 21. It can be restored by VDU 6.

VDU 26 will restore the graphics and text windows to their default states. That is, both filling the screen.

Text

Text can be sent to the screen with any VDU command from 32 to 255, excepting 127 which is the delete command.

VDU 28 defines the text window. VDU 12 will clear the window that the text cursor is in. After a VDU 12, the text cursor is moved to its home position, usually the top left hand corner. VDU 23,8 will clear a block within the text window.

Paged mode means that when about 75% of a screenful has been shown, then the system will pause and wait for Shift to be pressed before starting again. This stops text being lost from scrolling off the top of the screen too quickly Paged mode can be enabled by VDU 14 and disabled with VDU 15. By default, paged mode is off.

*Configure Scroll and NoScroll configure whether text will scroll when it reaches the bottom of the text window. This means that when NoScroll is set a character can be printed at the bottom right of the screen without immediately scrolling the screen. This feature can also be controlled with VDU 23,16 and allows a full screen of text to be simply printed.

VDU 23,7 can scroll the text window or the whole screen in any direction.

In VDU 5 mode, it is possible to change the size and spacing of text with VDU 23,17,7. This is how you would generate a message with large gaps between the characters.

Redefining characters

Each printable character (one that is not a command) is an array of 8 by 8 pixels that is defined in the shape of standard ASCII and ISO characters. All of these characters can be redefined to be any pattern.

To change the definition of a printable character, VDU 23,32-255 must be used. The character number that you wish to redefine is the second parameter, in the range 32-255. It is followed by 8 bytes that define the bit pattern to be used.

OS_Byte 20 will reset character definitions 32 - 127 to their default. OS_Byte 25 will reset a given group of them. OS_Word 10 can read the definition of any character from the current system font.

Printer

VDU 1 will send the following character to the printer stream. VDU 2 will enable the stream, so that all characters sent to the VDU are also sent to the printer stream. This state can be disabled by VDU 3.

Graphics

VDU 24 will define the position of the graphics window. VDU 16 will clear it to the current graphics background colour.

VDU 25 is the main graphics plot command. OS_Plot has the same effect as it, but is much faster, avoiding the delays inherent in the VDU stream. They both have a type parameter followed by x and y coordinates. The type covers moving the graphics cursor, plotting points, lines (solid and dotted), triangles, rectangles, parallelograms, circles, arcs, sectors, segments, ellipses and other graphic forms. These figures can be hollow or filled with the graphics foreground colour. It handles relative or absolute drawing That is, the x and y are relative to the current x and y or moving to a new absolute position on the screen.

When plotting dotted lines, the default pattern is a dot-space pattern repeated. This can be changed to any pattern. VDU 23,6 is passed 8 bytes that define a pattern up to 64 bits in length to be repeated. OS_Byte 163 sets how many bits are to be used. Simple patterns like &FF (solid line), &AA (the default dot-space) and &EE (dashed line: dot-dot-dot-space) can be used or any more complex pattern up to 64 bits in length. OS_Word 10 can read the current definition.

VDU 29 sets the graphics origin. This is the point on the screen that becomes the 0,0 point for all subsequent graphics operations.

OS_ChangedBox will tell you what area of the screen has been changed. This can be used to reduce the amount of redrawing that needs to be done by an application.

*ScreenLoad complements *ScreenSave, discussed earlier and load a file into the screen memory.

Vsync

OS_Byte 19 will wait until a Vsync occurs before returning. This allows programs that are quick enough to write to the screen without any kind of flickering or tearing of images.

Screen memory and hardware scrolling

This is described fully in the Screen memory.

VDU Calls


VDU 0

Null Operation

Syntax

VDU 0

Parameters

--

Use

VDU 0 does nothing. It is this that enables the '|' character in the VDU statement to work. Any of the nine zeros that are sent which aren't required by the current VDU command are 'swallowed up'.


VDU 1

Next character to printer only

Syntax

VDU 1,character

Parameters

character - to send to the printer stream

Use

VDU 1 sends the next character to the printer stream only, provided that the printer has been enabled by VDU 2. Otherwise, the next character is ignored. This enables the printer ignore character, and any other character which is not usually passed on by the VDU printer driver, to be sent to the printer through the VDU.

Example

VDU 1,10 - Send a linefeed to the printer stream, if enabled


VDU 2

Enable printer stream

Syntax

VDU 2

Parameters

--

Use

VDU 2 enables the printer stream. After this call, most characters sent to the screen will also be sent to the currently selected printer device. OS_Byte 5 controls this, as described on OS_Byte 5. Only characters in the following ranges are sent to the printer: 32 - 126, 128 - 255 (ie the printable characters), 8 - 13 (backspace, horizontal tab, linefeed, vertical tab, form feed and carriage return, respectively). No multi-byte control sequences, except the argument of VDU 1, are sent to the printer.

Even if the VDU drivers are disabled (using VDU 21) the characters sent to the VDU drivers will still be sent to the printer although they will no longer affect the screen. However, if the VDU is disabled using OS_Byte 3, then VDU 2 printing will not take place.

The effect of VDU 2 can be cancelled using VDU 3.

You can determine whether VDU printing is enabled using OS_Byte 117.


VDU 3

Disable printer stream

Syntax

VDU 3

Parameters

--

Use

VDU 3 cancels the effects of VDU 2 so that all subsequent printable characters are not passed through the kernel printer driver.


VDU 4

Split cursors

Syntax

VDU 4

Parameters

--

Use

VDU 4 cancels VDU 5 mode. It causes all subsequent printable characters to be printed at the current text cursor position using the current text foreground and background colours. The text cursor is normally displayed (unless it has been disabled using VDU 23,1) and after each character has been printed the cursor moves on by one character. The direction of cursor movement is normally to the right but may be altered using VDU 23,16.

After a character has been printed at the end of a row (or column if vertical printing is used) the cursor moves on to the start of the next screen line (or column), scrolling the screen when there are no more rows (or columns), providing scrolling is enabled. Again, you can use VDU 23,16 to enable or disable scrolling. Cursor editing is allowed in this mode.

You can determine whether the cursors are split or joined using OS_Byte 117.


VDU 5

Join cursors

Syntax

VDU 5

Parameters

--

Use

This enters VDU 5 mode. It links the text and graphics cursors and causes all subsequent printable characters to be printed at the current graphics cursor position, the topmost row, lefthand edge of the character being placed there. Characters are displayed in the current graphics foreground colour using the current graphics action. The background pixels in the character shape are not plotted.

You can set the character sizing and spacing using VDU 23,17,7...

After the character has been printed, the graphics cursor is moved by one character position. The direction of cursor movement is normally to the right but may be altered (using VDU 23,16). It moves to a new row (or column if vertical printing is being used) when necessary, or to the opposite corner of the graphics window if there are no more rows (or columns). Scrolling does not occur.

This command allows characters to be placed at any position on the screen, but means that the text is printed somewhat slower than when the cursors are split. In addition, each character is superimposed onto the existing text or graphics. Hence, printing a backspace character followed by a space moves the graphics cursor back by one character and then superimposes a space onto the character already there, thereby leaving it unaltered.

Cursor editing is not possible in this mode.

VDU 5 has no effect in text-only or Teletext modes. In other modes it may be cancelled using VDU 4.


VDU 6

Enable screen output

Syntax

VDU 6

Parameters

--

Use

VDU 6 restores the functions of the VDU driver after it has been disabled by VDU 21. It causes all subsequent printable characters to be sent to the screen and control sequences to be obeyed.

You can determine whether the VDU is enabled or disabled using OS_Byte 117.


VDU 7

Bell

Syntax

VDU 7

Parameters

--

Use

VDU 7 generates the current bell sound. The initial default is specified by *Configure Loud/Quiet and *Configure SoundDefault; you may subsequently alter it using OS_Bytes 211 - 214.


VDU 8

Backspace

Syntax

VDU 8

Parameters

--

Use

VDU 8 causes either the text cursor (by default) or the graphics cursor (in VDU 5 mode) to be moved back one character position (ie in the negative x direction). This normally means moving it to the left but will be different if the direction of cursor movement is altered (using VDU 23,16).

If the cursor was at the start of a row (or column if vertical printing is used) then it is moved back to the end of the previous row (or column), scrolling the screen if necessary. It does not cause the last character to be deleted.


VDU 9

Horizontal tab

Syntax

VDU 9

Parameters

--

Use

VDU 9 causes either the text cursor (by default) or the graphics cursor (in VDU 5 mode) to be moved on one character position (ie in the positive x direction). This normally means moving it to the right but is different if the direction of cursor movement is altered (using VDU 23,16).

If the cursor was at the end of a row (or column if vertical printing is used) then it is moved on to the start of the next row (or column), scrolling the screen if necessary.


VDU 10

Linefeed

Syntax

VDU 10

Parameters

--

Use

VDU 10 causes either the text cursor (by default) or the graphics cursor (in VDU 5 mode) to be moved on one line (ie in the positive y direction). This normally means moving it down but is different if the direction of cursor movement has been altered (using VDU 23,16).

If the cursor was on the last line then the screen will be scrolled provided that scrolling is enabled.


VDU 11

Vertical tab

Syntax

VDU 11

Parameters

--

Use

VDU 11 causes either the text cursor (by default) or the graphics cursor (in VDU 5 mode) to be moved back one line (ie in the negative y direction). This normally means moving it up but will be different if the direction of cursor movement has been altered (using VDU 23,16).

If the cursor was on the first line then the screen will be scrolled, if scrolling is enabled.


VDU 12

Form feed/clear screen

Syntax

VDU 12

Parameters

--

Use

By default, VDU 12 clears either the current text window or, in VDU 5 mode, the current graphics window to the current text or graphics background colour respectively. The text or graphics cursor is moved to the text home position (see VDU 30).

When sent to a printer, this character generally causes a new page to be started.


VDU 13

Carriage return

Syntax

VDU 13

Parameters

--

Use

VDU 13 causes the text cursor or, in VDU 5 mode, the graphics cursor to be moved to the negative x edge of the relevant window at the same y value. The negative x edge is normally the left edge but it may be changed using VDU 23,16.

When sent to a printer, this character generally causes the print head to move to the start of the current line. Additionally, some printers may also generate a linefeed.


VDU 14

Paged mode on

Syntax

VDU 14

Parameters

--

Use

VDU 14 causes the screen display to wait for Shift to be pressed before the next scroll and periodically thereafter. Normally, approximately 75% of the number of lines in the current window is scrolled before it waits again. The effects of the command may be cancelled using VDU 15.

OS_Byte 117 may be used to determine whether paged mode is enabled. See also OS_Byte 217.


VDU 15

Paged mode off

Syntax

VDU 15

Parameters

--

Use

VDU 15 cancels the effect of VDU 14 so that scrolling is unrestricted.


VDU 16

Clear graphics window

Syntax

VDU 16

Parameters

--

Use

VDU 16 clears the current graphics window to the current graphics background colour using the graphics background action. It does not affect the position of the graphics cursor.


VDU 17

Set text colour

Syntax

VDU 17,colour

Parameters

colour - logical text colour

Use

VDU 17 is used to assign a logical colour to either the text foreground or background according to the value of colour, as follows:

    Value Colour
    0 - 127 foreground
    128 - 255 background (colour in range 0 - 127)

If the absolute value of the parameter lies outside the allowed set for the current mode, it is treated MOD (the number of colours - 64 in 256 colour mode) so that it lies within that range. For example, in mode 1, which allows four colours, the commands VDU 17,9 and VDU 17,5 are equivalent to VDU 17,1.

The interpretation of colour depends on the type of mode:

    Colours colour parameter meaning
    2,4,16 Logical colour for that pixel
    256 Bottom 6 bits of colour provide colour information:
      Bit 5 - Blue bit 3
      Bit 4 - Blue bit 2
      Bit 3 - Green bit 3
      Bit 2 - Green bit 2
      Bit 1 - Red bit 3
      Bit 0 - Red bit 2

This allows 64 different colours to be obtained. Each of these can be used in one of four different tints, giving 256 available shades. See VDU 23,17 for more details. The current text colours may be read using OS_ReadVduVariables.

Example
VDU 17,12
Set to logical colour 12

VDU 18

Set graphics colour and action

Syntax

VDU 18,action,colour

Parameters

action - operation to perform
colour - colour to use

Use

VDU 18 is used to define either the graphics foreground colour or the graphics background colour, and the way in which it is to be plotted on the screen.

The graphics plotting action is determined by action as follows:

    Value Action
    0 Overwrite colour on screen with colour
    1 OR colour on screen with colour
    2 AND colour on screen with colour
    3 exclusive OR colour on screen with colour
    4 Invert colour on screen
    5 Leave colour on screen unchanged
    6 AND colour on screen with (NOT colour)
    7 OR colour on screen with (NOT colour)
    8 - 15 As 0 to 7, but background colour is transparent
    16 - 31 Colour pattern 1 using action 0 - 15
    32 - 47 Colour pattern 2 using action 0 - 15
    48 - 63 Colour pattern 3 using action 0 - 15
    64 - 79 Colour pattern 4 using action 0 - 15
    80 - 95 Giant colour pattern (patterns 1 - 4 placed side by side)

The range 8 - 15 is used in the following circumstances:

  • If a sprite has a transparency mask, then plotting it using one of these actions causes the mask to be used.
  • Where the mask has a 0 bit, nothing is plotted; where it has a 1 bit, the appropriate sprite colour is plotted. If an action in the range 0 - 7 is used, the sprite mask is ignored. See the chapter on sprites for more details.

These actions are also used in colour pattern plotting. If a pixel in the pattern has the same colour as the current graphics background colour, it is not plotted but left transparent instead. (If the action is used when setting a background colour pattern, then the pixel is left unplotted if it has the same colour as the current graphics foreground colour.)

The graphics colour is determined by colour as follows:

    Value Meaning
    0 - 127 Foreground colour specified
    128 - 255 Background colour specified (colour in range 0 - 127)

If the absolute value of the parameter lies outside the allowed set for the current mode, it is altered so that it lies within the range (as for VDU 17).

Where action has specified a colour pattern, then colour is used only to determine whether the pattern is used for the graphics foreground or background colour (depending on whether it is less than 128 or not).

The interpretation of colour depends on the type of screen mode. See the table for VDU 17 above for details.

The current graphics colours and actions may be read using OS_ReadVduVariables.

Example

VDU 18,1,6 - Write, ORing with the screen in colour 6


VDU 19

Set palette

Syntax

VDU 19,logical colour,mode,red,green,blue

Parameters

logical colour - colour to set
mode - how to set the colour
red, green, blue - physical colour information

Use

VDU 19 defines the colour palette relationship. It causes a specified logical colour for either the screen, border or pointer to be represented by a given physical colour.

The action depends on the value of 'mode' as follows:

    mode = 0 - 15 logical colour = physical colour specified by mode parameter (see below);
    red, green and blue are ignored, and should be zero.
    mode = 16 both flash palettes for logical colour =
    red units red, green units green, blue units blue
    mode = 17 first flash palette for logical colour =
    red units red, green units green, blue units blue
    mode = 18 second flash palette for logical colour =
    red units red, green units green, blue units blue
    mode = 24 border colour =
    red units red, green units green, blue units blue;
    logical colour is not used, and should be zero
    mode = 25 logical colour (1 - 3) of pointer =
    red units red, green units green, blue units blue

If you add 128 to the 'mode' value, you also set the 'supremacy' bit of the appropriate palette entry. This is used when the computers' video is mixed with an external video source, to provide a superimposed image.

In all cases, the red, green and blue parameters have a range 0 - 255. However, as only the top four bits are significant, the 16 possible values are &0X, &1X, &2X,... &FX, where X means 'don't care'. The bottom nibble may be significant in future versions of the hardware - to cater for this you should replicate the top nibble in the bottom nibble, by multiplying each RGB component by 17/16. Therefore, &F0F0F000 becomes &FFFFFF00.

In normal non-flashing colours, what this means is that both of the flash colours are the same. RISC OS will swap colours at a programmed interval. If they are the same colour, then there is no noticeable effect. 'Mode' values of 17 and 18 allow any colour to be made to flash with any combination of colours.

There are 16 palette registers, which means that in modes with one, two and four bits per pixel, there is a register available for each of the logical colours. Therefore, each can be assigned a physical colour by a simple one-to-one relationship.

By default (after a mode change or VDU 20), the palette is set up using a setting where the 'mode' value is in the range 0 - 15. The actual colour number depends on the logical colour and the number of bits per pixel used in a given screen mode as follows:

    Logical colour Bits per pixel in a screen mode
    1 2 4
    0 0 0 0
    1 7 1 1
    2 3 2
    3 7 3
    4 4
    5 5
    6 6
    7 7
    8 8
    9 9
    10 10
    11 11
    12 12
    13 13
    14 14
    15 15

The meanings of the physical colours specified by the mode parameter when it is in the range 0 - 15 are:

    Physical colour Colour
    0 Black
    1 Red
    2 Green
    3 Yellow
    4 Blue
    5 Magenta
    6 Cyan
    7 White
    8 Black-white flashing
    9 Red-cyan flashing
    10 Green-magenta flashing
    11 Yellow-blue flashing
    12 Blue-yellow flashing
    13 Magenta-green flashing
    14 Cyan-red flashing
    15 White-black flashing

In modes with eight bits per pixel the situation is more complex. A simple mapping of the logical colour to the physical colour via the palette is not possible. Instead, the eight bits of the logical colour are treated as two nibbles as follows:


Treatment of logical colours in eight bit per pixel modes

Bit 7 goes directly to the top bit of blue
Bit 6 goes directly to the top bit of green
Bit 5 goes directly to the second bit of green
Bit 4 goes directly to the top bit of red

By default, the palette registers are set to have the following effect:

Bit 3 is sent to the second bit of blue
Bit 2 is sent to the second bit of red
Bit 1 is sent to the third bits of blue, green and red
Bit 0 is sent to the fourth bits of blue, green and red

Hence the palette cannot be used to produce extreme effects upon the colour; it does not have any effect upon the top (most significant) bits of any colour or the second bit of green. It can only control the second bits of blue and red, and the white tint which is obtained by the settings of all three of the third and fourth (least significant) bits.

You can also set the palette using OS_Word 12, and read the current palette using OS_Word 11 and OS_ReadPalette.

Example

VDU 19,5,12,0,0,0 - Set logical colour 5 to be physical colour 12


VDU 20

Restore default colours

Syntax

VDU 20

Parameters

--

Use

VDU 20 restores the default palette for the current mode. It also resets the default text and graphics background colour to black, and the text and graphics foreground colour to white. The graphics foreground and background actions are set to 0 (overwrite). In 256-colour modes the tints are set to their default values (0 for background tints and &C0 for foreground ones).


VDU 21

Disable screen display

Syntax

VDU 21

Parameters

--

Use

VDU 21 prevents the VDU screen drivers performing any of their normal functions until a VDU 6 is issued. Any control sequences sent to the VDU drivers are queued in the usual way. Therefore, sending the character VDU 19 causes the next 5 characters to be treated as parameters for this (ignored) command.

For example, the sequence VDU 22,6 is treated as one whole command in the usual way and not as VDU 22 followed by VDU 6 which would re-enable the VDU drivers.

This command does not prevent characters from being sent to the VDU printer driver (if already enabled by a VDU 2), or any of the other output streams.

You can use OS_Byte 117 to determine whether the VDU driver is currently enabled or disabled.


VDU 22

Change display mode

Syntax

VDU 22,mode

Parameters

mode the screen mode to select

Use

VDU 22 is used to select a screen mode. The bottom seven bits of the mode parameter are used to select the mode. The modes available in RISC OS depend on the configured monitor type (see *Configure MonitorType on *Configure MonitorType) and the model of computer. Below is a table of all modes provided by RISC OS, which shows:

  • the mode number
  • the text resolution in columns × rows
  • the graphics resolution in pixels, which corresponds to the clarity of the mode's display
  • the resolution in OS units, which corresponds to the area of workspace shown by the mode
  • the number of logical colours available
  • the memory used to display the screen (to the nearest 0.1Kbyte)
  • the vertical refresh rate to the nearest Hz (invalid for monitor type 5), which indicates the degree of flickering that you may perceive
  • the bandwidth used to display the screen (to the nearest 0.1Mbyte/second), which corresponds to the load the mode places on the computer
  • the monitor types that support that mode:

      Type Monitor
      0 50Hz TV standard colour or monochrome monitor
      1 Multi-frequency monitor
      2 64Hz high-resolution monochrome monitor
      3 60Hz VGA-type monitor
      4 Super-VGA-type monitor (not available in RISC OS 2)
      5 LCD (liquid crystal display) (not available in RISC OS 2)

  • the notes on the following page that are relevant to the mode.

Mode Text
resolution
Pixel
resolution
OS units
resolution
Logical
colours
Mem
used
Refresh
rate
Band-
width
Monitor
types
Notes
0 80 × 32 640 × 256 1280 × 1024 2 20K 50Hz 1M/s 0,1,3,4,5 (3)
1 40 × 32 320 × 256 1280 × 1024 4 20K 50Hz 1M/s 0,1,3,4,5 (3)
2 20 × 32 160 × 256 1280 × 1024 16 40K 50Hz 2M/s 0,1,3,4,5 (3)
3 80 × 25 Text only Text only 2 40K 50Hz 2M/s 0,1,3,4,5 (3) (5) (7)
4 40 × 32 320 × 256 1280 × 1024 2 20K 50Hz 1M/s 0,1,3,4,5 (3)
5 20 × 32 160 × 256 1280 × 1024 4 20K 50Hz 1M/s 0,1,3,4,5 (3)
6 40 × 25 Text only Text only 2 20K 50Hz 1M/s 0,1,3,4,5 (3) (5) (7)
7 40 × 25 Teletext Teletext 16 80K 50Hz 4M/s 0,1,3,4,5 (3) (5)
8 80 × 32 640 × 256 1280 × 1024 4 40K 50Hz 2M/s 0,1,3,4,5 (3)
9 40 × 32 320 × 256 1280 × 1024 16 40K 50Hz 2M/s 0,1,3,4,5 (3)
10 20 × 32 160 × 256 1280 × 1024 256 80K 50Hz 4M/s 0,1,3,4,5 (3)
11 80 × 25 640 × 250 1280 × 1000 4 40K 50Hz 2M/s 0,1,3,4,5 (3) (8)
12 80 × 32 640 × 256 1280 × 1024 16 80K 50Hz 4M/s 0,1,3,4,5 (3)
13 40 × 32 320 × 256 1280 × 1024 256 80K 50Hz 4M/s 0,1,3,4,5 (3)
14 80 × 25 640 × 250 1280 × 1000 16 80K 50Hz 3.9M/s 0,1,3,4,5 (3) (8)
15 80 × 32 640 × 256 1280 × 1024 256 160K 50Hz 8M/s 0,1,3,4,5 (3)
16 132 × 32 1056 × 256 2112 × 1024 16 132K 50Hz 6.6M/s 0,1 (6)
17 132 × 25 1056 × 250 2112 × 1000 16 132K 50Hz 6.5M/s 0,1 (6) (8)
18 80 × 64 640 × 512 1280 × 1024 2 40K 50Hz 2M/s 1
19 80 × 64 640 × 512 1280 × 1024 4 80K 50Hz 4M/s 1
20 80 × 64 640 × 512 1280 × 1024 16 160K 50Hz 8M/s 1
21 80 × 64 640 × 512 1280 × 1024 256 320K 50Hz 16M/s 1
22 96 × 36 768 × 288 768 × 576 16 108K 50Hz 5.4M/s 0,1 (1) (9)
23 144 × 56 1152 × 896 2304 × 1792 2 126K 64Hz 8.1M/s 2
24 132 × 32 1056 × 256 2112 × 1024 256 264K 50Hz 13.2M/s 0,1 (6)
25 80 × 60 640 × 480 1280 × 960 2 37.5K 60Hz 2.3M/s 1,3,4,5
26 80 × 60 640 × 480 1280 × 960 4 75K 60Hz 4.5M/s 1,3,4,5
27 80 × 60 640 × 480 1280 × 960 16 150K 60Hz 9M/s 1,3,4,5
28 80 × 60 640 × 480 1280 × 960 256 300K 60Hz 18M/s 1,3,4,5
29 100 × 75 800 × 600 1600 × 1200 2 58.6K 56Hz 3.3M/s 1,4 (1) (2)
30 100 × 75 800 × 600 1600 × 1200 4 117.2K 56Hz 6.6M/s 1,4 (1) (2)
31 100 × 75 800 × 600 1600 × 1200 16 234.4K 56Hz 13.2M/s 1,4 (1) (2)
33 96 × 36 768 × 288 1536 × 1152 2 27K 50Hz 1.4M/s 0,1 (1)
34 96 × 36 768 × 288 1536 × 1152 4 54K 50Hz 2.7M/s 0,1 (1)
35 96 × 36 768 × 288 1536 × 1152 16 108K 50Hz 5.4M/s 0,1 (1)
36 96 × 36 768 × 288 1536 × 1152 256 216K 50Hz 10.8M/s 0,1 (1)
37 112 × 44 896 × 352 1792 × 1408 2 38.5K 60Hz 2.3M/s 1 (1)
38 112 × 44 896 × 352 1792 × 1408 4 77K 60Hz 4.6M/s 1 (1)
39 112 × 44 896 × 352 1792 × 1408 16 154K 60Hz 9.2M/s 1 (1)
40 112 × 44 896 × 352 1792 × 1408 256 308K 60Hz 18.5M/s 1 (1)
41 80 × 44 640 × 352 1280 × 1408 2 27.5K 60Hz 1.7M/s 1,3,4,5 (1) (3) (4)
42 80 × 44 640 × 352 1280 × 1408 4 55K 60Hz 3.3M/s 1,3,4,5 (1) (3) (4)
43 80 × 44 640 × 352 1280 × 1408 16 110K 60Hz 6.6M/s 1,3,4,5 (1) (3) (4)
44 80 × 25 640 × 200 1280 × 800 2 15.7K 60Hz 0.9M/s 1,3,4,5 (1) (3)
45 80 × 25 640 × 200 1280 × 800 4 31.3K 60Hz 1.9M/s 1,3,4,5 (1) (3)
46 80 × 25 640 × 200 1280 × 800 16 62.5K 60Hz 3.8M/s 1,3,4,5 (1) (3)

Notes on display modes
  1. These modes are not available in RISC OS 2.00, nor (except for mode 31) are they available in RISC OS 2.01.
  2. These modes are not available on early models of RISC OS computers (ie the Archimedes 300, 400 and 400/1 series, and the A3000), because they are unable to clock VIDC at the necessary rate.
  3. These modes are handled differently with a VGA or Super-VGA-type monitor. If you are using such a monitor:
    • RISC OS 2.00 does not implement these modes.
    • These modes are all displayed on a screen having 352 raster lines. Where a mode has fewer than 352 vertical pixels, it is centred on the screen with blank rasters at the top and bottom. Because of their appearance these modes are known as letterbox modes.
    • The refresh rate is 70Hz.
    • The bandwidths shown in the table for these modes are lower than these monitor types consume, because no allowance has been made for the blank rasters.
    • Early models of RISC OS computers (ie the Archimedes 300, 400 and 400/1 series, and the A3000) scan these modes some 4.7% slow. Again this is because they are unable to clock VIDC at the necessary rate. Most VGA and Super-VGA-type monitors can still successfully lock onto this signal, but some may not. Furthermore, these models do not provide a Sync Polarity signal. This makes the effect of letterbox modes (see above) more severe.
  4. Early models of RISC OS computers (ie the Archimedes 300, 400 and 400/1 series, and the A3000) also scan these modes some 4.7% slow with multi-frequency monitors. Again this is because they are unable to clock VIDC at the necessary rate.
  5. These modes do not display graphics, and are provided for compatibility with BBC/Master series computers.
  6. In these modes circles, arcs, sectors and segments do not look circular. This is because the aspect ratio of the pixels is not in a 1:2, 1:1 or 2:1 ratio.
  7. These are gap modes, where the colour of the gaps is not necessarily the same as the text background.
  8. These modes are not a multiple of eight pixels high. By default, in these modes the bottom of the screen corresponds to the bottom line of ECF patterns, but the top line will not correspond to the top line of ECF patterns.
  9. This mode is not available in RISC OS 3 (version 3.00). It provides a double-sized display suitable for use by visually impaired people. Unfortunately some applications may not provide correct displays when used with this mode.
Other notes

Mode 32 has not been defined.

If an attempt is made to select a mode which is not appropriate to the current monitor type (or OS version), a suitable mode for that monitor is used. For example, an attempt to select mode 23 on a type 0 monitor will result in mode 0 being used.

In 256 colour modes, there are some restrictions on the control of the colours. Only 64 base colours may be selected; 4 levels of tinting turn the base colours into 256 shades. Also, the selection from the colour palette of 4096 shades is only possible in groups of 16.

Banks of screen memory

If 128 is added to the mode number, the so-called shadow bank is used if possible. Any display mode may have several banks of memory available. The number of banks depends on the size of the screen memory (as allocated by *Configure ScreenSize) and the size of the current mode. For example, if 160K is allocated, and 20K is used for the display, eight banks are available.

Usually, bank 1 is used. However, if 128 is added to the mode number, or a *Shadow command has been issued, bank 2 is used after a mode change. Shadow memory can only be used if ScreenSize is at least twice the memory for the required mode.

The other banks may be accessed using OS_Bytes 112 - 113.

Effect of the mode command

The mode command causes the following actions:

  • Cursor editing is terminated if currently in use
  • VDU 4 mode is entered
  • The text and graphics windows are restored to their default values
  • The text cursor is moved to its home position
  • The graphics cursor is moved to (0,0)
  • The graphics origin is moved to (0,0)
  • Paged mode is terminated if currently in use
  • The logical-physical colour map is set to the new mode's default
  • The text and graphics foreground colours are set to white
  • The text and graphics background colours are set to black (colour 0)
  • The colour patterns are set to their defaults for the new mode
  • The ECF origin is set to (0,0)
  • The dot pattern for dotted lines is reset to &AAAAAAAA
  • The dot pattern repeat length is reset to 8
  • The screen is cleared to the current text background colour (ie black).

If there is not enough configured screen RAM for the mode you have selected, and the application workspace area is not in use, then memory is moved out of the application workspace area to the screen area.

Getting information on a mode

The current screen mode may be read using OS_Byte 135.

The size of the screen in a given mode can be determined by reading VDU variables XWindLimit, YWindLimit, XEigFactor, YEigFactor.

Example

VDU 22,7 - Select Teletext mode


VDU 23

Miscellaneous commands

Syntax

VDU 23,command,n1,n2,n3,n4,n5,n6,n7,n8

Parameters

command - the command to perform
n1,n2,n3,n4,n5,n6,n7,n8 - the 8 parameters which follow it

Use

VDU 23 is a multi-purpose command taking nine parameters, of which the first identifies a particular function. Each of the available functions is described below. Eight additional parameters are required in each case, though often most of these are ignored. This enables you to use '|' as shorthand in BASIC VDU statements, as in the example below.

Examples

VDU 23,0,10| - These two lines have the same effect
VDU 23,0,10,0,0,0,0,0,0,0


VDU 23,0

Set the interlace and control cursor appearance

Syntax

VDU 23,0,action,mode,0,0,0,0,0,0

Parameters

action - Sets which action to perform
mode - Defines the mode for a given action

Use
If action = 8, this sets the interlace as follows:

    Mode Effect
    0 sets the screen interlace state to the opposite of the current
    *TV setting
    1 sets the screen interlace state to the current *TV setting
    &80 turns the screen interlace off
    &81 turns the screen interlace on

If action= 10 or 11, this controls the height of the cursor on the screen and its appearance.

    action= 10 mode defines the start line for the cursor and its appearance:

      Bits 0 - 4 define the start line (0 being the top)
      Bits 5 - 6 define its appearance as follows:

      Bit 6 Bit 5 Meaning
      0 0 Steady
      0 1 Off
      1 0 Fast flash
      1 1 Slow flash

    action = 11 mode defines the end line for the cursor.

The bottom line of the cursor is 7 for 'normal' modes, 9 for standard 'gap' modes, and 19 for mode 7.

Example

VDU 23,0,8,&81| - Turn the screen interlace on


VDU 23,1

Control the appearance of the text cursor

Syntax

VDU 23,1,mode,0,0,0,0,0,0,0

Parameters

mode - determines which cursor mode

Use

VDU 23,1 controls the appearance of the text cursor on the screen depending on the value of mode:

    Value Meaning
    0 stops the cursor appearing
    1 makes the cursor re-appear
    2 makes the cursor steady
    3 makes the cursor flash

The effect of this call is cancelled when cursor editing occurs. The effect of the previous call is not changed by cursor editing. See also SWI OS_RemoveCursors and SWI OS_RestoreCursors.

Example

VDU 23,1,3| - makes the cursor flash


VDU 23,2-5

Define ECF pattern and colours

Syntax

VDU 23,pattern_no+1,n1,n2,n3,n4,n5,n6,n7,n8

Parameters

pattern_no+1 - number of pattern to set (1 - 4) plus one
n1,n2,n3,n4,n5,n6,n7,n8 - colour for each row

Use

VDU 23,2 - VDU 23,5 are used to define the four colour patterns:

    VDU 23,2 sets pattern 1
    VDU 23,3 sets pattern 2
    VDU 23,4 sets pattern 3
    VDU 23,5 sets pattern 4

Each of the integers n1 to n8 defines the colours of one row of the pattern, n1 being the top row and n8 being the bottom. For a given parameter, the logical colours of the pixels in each row depend upon the number of colours available in the current screen mode and which pattern mode is used. There are two available pattern modes. The default is the BBC/Master compatible mode. The other is the native RISC OS mode which decodes the values in a simpler fashion. To change between these modes use VDU 23,17,4.

If the bit settings in one of the n parameters is denoted by 76543210, then the logical colours of the pixels in each row (from left to right) are:

    Bits per pixel No. of colours No. of pixels in a line BBC/Master colours RISC OS colours
    1 2 8 7,6,5,4,3,2,1,0 0,1,2,3,4,5,6,7
    2 4 4 73, 62, 51, 40 10, 32, 54, 76
    4 16 2 7531, 6420 3210, 7654
    8 256 1 76543210 76543210

There are many examples of using these and the VDU 23,12-15 commands to alter ECF functions in the Application Notes.

In any 256 colour mode, each parameter refers to the colour of each line. Use the colour byte as described by VDU 19.


VDU 23,6

Set dot-dash line style

Syntax

VDU 23,6,n1,n2,n3,n4,n5,n6,n7,n8

Parameters

n1,n2,n3,n4,n5,n6,n7,n8 - bit pattern for style

Use

VDU 23,6 sets the dot-dash line style used by dotted line PLOT commands (see also VDU 25 - which does the plotting - on VDU 25, and OS_Byte 163 - which sets the dot-dash repeat length - on OS_Byte 163).

Each of the integers n1 to n8 defines eight elements of the line style, n1 being at the start and n8 at the end. The bits in each byte are read from most significant to least significant, each 1-bit indicating a dot and each 0-bit a space. The default is &AAAAAAAA (alternating dots and spaces) with a repeat length of eight (so only n1 is used).

Example
VDU 23,6,&F0,&F0,&F0,&F0,&F0,&F0,&F0,&F0

VDU 23,7

Scroll text window or screen

Syntax

VDU 23,7,extent,direction,movement,0,0,0,0,0

Parameters

extent - text window or screen
direction - direction to scroll
movement - how much movement

Use

VDU 23,7 allows the current text window or whole screen to be scrolled directly in any direction without moving the cursor. The extent, direction and movement determine the area to be scrolled, the direction of scrolling and the amount of scrolling as follows:

    extent Effect
    0 scroll the current text window
    1 scroll the entire screen
    direction Effect
    0 scroll right
    1 scroll left
    2 scroll down
    3 scroll up
    4 scroll in positive x direction (as set by VDU 23,16)
    5 scroll in negative x direction (as set by VDU 23,16)
    6 scroll in positive y direction (as set by VDU 23,16)
    7 scroll in negative y direction (as set by VDU 23,16)
    movement Effect
    0 scroll by one character cell
    1 scroll by one character cell vertically or one byte horizontally

If movement is 1, the horizontal movement depends on the number of colours in the current mode as follows:

    Number of colours Number of pixels moved
    2 8
    4 4
    16 2
    256 1

Example

VDU 23,7,0,3,0| - Scroll window up one character


VDU 23,8

Clear a block of the text window

Syntax

VDU 23,8,base_start,base_end,x1,y1,x2,y2,0,0

Parameters

base_start - base position of start of block
base_end - base position of end of block
x1, y1, x2, y2 - displacements of block

Use

VDU 23,8 causes a block of the current text window to be cleared to the text background colour. The parameters base_start and base_end indicate base positions relating to the start and end of the block to be cleared respectively:

    Value Meaning
    0 top left of window
    1 top of cursor column
    2 off top right of window
    4 left end of cursor line
    5 cursor position
    6 off right of cursor line
    8 bottom left of window
    9 bottom of cursor column
    10 off bottom right of window

References to 'left', 'up' and so on are dependent upon the cursor movement control set by VDU 23,16. 'Off' means 'one character beyond (in the positive x direction)'. The effects of other values, ie. 3, 7 and any number over 10, are undefined.

The parameters x1,y1 and x2,y2 are displacements from the positions specified by the base start and base end; they determine the start and end of the block:

    x1 Displacement from base start in x direction
    y1 Displacement from base start in y direction
    x2 Displacement from base end in x direction
    y2 Displacement from base end in y direction

The result is undefined if the absolute values defining the start and end of the block produce values outside the range -128 to 127. If the end point of the block lies before the start point then no clearing takes place.

The action of this command can be viewed as equivalent to moving the text cursor to the start of the block, then printing spaces until the end of the block is reached (but without printing a space at the last position).

Example

VDU 23,8,5,10,0,0,0,0| - Clear from cursor to end of screen


VDU 23,9

Set flash time for first flashing colour

Syntax

VDU 23,9,duration,0,0,0,0,0,0,0

Parameters

duration - number of VSyncs

Use

VDU 23,9 sets the flash time for the first flashing colour. The length is determined by the value of duration as follows:

    duration = 0 sets a steady flash colour 1
    duration [NOT EQUAL] 0 sets the duration

A Vsync is the time between refreshes of the screen display. It varies between display modes and countries. In the UK for modes 0 - 17 it is approximately 1/50th second.

This command is equivalent to OS_Byte 9 (see OS_Byte 9).

Example

VDU 23,9,1| - Set to one Vsync


VDU 23,10

Set flash time for second flashing colour

Syntax

VDU 23,10,duration,0,0,0,0,0,0,0

Parameters

duration - number of VSyncs

Use

VDU 23,10 sets the flash time for the second flashing colour. The length is determined by the value of duration as follows:

    duration = 0 sets a steady flash colour 2
    duration [NOT EQUAL] 0 sets the duration

This command is equivalent to OS_Byte 10.

Example

VDU 23,10,2| - Set to two VSyncs


VDU 23,11

Set default patterns

Syntax

VDU 23,11,0,0,0,0,0,0,0,0

Parameters

--

Use

VDU 23,11 selects the Master 128 compatible pattern mode and causes the four colour patterns to be reset to their defaults for the current screen mode. With the default logical-physical map, these defaults are:

Mode 0

1 - Red-orange 2 - Orange 3 - Yel-orange 4 - Cream
11001100 11110000 11111111 00000011
00000000 00001111 00110011 00001100
11001100 11110000 11111111 01000100
00000000 00110011 01010101 10001000

Other 2 colour modes

1 - Dark grey 2 - Grey 3 - Light grey 4 - Hatching
10101010 11001100 11111111 00010001
00000000 00110011 01010101 00100010
10101010 11001100 11111111 01000100
00000000 00110011 01010101 10001000

4 colour modes

1 - Red-orange 2 - Orange 3 - Yel-orange 4 - Cream
2121 2121 2222 2323
1111 1212 1212 3232
2121 2121 2222 2323
1111 1212 1212 3232

16 colour modes

1 - Orange 2 - Pink 3 - Yel-green 4 - Cream
21 61 32 37
12 16 23 73
21 61 32 37
12 16 23 73

256 colour modes

1 - Grey 2 - Slate 3 - Green 4 - Pink
3F 00 0 C0 4 C0 3B 00
  40   80   80   40
  80   40   40   80
  C0   00   00   C0

All the patterns repeat after four rows, so only the first four are shown.

Example

VDU 23,11|


VDU 23,12-15

Define simple ECF patterns and colours

Syntax

VDU 23,pattern,n1,n2,n3,n4,n5,n6,n7,n8

Parameters

Define a two by four block of pixels as follows:

The pattern parameter determines which colour pattern is set:

pattern Sets colour pattern
12 1
13 2
14 3
15 4

Use

VDU 23,12-15 are used to define the four colour patterns in a simpler way than that provided by VDU 23,2-5. The limitation is that you can only set a two-by-four pattern of pixels.

The pixels of the top row of the resulting pattern are assigned alternating logical colours n1 and n2, those of the next row have colours n3 and n4 etc.

In any 256 colour mode, the declared use of the parameters does not apply. In this case, each parameter refers to the colour of each line, from 1 to 8. Use the colour byte as described by VDU 19.

Example

To set up the following pattern in mode 1 for colour pattern 1:

RedYel 12
WhtRed 31
BlkRed 01
WhtYel 32

the required sequence is:

VDU 23,12,1,2,3,1,0,1,3,2


VDU 23,16

Control the movement of cursor after printing

Syntax

VDU 23,16,x,y,0,0,0,0,0,0

Parameters
x exclusive OR value

y AND value
Use

VDU 23,16 gives control of the movement of the cursor after a character has been printed. This movement is under the control of a byte of flags. VDU 23,16 replaces the byte by:

    ((current byte) AND y) XOR x

The interpretation of the flags is as follows:

Bit Value Effect
7 0 Normal.
  1 Undefined.
6 0 In VDU 5 mode, cursor movements beyond the current edge of the window cause special actions. For example, they generate newlines at the end of the line.
  1 In VDU 5 mode, cursor movements beyond the edge of the window do not cause special actions. This is the most useful mode of VDU 5; used in the Window Manager.
5 0 Cursor moves in the positive x direction after the character is printed. If this results in the cursor moving beyond the edge of the window, the settings of bits 6, 4 and 0 define the action which is taken.
  1 Cursor does not move after the character is printed.
4 0 When a cursor movement in the y direction results in the cursor moving beyond the window edge, the window is scrolled if in VDU 4 mode. If in VDU 5 mode, the cursor moves to the opposite edge of the window.
  1 When a cursor movement in the y direction results in the cursor moving beyond the window edge, the cursor is always moved to the opposite edge of the window.
3 0 x direction is horizontal, y direction is vertical.
  1 x direction is vertical, y direction is horizontal.
2 0 Positive vertical direction is down.
  1 Positive vertical direction is up.
1 0 Positive horizontal direction is right.
  1 Positive horizontal direction is left.
0 0 Disables the scroll-protect option. When printing a character in VDU 4 mode results in the cursor moving beyond the edge of the window, the cursor is instead moved to the negative x edge of the window and one line in the positive y direction.
  1 Enables the scroll protect option. When printing a character in VDU 4 mode results in the cursor moving beyond the edge of the window, a 'pending newline' is generated. It is actually executed just before the next character is printed, provided that it has not been deleted or executed by another cursor control character. For example VDU 127 would cancel it; VDU 9 would execute it.

Example

VDU 23,16,%00000100,%11111011| - Set vertical direction up


VDU 23,17,0-3

Set the tint for a colour

Syntax

VDU 23,17,action,tint,0,0,0,0,0,0

Parameters

action - determines which colour is to be set
tint - what the tint is to be set to

Use

VDU 23,17,0-3 is used to set the amount of white tint given to a colour in the 256-colour modes. The action determines which colour's tint is set, as follows:

    action Colour
    0 sets the tint for the text foreground colour
    1 sets the tint for the text background colour
    2 sets the tint for the graphics foreground colour
    3 sets the tint for the graphics background colour

The value of the tint is given by the top two bits of the tint parameter:

    tint Tint effect
    &00 Bit 0 and bit 1 clear (darkest)
    &40 Bit 0 set and bit 1 clear
    &80 Bit 1 set and bit 0 clear
    &C0 Bit 0 and bit 1 set (lightest)

For more details, see the chapter entitled 256-colour modes.

Example

VDU 23,17,0,&C0| - Set the text foreground colour to lightest tint


VDU 23,17,4

Choose the patterns used to interpret subsequent VDU 23,2 - 5... calls

Syntax

VDU 23,17,4,patterns,0,0,0,0,0,0

Parameters

patterns - which mode of patterns

Use

This command chooses which set of colour patterns are used to interpret subsequent VDU 23,2 - 5... calls, depending on the value of <patterns>:

    patterns Mode
    0 Use 6502 BBC Micro compatible colour patterns
    1 Use native colour patterns

Example

VDU 23,17,4,1| - Use native colour patterns


VDU 23,17,5

Exchange text foreground and background colours

Syntax

VDU 23,17,5,0,0,0,0,0,0,0

Parameters

--

Use

This command exchanges the current text foreground and background colours. After the first time it's called, subsequent characters printed are in inverse video. After the second time it's called, subsequent characters printed are of normal appearance.

Example
VDU 23,17,5|

VDU 23,17,6

Set ECF origin

Syntax

VDU 23,17,6,x;y;0,0,0

Parameters

x, y - point coordinates

Use

By default, the alignment of ECF patterns is with the bottom left corner of the screen. This command changes it so that the bottom left pixel of the pattern coincides with the pixel at the specified point.

The origin is restored to the default after a mode change.

OS_SetECFOrigin performs the same action.

Example
VDU 23,17,6,200;300;0,0,0

VDU 23,17,7

Set character size/spacing

Syntax

VDU 23,17,7,flags,x;y;0,0

Parameters

flags - what to set the size of
x, y - size in pixels

Use

This command allows changing the size and spacing of VDU 5 characters. They are reset when a mode change occurs. Bit 1 of the flags refers to the size of VDU 5 characters. Bit 2 refers to the spacing between VDU 5 characters. x and y are sizes in pixels.

Sizes of 8x16 and 8x8 are optimised for speed. All other settings are much slower. The spacing settings do not affect the speed. The default size and spacing of VDU 5 characters is 8x8.

Example

VDU 23,17,7,%100,10;8;0,0 - change VDU 5 spacing to 10 pixels


VDU 23,18-24

Reserved for future expansion


VDU 23,25-26

These calls are provided by the Font Manager for compatibility with earlier operating systems. You must not use them. See the chapter entitled The Font Manager for further details.


VDU 23,27

This call is provided by the Sprite Manager. See the chapter entitled Sprites for further details.


VDU 23,28-31

Reserved for use by application programs.


VDU 23,32-255

Redefine the printable characters

Syntax

VDU 23,32-255,n1,n2,n3,n4,n5,n6,n7,n8

Parameters

32 - 255 - character to define
n1,n2,n3,n4,n5,n6,n7,n8 - definition by row

Use

VDU 23,32 to VDU 23,255 redefine the printable ASCII characters. The redefined character depends on the value of the second parameter. For example, VDU 23,65 redefines the character whose ASCII value is 65, ie capital A. The parameters n1 to n8 are integers representing the eight rows of the character to be redefined, n1 being the top row and n8 the bottom row. Each bit of a value represents one pixel of the corresponding row, with a '1' indicating that the corresponding pixel is to be plotted in the foreground colour and a '0' that it is to be plotted in the background colour (or not at all in the case of VDU 5 mode printing). The most significant bit of the byte corresponds to the left-hand pixel of its row, and the others follow linearly.

Although the delete character (ASCII 127) can be redefined, redefining has no effect as it cannot be displayed.

You can read the pattern for a given character using OS_Word 10.

You should not use this call in programs that might be run under the desktop, as your redefinitions may affect other programs. If you must use this call, ensure you only redefine characters that are normally unused.

Note that the desktop redefines some characters for its own use, and you must not redefine these yourself. To determine which characters are normally unused, view the entire system font under the desktop (the !Chars application is ideal for this):

  • In RISC OS 2, the unused characters are those remaining from the underlined string 'These·characters·are·not·defined'
  • In later versions of RISC OS, the unused characters are those represented as small hexadecimal numbers
Example

VDU 23,65,&AA,&55,&AA,&55,&AA,&55,&AA,&55 - redefine 'A'


VDU 24

Define graphics window

Syntax

VDU 24,x1;y1;x2;y2;

Parameters

x1, y1, x2, y2 - coordinates of window

Use

VDU 24 allows the user to define a graphics window. Any graphics objects which are drawn (including VDU 5 mode and fancy-font characters) and which lie outside this window are clipped to the edges of the window. The four parameters define the left, bottom, right and top boundaries of the window respectively, relative to the current graphics origin (the bottom left of the screen, by default). The window which you are defining must lie within the screen boundaries, otherwise the command is ignored.

The coordinates are inclusive - that is, the points you specify lie within the window.

Use OS_ReadVduVariables to discover the size of the current graphics window.

Example
VDU 24,100;150;700;800;

The following example shows how to derive (in this instance, xsize) the size of a window in OS units

DIM blk% 12
VduExt_XEigFactor% = 4
VduExt_XWindLimit% = 11
blk%!0 = VduExt_XEigFactor%
blk%!4 = VduExt_XWindLimit%
blk%!8 = -1
SYS "OS_ReadVduVariables", blk%, blk%
xeigfactor% = blk%!0
xwindlimit% = blk%!4: REM in pixels
xwindsize%  = (xwindlimit% + 1) << xeigfactor%: REM in OS units


VDU 25

General PLOT command

Syntax

VDU 25,type,x;y;

Parameters

type - what kind of plot to perform
x, y - where to plot

Use

VDU 25 is a multi-purpose graphics plotting command. The first parameter defines a particular function. The other parameters are the x coordinate and the y coordinate. They are relative either to the current graphics origin, or to the last point visited, depending on the value of type.

The bottom three bits of type determine the manner in which the plot is to be performed. Thus (type AND 7) has the following effects:

    type AND 7 Effect
    0 move cursor relative (to last graphics point visited)
    1 plot relative using current foreground colour
    2 plot relative using logical inverse colour
    3 plot relative using current background colour
    4 move cursor absolute (ie move to actual coordinates given)
    5 plot absolute using current foreground colour
    6 plot absolute using logical inverse colour
    7 plot absolute using current background colour

The remaining bits of type determine the action to be performed. The value given here is added to the 0 - 7 range above to get all the possible combinations. The value here is the decimal starting value:

    Value Effect
    0 Solid line including both end points
    8 Solid line excluding the final point
    16 Dotted line including both end points, pattern restarted
    24 Dotted line excluding the final point, pattern restarted
    32 Solid line excluding the initial point
    40 Solid line excluding both end points
    48 Dotted line excluding the initial point, pattern continued
    56 Dotted line excluding both end points, pattern continued
    64 Point Plot
    72 Horizontal line fill (left and right) to non-background
    80 Triangle fill
    88 Horizontal line fill (right only) to background
    96 Rectangle fill
    104 Horizontal line fill (left and right) to foreground
    112 Parallelogram fill
    120 Horizontal line fill (right only) to non-foreground
    128 Flood to non-background
    136 Flood to foreground
    144 Circle outline
    152 Circle fill
    160 Circular arc
    168 Segment
    176 Sector
    184 Block copy/move *
    192 Ellipse outline
    200 Ellipse fill
    208 Font printing - see the chapter entitled The Font Manager
    216 Reserved for Acorn Expansion
    224 Reserved for Acorn Expansion
    232 Sprite Plot - see the chapter on sprites
    240 Reserved for User programs
    248 Reserved for User programs
    The eight values in the range 184 - 191, which perform a block copy/move, have the following meanings:

    Value Effect
    184 Move relative
    185 Relative rectangle move
    186 Relative rectangle copy
    187 Relative rectangle copy
    188 Move absolute
    189 Absolute rectangle move
    190 Absolute rectangle copy
    191 Absolute rectangle copy

Some of the objects require several points to be specified in order to define the shape completely. The last plot does the actual drawing. The sequences of moves and draws required for each type are:

    Shape Sequence of moves
    Line Move to one endpoint. Plot line to other endpoint.
    Triangle Move to first vertex. Move to second vertex. Plot triangle to last vertex.
    Rectangle Move to one corner. Plot rectangle to diagonally- opposite corner.
    Parallelogram Move to first corner. Move to second corner. Plot parallelogram to third corner. The fourth corner is derived from the other three, and is opposite the second one.
    Circle Move to centre. Plot circle to point on the circumference.
    Arc, segment, sector Move to centre of circle. Move to start of arc. Plot to a point on the line from the centre to the end of the arc. Arcs, etc, are always drawn counter-clockwise.
    Block copy/move Move to one corner of source rectangle. Move to diagonally-opposite corner of source rectangle. Plot block copy/move to lower left of destination rectangle.
    Ellipse Move to centre. Move to intersection of ellipse circumference and centre's y coordinate. Plot ellipse to highest or lowest point on the ellipse.

Example

VDU 25,69,100;200; - plot point absolute


VDU 26

Restore default windows

Syntax

VDU 26

Parameters

--

Use

VDU 26 causes the text and graphics windows to be reset to their default states, ie both become the full screen. In addition, the command resets the graphics origin to (0,0), moves the graphics cursor to (0,0) and moves the text cursor to its home position. Hardware scrolling of the text window is initiated.


VDU 27

No operation

Syntax

VDU 27

Parameters

--

Use

This VDU has no effect


VDU 28

Define text window

Syntax

VDU 28,x1,y1,x2,y2

Parameters

x1 - left-most x column
y1 - bottom-most y row
x2 - right-most x column
y2 - top-most y row

Use

VDU 28 defines (or redefines) a text window. The parameters are integers specifying the boundary of the window as above.

If the command attempts to define a window which extends outside the screen boundaries, has x1 greater than x2, or has y1 less than y2, it will have no effect. The smallest possible window is one character.

You can read the size of the current text window using OS_ReadVduVariables.

Example
VDU 28,10,15,20,5

VDU 29

Set graphics origin

Syntax

VDU 29,x;y;

Parameters

x, y - where the origin is to be set

Use

VDU 29 defines the point specified as the origin to be used for all subsequent graphics output using VDU 25 commands, and for the graphics window defined by VDU 24. The parameters are the two pairs of bytes specifying the absolute x and y coordinates of the new origin.

  • Note: changing the graphics origin does not alter the position of the graphics window on the screen. The window's coordinates in terms of the origin therefore effectively change after a VDU 29.

You can read the position of the current origin using OS_ReadVduVariables.

Example
VDU 29,100;200;

VDU 30

Home text cursor

Syntax

VDU 30

Parameters

--

Use

VDU 30 moves the text cursor to its 'home' position. This is normally the top left of the window but may be changed (using VDU 23,16). In VDU 5 mode the graphics cursor is moved instead. It may have an offset of up to (character size -1) pixels out of the corner along one or both of the axes to allow for the height or width of the character depending on the direction of character printing.


VDU 31

Position text cursor

Syntax

VDU 31,x,y

Parameters

x, y - text position to move to

Use

VDU 31 moves the text cursor to a specified x and y coordinate on the screen. The parameters x and y are the column and row numbers.

In VDU 4 mode, x and y are given relative to the text 'home' position which is at (0,0). If the position lies outside the text window, nothing happens, unless the scroll protect option is enabled and the x coordinate is just beyond the positive x edge of the window. In this case, the text cursor is moved to position (x-1,y) and a pending newline is generated.

In VDU 5 mode the graphics cursor is moved to its 'home' position plus (x character spacing × x) pixels in the positive x direction, plus (y character spacing × y) pixels in the positive y direction. It is possible to move the cursor outside the graphics window in VDU 5 mode.

You can read the position of the text cursor using OS_Byte 134.

Example

VDU 31,10,5


VDU 127

Delete

Syntax

VDU 127

Parameters

--

Use

Unless the previous use of VDU 23,16 indicates that no cursor movement is to take place after character printing, the cursor is moved backwards as if by VDU 8. Then the character under the cursor is deleted by overprinting it with a space (in VDU 4 mode) or a solid block of graphics background colour (in VDU 5 mode). These space and solid block characters are selected from the 'hard' (rather than the 'soft') font, so redefining these characters will not change the results.

Service Calls


Service_ModeChange
(Service Call &46)

Mode change

On entry

R1 = &46 (reason code)
R2 = mode number
R3 = monitor type

On exit

All registers preserved (do not claim)

Use

This call is made whenever a mode change has taken place. It is made for the benefit of modules which may want to re-read some VDU variables to keep a consistent view of the world. Neither RISC OS 2 nor RISC OS 3 (version 3.00) pass the mode number and monitor type.

You should not claim this service call; there is nothing a module can do to prevent the mode change from taking place.


Service_PreModeChange
(Service Call &4D)

Mode change

On entry

R1 = &4D (reason code)
R2 = selected mode (before possible translation)

On exit
Case 1

R1 preserved
R2 preserved

This is the normal action for a module which does not want to interfere

Case 2

R1 = 0 (service claimed)
R0 = 0

This implies that the module does not want the mode change to take place, and has taken an alternative action.

Case 3

R1 = 0 (service claimed)
R0 pointer to an error block

This implies that the module does not want the mode change to take place, and wishes to return the error pointed to by R0.

Case 4

R1 preserved
R2 = new mode

This implies that the module wants to substitute a mode for the specified mode. This is not a very good way of doing it, as other modules further down the chain will be offered the service with this new mode. The Service_ModeTranslation mechanism described below should be used by modules providing new monitor types.

Use

This service call is now of little use, as better alternatives are available.


Service_ModeExtension
(Service Call &50)

Allow soft modes

On entry

R1 = &50 (reason code)
R2 = mode number that information is requested for
R3 = monitor type (or -1 for don't care)

On exit

All registers preserved (if not claimed)

If claimed:
R1 = 0
R2 preserved
R3 = pointer to VIDC list
R4 = pointer to workspace list

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. In RISC OS it is possible to load modules which provide additional screen modes and additional monitor types; such modules must claim this call if they recognise the passed mode and monitor type, and return the information.

Under RISC OS 3 (version 3.10) and later this service call is no longer issued for mode/monitor combinations that RISC OS itself already supports.

If writing a module providing soft modes, the mode number you use must fit this scheme:

    Modes Use
    0 - 63 Reserved for use by RISC OS
    64 - 95 Reserved for third party applications
    96 - 127 Reserved for user defined modes

Mode numbers in the range 64 - 95 are allocated by Acorn.

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

VIDC list: format 0

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. There are currently two different formats. The first is:

    Offset Value
    0 0 (format of list)
    4 VIDC base mode
    8 VIDC parameter
    12 VIDC parameter
    ... ...
    n -1

The VIDC base mode is the number of an existing operating system screen mode which is used to determine the values of VIDC registers not explicitly mentioned in the list. The VIDC parameters are in the form that would be written to the hardware: ie the top 6 bits specify which register is programmed, and the remainder specify the value to be programmed in that register.

However, bits 6 and 7 of the control register should be set to 0, as these will be modified by RISC OS to take the configured sync and the *TV interlace setting into account. Similarly the vertical parameters for border start, display start, display end and border end are modified by RISC OS to take the *TV vertical offset into account.

VIDC parameters below &80000000 are ignored, since these correspond to palette registers (determined by the workspace base mode) and sound registers (not part of the display system).

VIDC list: format 1

On older machines, the VIDC clock is fixed at 24MHz, and the pixel rate is only determined by VIDC's internal dividers, as specified in bits 0 and 1 of the Control Register (VIDC address &E0). Newer machines have extra hardware to allow the selection of different VIDC clocks, and to determine the polarity of the sync lines. VIDC uses its clock together with a set of internal dividers to provide a range of pixel rates. For example, the A540 hardware provides the following pixel rates:

    24000 kHz, 25175 kHz, 36000 kHz with a multiplier of 2/2
    16000 kHz, 16783 kHz, 24000 kHz with a multiplier of 2/3
    12000 kHz, 12587 kHz, 18000 kHz with a multiplier of 1/2
    8000 kHz, 8392 kHz, 12000 kHz with a multiplier of 1/3

The second format of VIDC list was introduced to support these features. It is similar to format 0 (see above), but adds extended parameters:

    Offset Value
    0 1 (format of list)
    4 VIDC base mode
    8 VIDC parameter
    12 VIDC parameter
    ...
    n -1
    n+4 Extended parameter
    n+8 Extended parameter
    ...
    m -1

Extended parameters are of the form:

    (0 << 24) + (pixel rate in kHz)

    This will override the settings of bits 0 and 1 of a Control Register specifier in the main body of the list. If no pixel rate is specified, then the VIDC clock is set to 24MHz, and the settings of the divider in the Control Register are used as normal.

    If the pixel rate specified is not achievable with the hardware on the machine, the nearest available pixel rate is used. When specifying a pixel rate for a hi-res-mono display, the pixel rate specified should be the actual pixel rate divided by 4, ie 24000 not 96000.

or:

    (1 << 24) + (sync polarity)

    where the sync polarity is defined as follows:

    Bits Meaning
    0 0 => HSYNC PVE (AS ON A STANDARD ARCHIMEDES)_ 1 => HSync -ve
    1 0 => VSYNC PVE (AS ON A STANDARD ARCHIMEDES)_ 1 => VSync -ve
    2 - 23 reserved; must be zero
    If no sync polarity is specified, a default of 0 is used (ie the same as a normal Archimedes).

or, from RISC OS 3 (version 3.10) onwards:

    (2 << 24) + (true VIDC clock rate in kHz)

    This is intended to be used in systems where the clock rate fed to VIDC is under the control of some external device, rather than being selected by the clock select latch. (For example, on the portable machine, the LCD ASIC feeds either 8MHz or 16MHz into VIDC when LCD modes are selected).

The values programmed into the clock select latch and the VIDC divider are still determined either from the control register specifier or a pixel rate specifier assuming the same range of clock speeds as on the A540; but the VIDC clock rate specifier is used to determine the video memory rate, which in turn determines the VIDC FIFO Request Pointer values (bits 4 and 5 of the VIDC control register). The VIDC clock rate specifier is also stored in VDU variable VIDCClockSpeed (&AC), which is used by the SoundDMA module to determine the VIDC Sound Frequency Register value.

Workspace list

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
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 on PaletteV, and Service_ModeChanging on Service_ModeChanging. This feature is not available under RISC OS 2, nor under RISC OS 3 (version 3.00); for these you should choose a workspace base mode which has an appropriate palette already set.

When the service is received, the module should check that R2 contains a mode
that it knows about and that R3 holds a monitor type that is suitable for that mode. If not, the service should be passed on. If R3 holds -1 then the MOS 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.

Note that it is possible for a mode to have two or more different sets of VIDC parameters for different monitor types, but the workspace parameters must be the same, as the mode number is used as an identifier in sprites and in calls such as OS_ReadModeVariable.


Service_ModeTranslation
(Service Call &51)

Translate modes for unknown monitor types

On entry

R1 = &51 (reason code)
R2 = mode number that requires translation
R3 = monitor type

On exit

All registers preserved (if not claimed)

If claimed:
R1 = 0
R2 = substitute mode
R3 preserved

Use

This service is offered during a call to OS_CheckModeValid or a screen mode change, if the selected mode is not available with the current monitor type (this having been ascertained by offering Service_ModeExtension) and the monitor type is not one known to the MOS (ie not in the range 0 - 3 for RISC OS 2.00, or 0 - 4 otherwise).

If the monitor type passed in R3 is known to the module, then the module should discover what the attributes of the mode in R2 are (by calling OS_ReadModeVariable) and then choose a mode which is suitable for this monitor type and is closest in attributes to the selected mode. This mode number should be returned in R2.


Service_MonitorLeadTranslation
(Service Call &76)

Translate monitor lead ID

On entry

R1 = &76 (reason code)
R2 = monitor lead ID (see below)

On exit

If monitor lead ID is recognised, then the module should set:

R1 = 0 (claim service)
R3 = default screen mode number to use on this type of monitor
R4 = monitor type number to use (as used in *Configure MonitorType)
R5 = sync type to use on this type of monitor (0 => SEPARATE SYNCS_ 1 => composite sync)

All other registers must be preserved.

If the monitor lead ID is not recognised, the module should preserve all registers.

Use

This service call is issued if SWI OS_ReadSysInfo is called with R0=1 and any of the configured Mode, MonitorType or Sync are set to Auto.

The monitor connector provides 4 ID pins, ID0-ID3, each of which may be connected to 0v, +5v or to the Hsync pin. The monitor lead ID represents the state of these 4 ID pins by 4 2-bit fields, with ID0 in bits 0 and 1, ID1 in bits 2 and 3, ID2 in bits 4 and 5, and ID3 in bits 6 and 7. The meaning of each field is as follows:

    Value Meaning
    0 ID pin is tied to 0v
    1 ID pin is tied to +5v
    2 ID pin is tied to Hsync
    3 Indeterminate - either the state is fluctuating, or the machine is not capable of reading the ID

If your module recognises the monitor lead ID, you should claim the service call and return a monitor type, sync type, and default screen mode to use. For example, the Portable module (which is only present on portables) recognises the ID 1111 returned when no lead is connected, and sets the monitor type to 5 (LCD), the sync to 0, and the default mode to 27.

If the service is not claimed, then RISC OS checks the monitor lead ID against the following list of recognised IDs, and adopts these defaults:

    ID0 ID1 ID2 ID3 Monitor type Sync type Default mode
    H 1 1 X 0 (TV standard) 1 (composite) 12
    1 1 H X 1 (Multisync) 1 (composite) 27
    1 0 1 X 3 (Mono VGA) 0 (separate) 27
    0 1 1 X 3 (Colour VGA) 0 (separate) 27
    0 1 0 X 4 (Super VGA) 0 (separate) 27

where the values in the ID columns have the following meanings:

    Value Meaning
    0 ID pin must be tied to 0v
    1 ID pin must be tied to +5v
    H ID pin must be tied to Hsync
    X Value of ID pin is immaterial

If RISC OS still does not recognise the monitor lead ID, it assumes it to be a TV standard monitor, and uses those settings (ie composite sync, default mode 12).

This service call is not issued by RISC OS 2. Furthermore, older machines such as the A300 and A400 series, and the A3000, cannot detect the sense of the monitor lead IDs.


Service_ModeChanging
(Service Call &89)

Mode change

On entry

R1 = &89 (reason code)
R2 = mode number
R3 = monitor type

On exit

All registers preserved (do not claim)

Use

This service call is issued during a mode change, after Service_PreReset has been issued and a mode change is inevitable, but before it has actually happened. It is intended for use by modules that wish to claim PaletteV on particular combinations of mode number and monitor type. They should claim or release PaletteV depending on whether or not their module recognises the combination of mode number and monitor type. This allows modules providing extended palettes and the like to intercept RISC OS's palette programming.

For example, it is used in this way by the Portable module when an LCD screen mode is selected.

For more details, see the documentation of PaletteV on PaletteV.

This service call is not issued by RISC OS 2, nor by RISC OS 3 (version 3.00).

SWI Calls


OS_Byte 9
(SWI &06)

Write duration of first flash colour

On entry

R0 = 9 (reason code)
R1 = new duration to write

On exit

R0 = preserved
R1 = duration before being overwritten
R2 = corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sets the duration of the first flash colour.

Flashing colours are displayed as a sequence of two alternating colours. By default, each colour is displayed for 25 video frames at a time, which is approximately 0.5 seconds for 50Hz screen modes in the UK. This command allows you to alter the duration for which the first colour is displayed as follows:

    Value Meaning
    0 Set an infinite duration (first colour constantly displayed)
    n Set the duration to n video frames (approximately n/50 seconds)

This variable may also be set using VDU 23,9. It may be read (but not set) by OS_Byte 195.

Related SWIs

OS_Byte 10, OS_Byte 195

Related vectors

ByteV


OS_Byte 10
(SWI &06)

Write duration of second flash colour

On entry

R0 = 10
R1 = duration to write

On exit

R0 preserved
R1 = duration before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sets the duration for the second flash colour. See OS_Byte 9 for an explanation.

This variable may also be set using VDU 23,10. It may be read (but not set) by OS_Byte 194.

Related SWIs

OS_Byte 9, OS_Byte 194

Related vectors

ByteV


OS_Byte 19
(SWI &06)

Wait for vertical sync

On entry

R0 = 19

On exit

R0 preserved
R1, R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The video display frame is drawn approximately fifty times a second for most screen modes in the UK. This call synchronises a software routine with the signal produced when the video output reaches the bottom of the displayed area of the picture (ie the start of the border).

From this time until the next frame starts to be displayed, you can redraw the screen.

It is possible to have more than this time by drawing from top to bottom, or setting a timer to wait until video output has passed the place on the screen you want to redraw.

If even this is not enough time to produce a flicker-free update of the screen, you should consider using more than one bank of screen memory and switching between them (using OS_Bytes 112-113 for example).

Related SWIs

OS_Byte 112, OS_Byte 113

Related vectors

ByteV


OS_Byte 20
(SWI &06)

Reset font definitions

On entry

R0 = 20

On exit

R0 preserved
R1, R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The shape of the character displayed when printing ASCII codes 32-255 may be redefined using the VDU 23,32-255 commands. Any such changes remain in force until the next hard reset. This command may be used to restore the default character definitions for ASCII codes in the range 32 - 127.

Note that you should anyway not redefine characters in the range 32 - 127, since they all have standard meanings which should be preserved for use in applications such as word processors.

See OS_Byte 25 for details on how to restore the other codes or how to restore a smaller selected group.

Related SWIs

OS_Byte 25

Related vectors

ByteV


OS_Byte 25
(SWI &06)

Reset group of font definitions

On entry

R0 = 25
R1 = group to restore

On exit

R0 preserved
R1, R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

All ASCII characters between 32 and 255 may be redefined using the VDU 23 command. This call restores all or a particular group of characters to their default settings according to R1, as follows:

    Value Range of characters to restore
    0 32-255
    1 32-63
    2 64-95
    3 96-127
    4 128-159
    5 160-191
    6 192-223
    7 224-255

Related SWIs

OS_Byte 20

Related vectors

ByteV


OS_Byte 106
(SWI &06)

Select pointer/activate mouse

On entry

R0 = 106
R1 = pointer shape and linkage flag

On exit

R0 preserved
R1 = shape and linkage flag before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

You can define four 'pointer buffers' using OS_Word 21, each holding a different shape definition for the mouse pointer. This call allows you to select one of these definitions for future use, or to turn off the pointer depending on the bottom seven bits of R1:

    Value Meaning
    0 Turn off current pointer
    1-4 Select given pointer

If a pointer is selected it can be linked to the mouse so the mouse drives it, depending on bit seven of R1 as follows:

    Value Meaning
    &00 Link pointer to mouse
    &80 Pointer unlinked

For example, a value in R1 of &03 selects pointer three and links it to the mouse, and a value of &82 selects pointer two but leaves it unlinked.

Related SWIs

OS_Word 21

Related vectors

ByteV


OS_Byte 112
(SWI &06)

Write VDU driver screen bank

On entry

R0 = 112
R1 = bank number

On exit

R0 preserved
R1 = previous bank number
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call selects the bank of screen memory which is to be used by the VDU drivers according to R1, as follows:

    Value Bank
    0 Default for the current screen mode (1 or 2)
    n Select bank 'n'

The maximum value for 'n' is (TotalScreenSize)/(ModeSize), where TotalScreenSize is the amount actually present in screen memory and ModeSize is the size of the current mode. For example, in mode 0, a 20K mode with 160K set aside for the screen makes eight banks available, so 8 is the maximum value for 'n'.

The default bank for a non-shadow mode is bank 1; for a shadow mode it is bank 2. OS_Byte 250 may be used to read the bank number without writing it.

Related SWIs

OS_Byte 250

Related vectors

ByteV


OS_Byte 113
(SWI &06)

Write display hardware screen bank

On entry

R0 = 113
R1 = bank number

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call selects the bank of screen memory which is to be used by the display hardware according to R1:

    Value Bank
    0 Default for the current screen mode
    n Select bank n

The bank may be read (but not set) using OS_Byte 251.

Related SWIs

OS_Byte 251

Related vectors

ByteV


OS_Byte 114
(SWI &06)

Write shadow/non-shadow state

On entry

R0 = 114
R1 = shadow state

On exit

R0 preserved
R1 = value before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call determines whether future MODE commands will be forced into the shadow state, depending on R1:

    Value Meaning
    0 Modes will be shadow
    1 Modes will be non-shadow

Shadow state requires twice the amount of RAM than the equivalent non-shadow mode since two copies of the screen are stored in memory. OS_Bytes 112 and 113 control the use of the banks.

To select a shadow state temporarily when in non-shadow mode, you can use the MODE 128+n convention. Future MODE commands will not be influenced by this.

Related SWIs

OS_Byte 112, OS_Byte 113

Related vectors

ByteV


OS_Byte 117
(SWI &06)

Read VDU status

On entry

R0 = 117

On exit

R0 preserved
R1 = status byte

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the content of the VDU status byte. This byte gives information on the way in which characters are output according to their bit settings:

    Bit Status when set
    0 Printer output enabled by VDU 2
    1 Unused
    2 Paged scrolling selected by VDU 14
    3 Text window in force (ie software scrolling)
    4 In a shadow mode
    5 In VDU 5 mode
    6 Cursor editing in progress
    7 Screen disabled with VDU 21

Related SWIs

None

Related vectors

ByteV


OS_Byte 134
(SWI &06)

Read text cursor position

On entry

R0 = 134

On exit

R0 preserved
R1 = position in x direction
R2 = position in y direction

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the current text cursor position unless cursor editing is in progress, in which case the position returned is that of the input cursor. OS_Byte 165 reads the position of the output cursor irrespective of cursor editing mode.

Text is printed at x positions 0 to n-1, where 'n' is the number of characters per line in the current text window. Therefore, the value obtained is normally in this range. However, if there is a pending newline (see VDU 23,16), a position of 'n' will be returned.

Related SWIs

OS_Byte 165

Related vectors

ByteV


OS_Byte 135
(SWI &06)

Read character at text cursor position and screen mode

On entry

R0 = 135

On exit

R0 preserved
R1 = ASCII value of character (0 if unreadable)
R2 = screen mode

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the screen mode and the ASCII code of the character at the text cursor position. If cursor editing is in progress, it returns the character code returned by the character at the input cursor position (ie the character that would be copied as input the next time Copy is pressed).

Note that the screen mode does not have bit 7 set, even if it is a shadow mode.

Related SWIs

None

Related vectors

ByteV


OS_Byte 144
(SWI &06)

Set vertical screen shift and interlace

On entry

R0 = 144
R1 = vertical screen shift (as a signed 8 bit number)
R2 = interlace flag

On exit

R0 preserved
R1 = previous vertical screen shift
R2 = previous interlace flag

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call specifies the vertical screen alignment and interlace options after the next mode change. R1 sets the vertical offset. R2 turns interlace on and off as follows:

    Value Meaning
    0 Interlace on
    1 Interlace off

This is equivalent to *TV, which is described in this chapter.

Related SWIs

None

Related vectors

ByteV


OS_Byte 160
(SWI &06)

Read VDU variable value

On entry

R0 = 160
R1 = VDU variable number (0-15)

On exit

R0 preserved
R1 = value of variable
R2 = value of next variable (R1 on entry + 1)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The VDU driver uses a number of locations in RAM to store transient information. This call allows some of these locations to be examined. Note that the variables are not necessarily stored in the order implied by the value of R1 on entry. However, the relationship between R1 and the variable read is guaranteed to remain the same for all versions of RISC OS.

    Value Location
    0 LSB of graphics window left column (ic)
    1 MSB of graphics window left column (ic)
    2 LSB of graphics window bottom row (ic)
    3 MSB of graphics window bottom row (ic)
    4 LSB of graphics window right column (ic)
    5 MSB of graphics window right column (ic)
    6 LSB of graphics window top row (ic)
    7 MSB of graphics window top row (ic)
    8 Text window left column
    9 Text window bottom row
    10 Text window right column
    11 Text window top row
    12 LSB of graphics origin x coordinate (ec)
    13 MSB of graphics origin x coordinate (ec)
    14 LSB of graphics origin y coordinate (ec)
    15 MSB of graphics origin y coordinate (ec)

  • (ic) means internal coordinates: the origin is always the bottom left of the screen. One unit is one pixel wide and one pixel high.
  • (ec) means external coordinates: a pixel is (1 « XEigFactor) units wide and (1 « YEigFactor) units high, where XEigFactor and YEigFactor are VDU variables.

This OS_Byte is provided mainly for compatibility with the BBC/Master 128. You can read many more of the VDU variables using OS_ReadVduVariables and OS_ReadModeVariable.

Related SWIs

OS_ReadVduVariables, OS_ReadModeVariable

Related vectors

ByteV


OS_Byte 163
(SWI &06)

Read/write general graphics information

On entry

R0 = 163
R1 = 242
R2 = dot-dash repeat length or action code

On exit

R0 preserved
R1 = status, or preserved
R2 = status, or preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call is a general purpose one reserved for Acorn applications. The only value of R1 which is guaranteed to perform a useful function is 242. The type of action depends on the value of R2:

    Value Meaning
    0 Set default dot-dash pattern and length
    1-64 Set dot-dash line repeat length to the value given
    65 Return status information
    66 Return information on the current sprite

The status information is returned in R1 and R2 as follows:

    R1 bits Meaning
    Bit 7 = 1 Sprites are always active
    Bit 6 = 1 Flood fill is always active
    Bits 0-5 Current dot dash line repeat length (0 means 64)

    R2 bits Meaning
    Bits 0-31 Current size of the system sprite area in bytes.

The information on the current sprite is returned in R1 and R2 as follows:

    R1 = width in pixels (ie internal coordinates)
    R2 = height in pixels (ie internal coordinates)

Related SWIs

None

Related vectors

ByteV


OS_Byte 165
(SWI &06)

Read output cursor position

On entry

R0 = 165

On exit

R0 preserved
R1 = position in x direction
R2 = position in y direction

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call returns the position of the output cursor, even while cursor editing is in progress.

Related SWIs

OS_Byte 134

Related vectors

ByteV


OS_Byte 193
(SWI &06)

Read/write flash counter

On entry

R0 = 193
R1 = 0 to read or new duration to write
R2 = 255 to read or 0 to write

On exit

R preserved
R1 = duration before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The duration stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((duration AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call accesses the location used as a count-down timer for the flashing colours. The location is loaded with the count for the first colour and decremented at a VSync rate, providing that the current flash period is not infinite. When it reaches zero, the colours are swapped and the counter is loaded with the duration of the second colour.

Related SWIs

OS_Byte 9, OS_Byte 10, OS_Byte 194, OS_Byte 195

Related vectors

ByteV


OS_Byte 194
(SWI &06)

Read duration of second colour

On entry

R0 = 194
R1 = 0
R2 = 255

On exit

R0 preserved
R1 = duration
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call reads the duration of the second colour, as set by OS_Byte 10.

The value read is only a record of the current duration. You must not attempt to use this call to write the value; doing so would merely change the stored value, without making any actual change. To change the duration you must instead call OS_Byte 10. This call is only included for backwards compatibility.

Related SWIs

OS_Byte 10

Related vectors

ByteV


OS_Byte 195
(SWI &06)

Read duration of first colour

On entry

R0 = 195
R1 = 0
R2 = 255

On exit

R0 preserved
R1 = duration
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This command will read the location that has been set by OS_Byte 9.

The value read is only a record of the current duration. You must not attempt to use this call to write the value; doing so would merely change the stored value, without making any actual change. To change the duration you must instead call OS_Byte 9. This call is only included for backwards compatibility.

Related SWIs

OS_Byte 9

Related vectors

ByteV


OS_Byte 211
(SWI &06)

Read/write bell channel

On entry

R0 = 211
R1 = 0 to read or new channel to write
R2 = 255 to read or 0 to write

On exit

R0 preserved
R1 = channel before being overwritten
R2 = bell sound information (see OS_Byte 212)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The channel stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((channel AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

The bell (VDU 7) sound is output on channel 1 by default. This call provides a means of determining the current channel, or changing it if required.

Related SWIs

OS_Byte 212, OS_Byte 213, OS_Byte 214

Related vectors

ByteV


OS_Byte 212
(SWI &06)

Read/write bell volume

On entry

R0 = 212
R1 = 0 to read or new volume to write
R2 = 255 to read or 0 to write

On exit

R0 preserved
R1 = volume before being overwritten
R2 = bell frequency (see OS_Byte 213)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The volume stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((volume AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This allows you to read or set the volume of the sound used to make the Ctrl-G bell sound. Values for the amplitude are in the range &80 (loudest) to &F8 (softest) in steps of &08. The default setting depends on the *Configure Loud/Quiet setting (&90/&D0 respectively).

Related SWIs

OS_Byte 211, OS_Byte 213, OS_Byte 214

Related vectors

ByteV


OS_Byte 213
(SWI &06)

Read/write bell frequency

On entry

R0 = 213
R1 = 0 to read or new frequency to write (in range 0 - 255)
R2 = 255 to read or 0 to write

On exit

R0 preserved
R1 = frequency before being overwritten
R2 = bell duration (see OS_Byte 214)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The frequency stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((frequency AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call provides a means of reading or changing the frequency associated with the bell sound. The default value is 100, and it has the same interpretation as the *Sound command.

The frequency must be an old-style BBC frequency: ie in the range 0 - 255.

Related SWIs

OS_Byte 211, OS_Byte 212, OS_Byte 214

Related vectors

ByteV


OS_Byte 214
(SWI &06)

Read/write bell duration

On entry

R0 = 214
R1 = 0 to read or new duration to write
R2 = 255 to read or 0 to write

On exit

R0 preserved
R1 = duration before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The duration stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((duration AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call provides a means of reading or changing the duration of the bell sound. The default value is 6, and the unit is 20ths of a second.

Related SWIs

OS_Byte 211, OS_Byte 212, OS_Byte 213

Related vectors

ByteV


OS_Byte 217
(SWI &06)

Read/write paged mode line count

On entry

R0 = 217
R1 = 0 to read or new count to write
R2 = 255 to read or 0 to write

On exit

R0 preserved
R1 = count before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The count stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((count AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

In the paged output mode, the display is prevented from scrolling (awaiting the depression of Shift) when approximately 75% of the height of the current text window has been scrolled. The number of lines printed since the last page halt is maintained in the location accessed by this call and it may be either read or changed (normally to 0 before requesting user input).

If you are using OS_Word 0 or OS_ReadLine to perform the input, this call is made automatically. OS_Word 0 is provided for compatibility only and should not be used.

Related SWIs

None

Related vectors

ByteV


OS_Byte 218
(SWI &06)

Read/write bytes in VDU queue

On entry

R0 = 218
R1 = 0 to read or new count to write
R2 = 255 to read or 0 to write

On exit

R0 preserved
R1 = count before being overwritten
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The count stored is changed by being masked with R2 and then exclusive ORd with R1: ie ((count AND R2) XOR R1). This means that R2 controls which bits are changed and R1 supplies the new bits.

This call affects the count of the number of characters which remain to be passed to the VDU driver in order to complete the current VDU sequence. The value is (minus the number of bytes left), and is held in 2's complement notation (eg. &FF means one byte to go). The call may be used to read the value or to change it (normally to zero, which has the effect of abandoning an incomplete VDU command).

You can use this call when an escape condition is acknowledged. This prevents the first few characters of an error message from being 'swallowed' by an incomplete VDU sequence.

Related SWIs

None

Related vectors

ByteV


OS_Byte 250
(SWI &06)

Read VDU driver screen bank number

On entry

R0 = 250
R1 = 0
R2 = 255

On exit

R0 preserved
R1 = screen bank used by VDU drivers
R2 = display screen bank (see OS_Byte 251)

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call reads the current VDU driver screen bank number, as set by OS_Byte 112.

The value read is only a record of the current VDU driver screen bank. You must not attempt to use this call to write the value; doing so would merely change the stored value, without making any actual change. To change the duration you must instead call OS_Byte 112. This call is only included for backwards compatibility.

Related SWIs

OS_Byte 112

Related vectors

ByteV


OS_Byte 251
(SWI &06)

Read display screen bank number

On entry

R0 = 251
R1 = 0
R2 = 255

On exit

R0 preserved
R1 = screen bank used by the display
R2 corrupted

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call reads the current display screen bank number, as set by OS_Byte 113.

The value read is only a record of the current display screen bank. You must not attempt to use this call to write the value; doing so would merely change the stored value, without making any actual change. To change the duration you must instead call OS_Byte 113. This call is only included for backwards compatibility.

Related SWIs

OS_Byte 113

Related vectors

ByteV


OS_Word 9
(SWI &07)

Read pixel logical colour

On entry

R0 = 9 (reason code)
R1 = pointer to parameter block

    R1+0 = LSB of x coordinate
    R1+1 = MSB of x coordinate
    R1+2 = LSB of y coordinate
    R1+3 = MSB of y coordinate

On exit

R0 preserved
R1 preserved:

    R1+4 = the logical colour of the pixel specified.

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call determines the logical colour of the pixel at given coordinates on the graphics screen. In 256 colour modes this call ignores the tint, and returns a value in the range 0 - 63. Consequently you should always use OS_ReadPoint in preference, since it returns both the logical colour and tint.

If the colour is returned as &FF then either:

  • the pixel is off the screen
  • the screen is in a non-graphics mode.

This call is provided for backwards compatibility only.

Related SWIs

OS_ReadPoint

Related vectors

WordV


OS_Word 10
(SWI &07)

Read a character definition

On entry

R0 = 10
R1 = pointer to parameter block

    R1+0 = ASCII code of character required

On exit

R0 preserved
R1 preserved:

    R1+1 = top row of definition
    ...
    R1+8 = bottom row of definition

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The characters displayed in all modes other than Teletext mode are defined as an eight-by-eight matrix of dots. This call enables you to read the definition for a specified ASCII code. However, the definitions returned for ASCII codes 0 to 31 and 127 (ie the non-printing characters) are not meaningful apart from the following characters:

    Value Information returned
    2 ECF pattern 1 (in native mode)
    3 ECF pattern 2 (in native mode)
    4 ECF pattern 3 (in native mode)
    5 ECF pattern 4 (in native mode)
    6 Dot-dash pattern

Bits set in each row of the character definition are displayed in the current text foreground colour; bits clear in each row are displayed in the current text background colour. In VDU 5 mode, bits which are set are plotted in the graphics foreground colour and action; bits which are clear are not plotted at all.

Related SWIs

None

Related vectors

WordV


OS_Word 11
(SWI &07)

Read the palette

On entry

R0 = 11
R1 = pointer to parameter block

    R1+0 = logical colour to read

On exit

R0 preserved
R1 preserved:

    R1+1 = physical colour associated with the specified logical colour
    R1+2 = red component
    R1+3 = green component
    R1+4 = blue component

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call allows you to determine the physical colour associated with a particular logical colour. The call can only return one of the colours associated with a flashing colour. To read the full information about a logical colour's palette entry, or to read the border and pointer palettes, you should use OS_ReadPalette. The OS_Word is provided for compatibility only.

Related SWIs

OS_ReadPalette

Related vectors

WordV


OS_Word 12
(SWI &07)

Write the palette

On entry

R0 = 12
R1 = pointer to parameter block

    R1+0 = logical colour to change
    R1+1 = new physical colour
    R1+2 = red component
    R1+3 = green component
    R1+4 = blue component

On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call allows you to change the physical colour associated with a particular logical colour. It duplicates the function of VDU 19 command. However, the OS_Word call is faster and may be used in interrupt routines. The five bytes of the parameter block are equivalent to the five parameters l,p,r,g,b described in the section on VDU 19 (see VDU 19).

Related SWIs

None

Related vectors

WordV


OS_Word 13
(SWI &07)

Read current and previous graphics cursor positions

On entry

R0 = 13
R1 = pointer to parameter block

On exit

R0 preserved
R1 preserved:

    R1+0 = LSB of previous x coordinate
    R1+1 = MSB of previous x coordinate
    R1+2 = LSB of previous y coordinate
    R1+3 = MSB of previous y coordinate
    R1+4 = LSB of current x coordinate
    R1+5 = MSB of current x coordinate
    R1+6 = LSB of current y coordinate
    R1+7 = MSB of current y coordinate

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

All the coordinates are in external form. You can read points visited before the previous one (and many other VDU variables) using OS_ReadVduVariables. The OS_Word is provided for compatibility only.

Related SWIs

OS_ReadVduVariables

Related vectors

WordV


OS_Word 21,0
(SWI &07)

Define pointer size, shape and active point

On entry

R0 = 21
R1 = pointer to parameter block

    R1+0 = 0
    R1+1 = Shape number (1-4)
    R1+2 = Width (w) in bytes (0-8)
    R1+3 = Height (h) in pixels (0-32)
    R1+4 = ActiveX in pixels from left (0-(w×4-1))
    R1+5 = ActiveY in pixels from top (0-(h-1))
    R1+6 = Least significant byte of pointer (P) to data
    R1+7 ...
    R1+8 ...
    R1+9 = Most significant byte of pointer to data

On exit

R0, R1 preserved

Interrupts

Interrupts are enabled (in RISC OS 2, the interrupt status is not altered)
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

You can define four shapes. These are numbered one to four and may be selected using OS_Byte 106.

As the pointer is always displayed in 2 bits per pixel (four pixels per byte), and the maximum width in bytes is 8, the maximum width is 32 pixels.

The ActiveX and ActiveY entries give the distance of the cursor 'hot spot' from the top left corner of the pointer. If these are zero, then positioning the pointer at coordinates (x, y) will move the top left corner to that position. Suppose the shape was a cross-hair 9 pixels in each direction; then making ActiveX and ActiveY (5,5) would position the hot-spot at the centre of the cross.

The data for the shape is pointed to by R1+6-R1+9. This data table contains the information for each row, from top to bottom, and the data within each row is given from left to right. Each byte contains the colours for four pixels. Bits 0,1 hold the colour number for the left-most pixel, bits 6,7 the colour for the right-most pixel. (So the pixels are displayed in reverse order to the order in which the byte would be written down.)

Colour zero is always transparent (ie the screen information shows through pixels in this colour). The other three colours may be set independently of any other colours on the screen using VDU 19 or the equivalent OS_Word.

However, note that colour two should be used with caution in defining pointer shapes, as it does not work correctly on high-resolution mono screens.

Related SWIs

OS_Byte 106

Related vectors

WordV


OS_Word 21,1
(SWI &07)

Define mouse coordinate bounding box

On entry

R0 = 21
R1 = pointer to parameter block

    R1 + 0 = 1 (sub-reason code)
    R1 + 1 = LSB of left coordinate All treated as signed 16-bit values, relative to screen origin at the time the command is issued
    R1 + 2 = MSB of left coordinate
    R1 + 3 = LSB of bottom coordinate
    R1 + 4 = MSB of bottom coordinate
    R1 + 5 = LSB of right coordinate
    R1 + 6 = MSB of right coordinate
    R1 + 7 = LSB of top coordinate
    R1 + 8 = MSB of top coordinate

On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The coordinates should be given as signed 16-bit values relative to the graphics origin at the time the command is issued.

If (left > right) or (bottom > top) then the command is ignored.

An infinite box can be obtained by setting:

    left = &8000 (-32768)
    bottom = &8000 (-32768)
    right = &7FFF (32767)
    top = &7FFF (32767)

If the current mouse position is outside the box, it is homed to the nearest point inside the box. The buffer is not flushed, but any buffered coordinates will be moved inside the bounding box when they are read.

When the mode changes, the box is set to the size of the screen.

Related SWIs

None

Related vectors

WordV


OS_Word 21,2
(SWI &07)

Define mouse multipliers

On entry

R0 = 21
R1 = pointer to parameter block

R1+0 = 2
R1+1 = x multiplier (treated as a signed 8-bit value)
R1+2 = y multiplier (treated as a signed 8-bit value)
On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The multipliers control the ratio between the movement of the mouse and the change in the coordinates of the mouse. The higher each value, the greater the amount the pointer moves (if linked to the mouse) for a given movement of the mouse.

The multipliers should both be given as signed eight-bit values. By specifying negative values (eg. 255 for -1), you can make the pointer move in the opposite direction from usual.

Both multipliers default to the configured MouseStep value. The factory defaults for this have varied between versions of RISC OS:

    RISC OS version MouseStep Mouse movement per screen width
    2 1 15cm
    3 (version 3.00) 2 7.5cm
    3 (version 3.10) 3 5cm

Related SWIs

None

Related vectors

WordV


OS_Word 21,3
(SWI &07)

Set mouse position

On entry

R0 = (reason code)
R1 = pointer to parameter block

    R1+0 = 3
    R1+1 = LSB of x position
    R1+2 = MSB of x position
    R1+3 = LSB of y position
    R1+4 = MSB of y position
On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The new values for the x and y positions of the mouse are given as two signed 16-bit values. If the new position lies outside the bounding box of the mouse, this command will be ignored.

Note that this call sets the position of the mouse rather than the pointer. If the mouse and pointer are not linked, the position of the pointer on the screen is left unchanged.

Related SWIs

None

Related vectors

WordV


OS_Word 21,4
(SWI &07)

Read unbuffered mouse position

On entry

R0 = 21
R1 = pointer to parameter block

    R1+0 = 4
On exit

R0 preserved
R1 preserved:

    R1+1 = LSB of x position
    R1+2 = MSB of x position
    R1+3 = LSB of y position
    R1+4 = MSB of y position
Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call will read the position of the mouse at the time of the call. That is, it will not read the position from the mouse buffer.

Care should be taken when reading this position, as the buffer positions may be significantly out of step.

With RISC OS 2.00 this call generates an undefined instruction trap due to a stack mismatch. This was fixed in RISC OS 2.01.

Related SWIs

None

Related vectors

WordV


OS_Word 21,5
(SWI &07)

Set pointer position

On entry

R0 = 21 (reason code)
R1 = pointer to parameter block

R1+0 = 5
R1+1 = LSB of x position
R1+2 = MSB of x position
R1+3 = LSB of y position
R1+4 = MSB of y position
On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

The new values for the x and y positions of the pointer are given as two signed 16-bit values.

Note that this call sets the position of the pointer rather than the mouse. If the mouse and pointer are linked, then the pointer position will be updated with the mouse position on the next VSync interrupt.

Related SWIs

None

Related vectors

WordV


OS_Word 21,6
(SWI &07)

Read pointer position

On entry

R0 = 21
R1 = pointer to parameter block

R1+0 = 6
On exit

R0 preserved
R1 preserved:

R1+1 = LSB of x position
R1+2 = MSB of x position
R1+3 = LSB of y position
R1+4 = MSB of y position
Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call will read the position of the pointer. If the mouse and pointer are not linked, then this call reads the position that the pointer was last set to.

If they are linked, then the pointer is updated from the unbuffered mouse position every VSync.

Related SWIs

None

Related vectors

WordV


OS_Word 22
(SWI &07)

Write screen base address

On entry

R0 = 22
R1 = pointer to parameter block

    R1+0 = Type
    R1+1 = Least significant byte of offset
    R1+2...
    R1+3...
    R1+4 = Most significant byte of offset
On exit

R0, R1 preserved

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This routine sets up a new screen base address. It is given as the offset from the address of the base of the screen buffer to the start of the screen display. This address can be used as the area of the buffer which is to be updated, ie written to by the VDU drivers, or the area which is to be displayed by the hardware, or both, depending on the bits of the first byte in the parameter block:

    Bit 0 Used by VDU drivers
    Bit 1 Displayed by hardware

This allows multiple screens to be used. For example, in mode 12 two copies of the screen can be kept. One of these can be updated whilst the other is being displayed using the following parameter blocks:

    R1 + 0 Contains 2 Displayed
    R1 + 1-R1+4 Contains &00
    R1 + 0 Contains 1 Updated
    R1 + 1-R1+4 Contains &14000

Then the two screens can be swapped over (at VSync) by changing over the addresses so that smooth animation is obtained.

The configured ScreenSize determines the amount of RAM initially set aside for the screen. This can subsequently change, for example if you drag the screen memory bar in the Task Manager, or call OS_ChangeDynamicArea. You can read the current amount set aside for the screen by reading the VDU variable TotalScreenSize; and you can read the amount needed for a single screen by reading the mode variable ScreenSize.

A slightly simpler way of achieving bank switching is to use OS_Bytes 112-113. With these, you only have to specify the bank number, not the actual offset.

Related SWIs

OS_Byte 112, OS_Byte 113

Related vectors

WordV


OS_Mouse
(SWI &1C)

Read a mouse state from the buffer

On entry

--

On exit

R0 = mouse x coordinate
R1 = mouse y coordinate
R2 = mouse buttons
R3 = time of button change

Interrupts

Interrupts are disabled
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI cannot be re-entered as interrupts are disabled

Use

OS_Mouse reads from the mouse buffer the mouse x and y positions as values between -32768 and 32767. Unless the graphics origin has been changed, the coordinates will lie within the mouse bounding box, which initially defaults to the screen area. The call also returns buttons currently pressed as a value in the range 0-7:

    Bit Meaning when set
    0 Right button down
    1 Middle button down
    2 Left button down

If there is no entry in the mouse buffer, the current status is returned. R3 gives the time the entry was buffered, or the current time if it is not a buffered reading. It uses the monotonic timer (see OS_ReadMonotonicTime).

Related SWIs

OS_ReadMonotonicTime

Related vectors

MouseV


OS_ReadPalette
(SWI &2F)

Read the palette setting of a colour

On entry

R0 = logical colour
R1 = type of colour

On exit

R2 = setting of first flashing colour
R3 = setting of second flashing colour

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

OS_ReadPalette reads the setting of a particular colour that is sent to the hardware. R1 selects whether the normal colour, border colour or pointer colour is read as follows:

    Value Meaning
    16 Read normal colour
    24 Read border colour
    25 Read pointer colour

The settings for the first flash colour and second flash colour are returned in R2 and R3 respectively. If these are identical then the colour is a steady, non-flashing one. The value contained in each of these is interpreted as follows:

    Bits Meaning
    0-6 Value showing how colour was programmed
    7 Supremacy bit
    8-15 Amount of red
    16-23 Amount of green
    24-31 Amount of blue

The bottom byte (bits 0-7) returns the value of the second parameter to the VDU 19 command which defines the palette (bit 7 is the supremacy bit). For example:

    Value Meaning
    0-15 Actual colour (BBC compatible)
    16 Defined by giving amounts of red, green and blue
    17-18 Flashing colour defined by giving amounts of red, green and blue

RISC OS 3 (version 3.10) and later versions no longer return values in the range 0 - 15. Instead they always return 16 for BBC colours 0 - 7, and 17 and 18 for BBC flashing colours 8 - 15.

Related SWIs

None

Related vectors

None


OS_ReadVduVariables
(SWI &31)

Read a series of VDU variables

On entry

R0 = pointer to input block
R1 = pointer to output block

On exit

R0, R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

OS_ReadVduVariables reads in a series of VDU variables and places them in sequence into a block of memory. The input block consists of a sequence of words. Each word is the number of the variable to be read. A value of -1 terminates the list. The value of each variable is put as a word into the output block, any invalid variables being entered as zero. The output block has no terminator. Both blocks must be word-aligned.

The possible variable numbers are the same as for OS_ReadModeVariable (see OS_ReadModeVariable) with the following additions:

Name No. Meaning
GWLCol 128 Left-hand column of the graphics window (ic)
GWBRow 129 Bottom row of the graphics window (ic)
GWRCol 130 Right-hand column of the graphics window (ic)
GWTRow 131 Top row of the graphics window (ic)
TWLCol 132 Left-hand column of the text window
TWBRow 133 Bottom row of the text window
TWRCol 134 Right-hand column of the text window
TWTRow 135 Top row of the text window
OrgX 136 x coordinate of the graphics origin (ec)
OrgY 137 Y coordinate of the graphics origin (ec)
GCsX 138 x coordinate of the graphics cursor (ec)
GCsY 139 Y coordinate of the graphics cursor (ec)
OlderCsX 140 x coordinate of oldest graphics cursor (ic)
OlderCsY 141 Y coordinate of oldest graphics cursor (ic)
OldCsX 142 x coordinate of previous graphics cursor (ic)
OldCsY 143 Y coordinate of previous graphics cursor (ic)
GCsIX 144 x coordinate of graphics cursor (ic)
GCsIY 145 Y coordinate of graphics cursor (ic)
NewPtX 146 x coordinate of new point (ic)
NewPtY 147 Y coordinate of new point (ic)
ScreenStart 148 Address of the start of screen used by VDU drivers
DisplayStart 149 Address of the start of screen used by display hardware
TotalScreenSize 150 Amount of memory currently allocated to the screen
GPLFMD 151 GCOL action for foreground colour
GPLBMD 152 GCOL action for background colour
GFCOL 153 Graphics foreground colour
GBCOL 154 Graphics background colour
TForeCol 155 Text foreground colour
TBackCol 156 Text background colour
GFTint 157 Tint for graphics foreground colour
GBTint 158 Tint for graphics background colour
TFTint 159 Tint for text foreground colour
TBTint 160 Tint for text background colour
MaxMode 161 Highest mode number available
GCharSizeX 162 x size of VDU 5 chars (in pixels)
GCharSizeY 163 Y size of VDU 5 chars (in pixels)
GCharSpaceX 164 x spacing of VDU 5 chars (in pixels)
GCharSpaceY 165 Y spacing of VDU 5 chars (in pixels)
HLineAddr 166 Address of fast line-draw routine
TCharSizeX 167 x size of VDU 4 chars (in pixels)
TCharSizeY 168 Y size of VDU 4 chars (in pixels)
TCharSpaceX 169 x spacing of VDU 4 chars (in pixels)
TCharSpaceY 170 Y spacing of VDU 4 chars (in pixels)
GcolOraEorAddr 171 Address of colour blocks for current GCOLs
VIDCClockSpeed 172 VIDC clock speed in kHz (eg 24000 => 24 MHz) - not available in RISC OS 2.00
WindowWidth 256 Characters that will fit on a row of the text window without a newline being generated
WindowHeight 257 Rows that will fit in the text window without scrolling it

  • ic means internal coordinates, where (0,0) is always the bottom left of the screen. One unit is one pixel.
  • ec means external coordinates, where (0,0) means the graphics origin, and the size of one unit depends on the resolution. The number of external units on a screen is dependent upon the video mode used; for example Mode 16 has 1280 by 1024 external units. The graphics origin is stored in external coordinate units, but is relative to the bottom left of the screen.
  • new point is the internal form of the coordinates given in an unrecognised PLOT command. When the UKPlot vector is called, the internal format coordinates (variables 140-145) have not yet been shuffled down, so the graphics cursor (144-5) contains the coordinates of the last point visited. The external coordinates version of the current point (138-9) is updated from the coordinate given in the unrecognised plot.
  • HLineAddr points to a fast horizontal line draw routine. It is called as follows:

    R0 = left x coordinate of end of line
    R1 = y coordinate of line
    R2 = right x coordinate of end of line
    R3 = 0 plot with no action (ie do nothing)
      1 plot using foreground colour and action
      2 invert current screen colour
      3 plot using background colour and action
      >= 4 pointer to colour block (on 64-byte boundary):
    Offset Value
    0 OR mask for top ECF line
    4 exclusive OR mask for top ECF line
    8 OR mask for next ECF line
    12 exclusive OR mask for next ECF line
    ...
    56 OR mask for bottom ECF line
    60 exclusive OR mask for bottom ECF line
    R14 = return address
    Must be entered in SVC mode
    All registers are preserved on exit

    All coordinates are in terms of pixels from the bottom left of the screen. The line is clipped to the graphics window, and is plotted using the colour action specified by R3. The caller must have previously called OS_RemoveCursors and call OS_RestoreCursors afterwards.

  • GcolOraEorAddr points to colour blocks for current GCOLs. If the value returned is n, then:

    n+&00-n+&3F is a colour block for the foreground colour + action
    n+&40-n+&7F is a colour block for the background colour + action
    n+&80-n+&BF is a colour block for the background colour with store action

    Each colour block is as described above. These are updated whenever a GCOL or TINT is issued or the ECF origin is changed. They are intended for programs which want to access screen memory directly and have access to the current colour/action settings.

Related SWIs

OS_ReadModeVariable

Related vectors

None


OS_ReadPoint
(SWI &32)

Read the colour of a point

On entry

R0 = x coordinate
R1 = y coordinate

On exit

R0, R1 preserved
R2 = colour
R3 = tint
R4 = screen flag

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

The coordinates passed are in external units and are relative to the current graphics origin.

OS_ReadPoint takes a point and returns its colour in R2 and its tint setting (amount of white, in the range 0-255) in R3. R4 returns the following:

    Value Meaning
    0 Point on the screen
    -1 Point off the screen (R2 = -1 also)

See VDU 19 for a description of colour and tint values.

Related SWIs

None

Related vectors

None


OS_ReadModeVariable
(SWI &35)

Read information about a screen mode

On entry

R0 = screen mode, or -1 for current mode
R1 = variable number

On exit

R0, R1 preserved
R2 = value of variable
the C flag is set if variable or mode numbers were invalid

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

OS_ReadModeVariable allows you to read information about a particular screen mode without having to change into that mode. The possible variable numbers are given below:

Name Number Meaning
ModeFlags 0 The bits of the result have the following meanings:
    Bit 0 = 0 graphics mode
      = 1 non-graphics mode
    Bit 1 = 0 non-Teletext mode
      = 1 Teletext mode
    Bit 2 = 0 non-gap mode
      = 1 gap mode
    Bit 3 = 0 non-gap mode
      = 1 'BBC' gap mode (eg modes 3 and 6)
    Bit 4 = 0 not Hi-resolution mono mode
      = 1 Hi-resolution mono mode
    Bit 5 = 0 VDU characters are normal height
      = 1 VDU characters are double height
    Bit 6 = 0 hardware scroll used
      = 1 Maximum column number for printing text ie number of columns-1.
ScrBRow 2 Maximum row number for printing text ie number of rows-1.
NColour 3 Maximum logical colour ie either 1, 3, 15 or 63 (not 255).
XEigFactor 4 This indicates the number of bits by which an X coordinate must be shifted right to convert to screen pixels. Thus if this value is n, then one screen pixel corresponds to 2n external coordinates in the X direction.
YEigFactor 5 This indicates the number of bits by which a Y coordinate must be shifted right to convert to screen pixels. Thus if this value is n, then one screen pixel corresponds to 2n external coordinates in the Y direction.
LineLength 6 Offset in bytes from a point on a pixel row to the same point on the pixel row below.
    On current hardware this is the same as (characters per row) × (bits per pixel) × (pixel width of character) / 8; for example, in mode 15 it is 80×8×8/8, or 640. You must not assume this will always be the case.
ScreenSize 7 Number of bytes one screen buffer occupies. This must be a multiple of 256 bytes.
YShftFactor 8 Scaling factor for start address of a screen row. This variable is kept for compatibility reasons and should not be used.
Log2BPP 9 LOG base 2 of the number of bits per pixel.
Log2BPC 10 LOG base 2 of the number of bytes per character. It is in fact the LOG base 2 of the number of bytes per character divided by eight. So in mode 0, for example, it is LOG base 2 of (8/8), or 0. In mode 15 it is LOG base 2 of (64/8), or 3. It would be exactly the same as Log2BPP, except for the 'double pixel' modes.
XWindLimit 11 Number of x pixels on screen-1.
YWindLimit 12 Number of y pixels on screen-1.

Related SWIs

OS_ReadVduVariables

Related vectors

None


OS_RemoveCursors
(SWI &36)

Remove the cursors from the screen

On entry

-

On exit

-

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

OS_RemoveCursors removes the cursors (output and copy, if active) from the screen, saving the old state (their positions, flash rate etc.) on an internal stack so that it may be recovered later. This instruction must always be balanced later by a OS_RestoreCursors to restore the cursor again.

This call is provided only for routines that need direct screen access.

Note that routines that directly access the screen may need to run in SVC mode if the routines are to work with hardware scrolled screens, which may straddle the logical-physical memory boundary at 32MByte. If the routines do not need to work with hardware scrolled screens, then USR mode is adequate.

Related SWIs

OS_RestoreCursors

Related vectors

None


OS_RestoreCursors
(SWI &37)

Restore the cursors to the screen

On entry

-

On exit

-

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

OS_RestoreCursors restores the cursor state previously saved on the internal stack using OS_RemoveCursors.

This call is provided only for routines that need direct screen access.

Related SWIs

OS_RemoveCursors

Related vectors

None


OS_CheckModeValid
(SWI &3F)

Check if it is possible to change to a specified mode

On entry

R0 = mode number to check

On exit

if C flag = 0 then mode is valid:

    R0 preserved
if C flag = 1 then mode is invalid:
    if R0 = -1 then mode is non-existent:
      R1 = mode that would be used, or -2 if unable to select alternative mode
    if R0 = - 2 then not enough memory:
      R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

OS_CheckModeValid determines whether you can change to a given mode and return with the carry bit appropriately set. If the mode you're checking is not available on the current type of monitor, then R1 will contain the mode that will be used if an attempt is made to select the mode which you are checking, using VDU 22. If there is insufficient memory or the call is unable to determine an alternative for another reason, then -2 will be returned.

If this call returns that there is insufficient memory for the required mode, then it can be borrowed from other areas of the machine. See the chapter entitled Memory Management for details.

Note: For all versions of RISC OS, this call returns -2 to indicate there is 'insufficient memory' if the currently allocated amount of screen memory is too little for the specified mode. It does not take into account whether the area could grow.

Related SWIs

None

Related vectors

None


OS_Plot
(SWI &45)

Direct VDU call

On entry

R0 = plot command code
R1 = x coordinate
R2 = y coordinate

On exit

R0 - R2 corrupted

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call is equivalent to a VDU 25 command. However, it is much more efficient as only one call is required (instead of six calls to OS_WriteC). The call goes directly to the VDU drivers unless spooling has been turned on, redirection has been turned on or if WrchV has been claimed.

Related SWIs

None

Related vectors

WrchV


OS_SetECFOrigin
(SWI &56)

Set the origin of the ECF patterns

On entry

R0 = x coordinate
R1 = y coordinate

On exit

R0, R1 preserved

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

By default, the alignment of ECF patterns is with the bottom left corner of the screen. This command makes the bottom left of the pattern coincide with the bottom left of the specified point.

The origin is restored to the default after a mode change.

VDU 23,17,6 performs the same action.

Related SWIs

None

Related vectors

None


OS_ReadSysInfo
(SWI &58)

Read system information

On entry

R0 = reason code

On exit

R0 - R4 depend on reason code

Interrupts

Interrupt status is not altered
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is re-entrant

Use

This call reads various system information, depending on the reason code passed in R0. Current reason codes are:

Related SWIs

None

Related vectors

None


OS_ReadSysInfo 0
(SWI &58)

Read the configured screen size in bytes

On entry

R0 = 0 (reason code)

On exit

R0 = amount of configured screen memory, in bytes

Use

This call reads the configured screen size in bytes (which is that used after the next hard reset). See *Configure ScreenSize.


OS_ReadSysInfo 1
(SWI &58)

Read the configured Mode/WimpMode, MonitorType, and Sync

On entry

R0 = 1 (reason code)

On exit

R0 = configured Mode/WimpMode
R1 = configured MonitorType
R2 = configured Sync

Use

This call reads the configured Mode/WimpMode (which, from RISC OS 3 onwards, are identical), MonitorType, and Sync. See *Configure Mode, *Configure WimpMode, *Configure MonitorType, and *Configure Sync.

If any of the above have been configured to 'Auto', then the appropriate value for the attached monitor is returned.

This call is not available under RISC OS 2.


OS_ReadSysInfo 2
(SWI &58)

Read the presence of various chips, and unique machine ID

On entry

R0 = 2 (reason code)

On exit

R0 = IOEB ASIC presence flag

0 => absent
1 => present (type 1)
R1 = 82C710 (or similar) presence flag
0 => absent
1 => present
R2 = LCD ASIC presence flag
0 => absent
1 => present (type 1)
R3 = word 0 of unique machine ID, or 0 if unavailable
R4 = word 1 of unique machine ID, or 0 if unavailable

Use

This call checks for the presence of various chips, returning flags. It also reads the unique machine ID if a suitable chip is fitted to the computer; if none is, then the call returns an ID of zero.

Flag values not shown above are reserved for future hardware platforms that may have versions of the chips which are not backwards compatible.

This call is not available under RISC OS 2.


OS_ReadSysInfo 3
(SWI &58)

Read features mask for 82C710 chip family

On entry

R0 = 3 (reason code)

On exit

R0 = 82C710/82C711 basic features mask (see below)
R1 = 82C710/82C711 extra features mask (reserved for upwards compatible additional functionality)
R2-R4 reserved for future expansion

Use

The 82C710 family of chips are composed of several sub-units. Future chips in the family may have some sub-units which are incompatible with earlier versions, while leaving the functionality of other sub-units unchanged. This call returns a features mask, sub-fields within which show the 'compatibility level' of each sub-unit. Differing values of a sub-field indicate incompatible versions of the corresponding sub-unit. A sub-field of zero indicates that the sub-unit is not present. The values for the 82C710 and 82C711 are:

    Bits Sub-unit 82C710 82C711
    0 - 3 IDE hard disc interface 1 1
    4 - 7 floppy disc interface 1 1
    8 - 11 parallel port 1 1
    12 - 15 1st serial port 1 1
    16 - 19 2nd serial port 0 1
    20 - 23 chip configuration 1 2
    24 - 31 reserved 0 0

(The 710 only supports a single serial port. Obviously the 710 and 711 have differing chip configurations.)

If a sub-unit gains additional backwards-compatible functionality in future versions of the chip, this will be indicated by having bits set in the value returned in R1. Information on extra sub-units will be accommodated in the remaining bits of R0, or in R2-R4.

This call is not available under RISC OS 2, nor under RISC OS 3 (version 3.00).


OS_ChangedBox
(SWI &5A)

Determine which area of the screen has changed

On entry

R0 = 0 disable changed box calculations
1 enable changed box calculations
2 reset changed box to null rectangle
-1 read changed box information

On exit

R0 = previous enable state in bit 0 (0 for disabled, 1 for enabled)
R1 = pointer to a fixed block of 5 words, containing the following info:

R1+0 = new disable/enable flag (in bit 0)
R1+4 = x coordinate of left edge of box
R1+8 = y coordinate of bottom edge of box
R1+12 = x coordinate of right edge of box
R1+16 = y coordinate of top edge of box

The (R1+4) to (R1+16) values are only valid if the change box calculations were in an enabled state immediately after the call; otherwise they are undefined.

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

SWI is not re-entrant

Use

This call checks which areas of the screen have changed over calls to the VDU drivers. When this feature is enabled, RISC OS maintains the coordinates of a rectangle which completely encloses any areas that have changed since the last time the rectangle was reset.

This is particularly useful for applications which switch output to sprites, and then want to repaint the sprite onto the screen after performing VDU operations on the sprite. The application can make significant speed improvements by only repainting the section of the sprite which corresponds to the changed box.

All coordinates are measured in pixels from the bottom left of the screen. If a module provides extensions to the VDU drivers, it should read the address of this block on initialisation, and update the coordinates as appropriate. If an exact calculation of which areas have been modified is difficult, then the module should extend the rectangle to include the whole of the graphics window (or indeed the whole screen, if the operation can affect areas outside the graphics window).

The disable/enable flag at offset 0 in the block is for information only - it must not be modified directly, as RISC OS holds the master copy of this flag.

Changed box calculations are disabled on a mode change. However, the disable/enable state and the coordinates of the rectangle form part of the information held in save areas when output is switched between the screen and sprites.

Related SWIs

None

Related vectors

None


OS_SetColour
(SWI &61)

Sets the foreground or background graphics colours

On entry

R0 = flags:

bits 0 - 3 graphics plotting action (see below)
bit 4 set => ALTER BACKGROUND_ CLEAR => alter foreground
bit 5 set => R1 = PATTERN DATA_ CLEAR => R1 = colour number
bits 6 - 31 reserved (must be zero)
R1 = colour number (if R0 bit 5 is clear), or pointer to eight words of pattern data (if R0 bit 5 is set)

On exit

--

Interrupts

Interrupt status is undefined
Fast interrupts are enabled

Processor Mode

Processor is in SVC mode

Re-entrancy

Not defined

Use

This call sets the foreground or background graphics colours.

You can obtain the colour number to use from ColourTrans_ReturnColourNumber. You can supply an eight word pattern block to use giant ECFs instead of solid colours. With this call you can define a giant pattern for both the foreground and background colours, whereas the VDU drivers only allow you to set a single pattern for both (see VDU 23,2-5 on VDU 23,2-5).

The graphics plotting action passed in bits 0 - 3 of R0 is as follows:

Value Action
0 Overwrite colour on screen with colour
1 OR colour on screen with colour
2 AND colour on screen with colour
3 exclusive OR colour on screen with colour
4 Invert colour on screen
5 Leave colour on screen unchanged
6 AND colour on screen with (NOT colour)
7 OR colour on screen with (NOT colour)
8 - 15 As 0 to 7, but background colour is transparent

Related SWIs

ColourTrans_ReturnColourNumber

Related vectors

None

*Commands


*Configure Loud

Sets the configured volume for the beep to be loud

Syntax

*Configure Loud

Parameters

None

Use

*Configure Loud sets the configured volume for the beep to be loud.

The change takes effect on the next reset.

Related commands

*Configure Quiet

Related SWIs

OS_Byte 212

Related vectors

None


*Configure Mode

Sets the configured screen mode used

Syntax

*Configure Mode screen_mode|Auto

Parameter
screen_mode the display mode that the computer should use after a power-on or hard reset, and when entering or leaving the desktop
Auto automatic setting of appropriate mode using monitor lead
Use

*Configure Mode sets the configured screen mode used by the machine when it is first switched on, or after a hard reset, and when entering or leaving the desktop. It is identical to the command *Configure WimpMode; the two commands alter the same value in CMOS RAM.

You can also set a value of Auto (not available in RISC OS 2). More recent Acorn computers can sense the type of monitor lead connected, and hence set an appropriate mode. If no lead can be sensed, either because none is present or because the computer is of an older design, the mode defaults to mode 12.

Under RISC OS 2, this command only sets the configured screen mode used for the command line; *Configure WimpMode sets the configured screen mode used for the Desktop.

Example

*Configure Mode 27 selects VGA mode with 16 colours

Related commands

*Configure WimpMode, VDU 22

Related SWIs

None

Related vectors

None


*Configure MonitorType

Sets the configured monitor type

Syntax

*Configure MonitorType n|Auto

Parameters
n 0 to 5
Auto automatic sensing of monitor type using monitor lead
Use

*Configure MonitorType sets the configured monitor type that is connected to the computer. The values of n correspond to the following monitors:

n Monitor
0 50Hz TV standard colour or monochrome monitor
1 Multiscan monitor
2 Hi-resolution 64Hz monochrome monitor
3 VGA-type monitor
4 Super-VGA-type monitor (not available in RISC OS 2)
5 LCD (liquid crystal display) (only available on portables)

You can also set a value of Auto (not available in RISC OS 2). More recent Acorn computers can sense the type of monitor lead connected, and hence set the monitor type. If no lead can be sensed, either because none is present or because the computer is of an older design, the monitor type defaults to 0, save for portables, which default to 5 (an LCD).

You can also configure the monitor type by holding down the corresponding key from the numeric keypad while the computer is switched on.

Example
*Configure MonitorType 3 configure VGA-type monitor
Related commands

VDU 22

Related SWIs

None

Related vectors

None


*Configure MouseStep

Sets the configured value for how fast the pointer moves as you move the mouse

Syntax

*Configure MouseStep n

Parameters
n a number between 1 and 127
Use

*Configure MouseStep sets the configured value for how fast the pointer moves as you move the mouse. Useful values of n are 1, 2 or 3 for slow, medium or fast, respectively.

The mouse position is moved by n coordinates for each movement of the mouse. Although values up to 127 are accepted, anything above 6 is impractical because the step is too large.

You can also use OS_Word 21,2 to set the mouse step dynamically.

Example

*Configure MouseStep 3 select a fast speed

Related commands

None

Related SWIs

OS_Word 21,2

Related vectors

None


*Configure NoScroll

Sets the configured scrolling so the screen does not scroll upwards at the end of a line

Syntax

*Configure NoScroll

Parameters

None

Use

*Configure NoScroll sets the configured scrolling so that a newline is not generated when a character is printed at the end of a line. The default value is Scroll.

When printing a character in VDU 4 mode results in the cursor moving beyond the edge of the window, a 'pending newline' is generated. It is actually executed just before the next character is printed, provided that it has not been deleted or executed by another cursor control character. For example VDU 127 would cancel it; VDU 9 would execute it.

Refer to VDU 23,16 for a lengthier description of NoScroll, and for details of how to set this option dynamically.

Related commands

*Configure Scroll

Related SWIs

None

Related vectors

None


*Configure Quiet

Sets the configured volume for the beep to half its loudest volume.

Syntax

*Configure Quiet

Parameters

None

Use

*Configure Quiet sets the configured volume for the beep to half its loudest volume.

The change takes effect on the next reset.

Related commands

*Configure Loud

Related SWIs

OS_Byte 212

Related vectors

None


*Configure ScreenSize

Sets the configured amount of memory reserved for screen display

Syntax

*Configure ScreenSize mK|n

Parameters
mK number of kilobytes of memory reserved
n number of pages of memory reserved; n <= 127
Use

*Configure ScreenSize sets the configured amount of memory reserved for screen display. The default value is 80Kbytes on a 0.5Mbyte machine, and 160Kbytes for all other machines.

You can also use OS_ChangeDynamicArea to alter the screen memory allocation dynamically. For more information, refer to the chapter entitled Memory Management.

You cannot configure more than 480Kbytes of screen memory, due to limitations in the MEMC1 and MEMC1a memory controllers.

Example

*Configure ScreenSize 160K reserve 160Kbytes for screen display

Related commands

None

Related SWIs

OS_ChangeDynamicArea

Related vectors

None


*Configure Scroll

Sets the configured scrolling so the screen scrolls upwards at the end of a line

Syntax

*Configure Scroll

Parameters

None

Use

*Configure Scroll sets the configured scrolling so that a newline is generated automatically when a character is printed at the end of a line. This is the default value.

When printing a character in VDU 4 mode results in the cursor moving beyond the edge of the window, the cursor is instead moved to the negative x edge of the window and one line in the positive y direction.

Refer to VDU 23,16 for a lengthier description of Scroll, and for details of how to set dynamically this option.

Related commands

*Configure NoScroll

Related SWIs

None

Related vectors

None


*Configure Sync

Sets the configured type of synchronisation for vertical sync output

Syntax

*Configure Sync 0|1|Auto

Parameters
0 vertical sync
1 composite sync
Auto automatic sensing of required synchronisation type using monitor lead

Use

*Configure Sync sets the configured type of synchronisation that is provided on the vertical sync output of the video connector. This may be vertical sync (parameter of 0) or composite sync (parameter of 1).

You can also set a value of Auto (not available in RISC OS 2). More recent Acorn computers can sense the type of monitor lead connected, and hence set the required synchronisation type. If no lead can be sensed, either because none is present or because the computer is of an older design, the synchronisation type defaults to 1 (composite sync).

Example

*Configure Sync 1

Related commands

None

Related SWIs

None

Related vectors

None


*Configure TV

Sets the configured vertical screen alignment and screen interlace

Syntax

*Configure TV [vert_align[[,]interlace]]

Parameters
vert_align adjusts the vertical screen alignment 0 to 3 lines up (values of 0-3 respectively), or 1 to 4 lines down (values of 255-252 respectively)
interlace switches screen interlace on (with a value of 0), or off (with a value of 1)
Use

*Configure TV sets the configured vertical screen alignment and screen interlace. The default values are 0,1 (no vertical alignment offset and interlace off).

Example

*Configure TV 0,1 the default value

Related commands

*TV

Related SWIs

None

Related vectors

None


*Shadow

Sets which bank of screen memory is used on subsequent mode changes

Syntax

*Shadow [0|1]

Parameters

0 or 1 or nothing

Use

*Shadow sets which bank of screen memory is used on subsequent changes to the screen mode. It controls two banks of screen memory: the normal bank (bank 1, known as the non-shadow bank), and an alternate bank (bank 2, known as the shadow bank).

If you give either no parameter, or a parameter of 0, the shadow bank is used on the next mode change. If you give a parameter of 1, the non-shadow bank is used on the next mode change.

For the shadow bank to be used, there must be at least double the memory for the selected screen mode available in the screen area of memory. For example, to use shadow memory in screen mode 8 (a mode which requires 40Kbytes), at least 80Kbytes of screen memory must be available.

This command is provided for backwards compatibility only, since there is no useful benefit in using twice as much screen memory.

Example

*Shadow 1

Related commands

*Configure ScreenSize

Related SWIs

None

Related vectors

None


*TV

Adjusts the vertical screen alignment and screen interlace

Syntax

*TV [vert_align[[,]interlace]]

Parameters
vert_align adjusts the vertical screen alignment 0 to 3 lines up (values of 0-3 respectively), or 1 to 4 lines down (values of 255-252 respectively)
interlace switches screen interlace on (with a value of 0), or off (with a value of 1)
Use

*TV adjusts the vertical screen alignment and screen interlace.

The change takes effect on the next mode change.

Example

*TV 3,0 move the picture up 3 lines, and turn interlace on

Related commands

*Configure TV

Related SWIs

None

Related vectors

None

Application Notes

Examples of ECF pattern use

This section gives some examples of how you might set ECF patterns using the VDU 23,2-5... commands.

In BBC/Master compatible mode

For example in modes with four bits per pixel, bits 7, 5, 3 and 1 of the n parameter control the logical colour of the left-hand pixel, and bits 6, 4, 2 and 0 control the right-hand pixel. To set the left pixel to colour 2 (green by default) and the right one to colour 7 (white), the colours are combined as follows:

Pixel 1 colour (left) Green 2 0010
Pixel 2 colour (right) White 7 0111
Bit 7 6 5 4 3 2 1 0
Left pixel 0   0   1   0
Right pixel   0   1   1   1
Result 0 0 0 1 1 1 0 1

Resulting value = &1D (29)

Whereas in modes with two bits per pixel the method is:

Pixel 1 colour (left) Yellow 2 10
Pixel 2 colour Red 1 01
Pixel 3 colour White 3 11
Pixel 4 colour (right) Yellow 2 10
Bit 7 6 5 4 3 2 1 0
Pixel 1 1       0
Pixel 2   0       1
Pixel 3     1       1
Pixel 4       1       0
Result 1 0 1 1 0 1 1 0

Resulting value = &B6 (182)

In RISC OS native mode

In RISC OS mode, for example, in modes with four bits per pixel, the colour of the left-hand pixel is formed from bits 3, 2, 1 and 0 of the n parameter, and the colour of the right-hand pixel comes from bits 7, 6, 5 and 4 of the parameter. So, if the pixels are to be logical colours 2 and 7 again, the colours are combined as follows:

Pixel 1 colour (left) Green 2 0010
Pixel 2 colour (right) White 7 0111
Bit 7 6 5 4 3 2 1 0
Right pixel 0 1 1 1
Left pixel         0 0 1 0
Result 0 1 1 1 0 0 1 0

Resulting value = &72 (114)

Notice that the pixel colours on the left, as displayed, are derived from the bits on the right, as written down, and vice versa.

In modes with two bits per pixel the method is:

Pixel 1 colour (left) Yellow 2 10
Pixel 2 colour Red 1 01
Pixel 3 colour White 3 11
Pixel 4 colour (right) Yellow 2 10

Bit 7 6 5 4 3 2 1 0
Pixel 4 1 0
Pixel 3     1 1
Pixel 2         0 1
Pixel 1             1 0
Result 1 0 1 1 0 1 1 0

Resulting value = &B6 (182)

Further examples of ECF patterns

Here are examples of how to produce a pattern of alternating red (colour 1) lines and white (colour 7) lines (with the default palette). Each of the VDU 23,2 or VDU 23,12 commands alters ECF pattern 1 to cause the same effect.

in a 2 colour mode (black and white only available):

VDU 23,12,1,1,0,0,1,1,0,0
VDU 23,2,&FF,0,&FF,0,&FF,0,&FF,0
VDU 23,17,4,1| has no effect

in a 4 colour mode:

VDU 23,12,1,1,3,3,1,1,3,3
VDU 23,2,&0F,&FF,&0F,&FF,&0F,&FF,&0F,&FF
after VDU 23,17,4,1|
VDU 23,2,&55,&FF,&55,&FF,&55,&FF,&55,&FF

in a 16 colour mode:

VDU 23,12,1,1,7,7,1,1,7,7
VDU 23,2,3,&3F,3,&3F,3,&3F,3,&3F
after VDU 23,17,4,1|
VDU 23,2,&11,&77,&11,&77,&11,&77,&11,&77

in a 256 colour mode:

VDU 23,12,&C3,&FF,&C3,&FF,&C3,&FF,&C3,&FF
VDU 23,2,&17,&FF,&17,&FF,&17,&FF,&17,&FF
VDU 23,17,4,1| has no effect

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