Video drivers (supplement for RISC OS Pyromaniac)

The vector should be claimed when it is handled entirely within the driver.

This vector is called a new destination has been selected for output. In particular, it will be called on mode change and sprite redirection. Clients should initialise any variables which are necessary for their operation. Clients wishing to handle the entire Text interface may claim this call point, but it is strongly recommended that the call be passed on.

The mode flags will indicate any special features which are present in the mode specified. In particular:

This vector should never be claimed.

This vector is called to define a character. Clients should normally make a note of the changes and pass this call on.

This vector is called whenever the text colour has been changed and text output is about to be performed. It is expected that clients initialise any cached data they require in order to render characters in the new colours. The colours supplied are values to be written to the screen for that pixel, for example, in 2 BPP modes, a foreground colour of 3 would be used to indicate that all pixels set for that character would use the value 3 in memory. Clients may need to replicate these bits across a word in order to perform operations more rapidly, however implementation details are left to the client's discretion.

This vector is called to render a character on the screen at a text position. Characters are 8x8 pixels in all modes and should be rendered in the colours specified by VideoV 2. Unset pixel data for the character should use the background colour, and set pixel data for the character should use the foreground colour. Registers R2 and R3 are provided for clients which require the actual pixel position to render the character.

This vector is called to render a 'cursor' at a text position. This should be an inverted rectangle which spans the lines of the character requested by R0, or R4 and R5. The composite cursor mask is provided for clients which use the pixel position of the character to render the shape. The cursor should be rendered at the character specified by inverting the current contents of that location. The vector will be called repeatedly in order to 'flash' the cursor. In 'split' editing mode, the vector will be called to render whichever cursor requires redrawing.

The composite cursor position indicates the start and end lines of the cursor by the SS and EE values. The EE value is the last line that should be drawn. Thus, SS=6, EE=7 would invert lines 6 and 7 within the character. Similarly, SS=8, EE=9 would invert lines 8 and 9 within the character. Line 8 and 9 are only applicable to gap-modes.

This vector is called to clear a region of the text window. The supplied description block gives the character positions, and the memory positions which require clearing. The clear operation should be performed using the fill words given in +36 and +40. These words will be the same unless the user is in a BBC-style gap mode. Such modes are not expected to be used by clients in the future and support may be omitted from accelerated modules. The software implementation provides support for all combinations.

As with other text operations, the character positions are specified with their origin at the top left.

This vector is called to set the primary colours to use for plotting graphics operations. Clients should record the details. They may pre-cache the values after determining whether they can handle the operation type.

Lines are measured from the top left of the screen and should be ANDed with 7. Consult the example VideoSW code for more details (s/GrafPoint gives an obvious use).

Whilst many store and invert operations will be simple to accelerate within drivers, the more complex operations may be deferred to the software driver where necessary. In particular, drivers should be aware that the operation pattern may not correspond directly to any PLOT reason code. Users may manually select different colour operations for different bit regions or lines.

This vector is called to set the secondary colour used for graphics operations. This is commonly called the 'background colour'. The operation is identical to that of VideoV 16.

This vector is called whenever the output changes destination, usually due to a mode change or sprite redirection. Drivers should cache the context information for use within other calls. This vector should never be claimed.

This vector is called when the output destination base address has changed. It may be called under a number of circumstances, including sprite deletion, mask changes and hardware scrolling. Drivers should make a note of the new address and base all their calculations from it.

This vector is called to read the primitive operations which can be used to render a horizontal line, a point and a vertical line. Since these operations are expected to be called regularly it is important that they be fast. Rather than using the vector dispatch for every line or point to be rendered, a single function dispatch can be used - obviating the need for a SWI call, and subsequent vector dispatch. Consult the Graf_ReadPrimitives source for more details of the operation.

This vector is called to fill a rectangle. Clients should bound the coordinates if necessary and then plot the rectangle.

This vector is called to fill a triangle. Clients should plot the triangle, bounded by the coordinates given.

This vector is called to fill a parallelogram. Clients should plot the parallelogram, bounded by the coordinates given. The coordinates given are in no particular order. The fourth verex can be calculated from the other three.

This vector is called to copy a rectangle from part of the display elsewhere. No context or colour operation is provided. The region has already been bounded to the screen and graphics window (both the source and destination are guarenteed to be within the buffer). The source data, where not overwritten, should be unaffected by the copy operation.

This vector is called to fill a circle. Clients should plot the circle, bounded by the coordinates supplied if necessary.

This vector is called to draw an arc. Clients should plot the arc, bounded by the coordinates supplied if necessary. The coordinate order and meaning is identical to that used by the PLOT arc operation. That is, first coordinate pair indicates the centre of the circle, the second pair provides the start position on the edge of the circle, and the final pair provides the end position as a point on a line that intersects the circle. The arc should be drawn anti-clockwise.

This vector is called to draw a segment. Clients should plot the segment, bounded by the coordinates supplied if necessary. The coordinate order is the same as VideoV 27. A segment fills the arc shape, closing it with a line from the start position to the intersection of the end position line and the circle.

This vector is called to draw a sector. Clients should plot the sector, bounded by the coordinates supplied if necessary. The coordinate order is the same as VideoV 27. A segment fills the arc shape, closing it with a pair of lines from the start position to the centre of the circle, and from the intersection of the end position line and the circle to the centre of the circle. The shape is often known as a 'pie' from the common shape produced by removing sections from pies.

This vector is called to draw an ellipse. Clients should plot the ellipse, outline bounded by the coordinates supplied if necessary. The coordinate order is the same as the equivilent PLOT ellipse operation. That is, the first pair gives the centre position of the ellipse, the second pair gives the width of the ellipse at centre line (the y coordinate is ignored), and the final pair gives the position of the top-most, or bottom-most limit of the ellipse.

This vector is called to draw an ellipse. Clients should plot the solid ellipse, bounded by the coordinates supplied if necessary. The coordinate order is as for the VideoV 30 operation.

This vector is called to fill a line right until a given condition is met (denoted by R2 and R3).

This vector is called to fill a line left and right until a given condition is met (denoted by R2 and R3).

This vector is called to perform a flood fill operation, stopping at a given condition (denoted by R2 and R3).

This vector is called to perform many horizontal line fill operations as a single step. The block supplied must be copied if the driver is intending to buffer these operations. Because this call is always issued through the vector, clients should try to ensure that it is worthwhile calling using this interface rather than the direct HLine interface (see OS_ReadVduVariables).

This vector is called to define one of the 4 pointer shapes. Pointer shapes are pre-compensated for the 'active' position.

This vector is called to select one of the pointers for use. Only one pointer is ever displayed at a time.

This vector is called to update the location of the pointer on the screen.

This vector is called to remove the pointer from the screen.

This vector is called to set the colour of the pointer.

This vector is called to check the validity of a mode prior to selecting it. Drivers should reject modes which they are incapable of displaying.

This vector is called to select a screen mode for use. It has already passed the vetting procedure above so should be able to be selected.

Drivers should perform the following actions on a mode change:

• Default to the first screen bank for display and driver
• Release any claimed memory for alternate screen banks
• Clear the palette to black

This vector is called to request a hardware scroll of the device. The scroll may be a change of the base of the area, as used by the VIDC driver, or an accelerated copy operation. Drivers can just ignore this operation, or return 0 for both R0 and R1 to indicate that the hardware scroll is not supported. The Kernel can perform the necessary operations if they are not supported by the driver.

Note: (R0 AND NOT 7) lines should be filled with R2.
(R0 AND 7) lines should be filled with R3.

This allows the system to provide gap modes in the same manner as the BBC did.

This vector is called to change the displayed colours. The operation of regular palette entries is defined within paletted modes only. Drivers or hardware not supporting the screen 'border' colour should ignore the operation. Drivers which cannot provide the full 24bit colour specification should make best effort to match the colours requested. The colours should be transformed by any RGB tables specified in a separate call if the hardware does not support any specific transformation configuration.

Where RGB tables are not supported by the hardware, it will be necessary to take a copy of the palette entries.

This vector is called to enable the display hardware. This operation is intended to allow components to restart the display hardware for client defined reasons. The Portable module may use this to control the power to the hardware when requested.

This vector is called to disable the display hardware. This operation is intended to allow components to shut down and restart the display hardware for client defined reasons. The Portable module may use this to control the power to the hardware when requested.

This vector is called to select an immediate power-save mode should be entered. Regardless of whether this call is handled or not, the palette will be set to black. Drivers should expect to get palette operations whilst blanked. They may wish to ignore these.

The state values (with the exception of -1) are directly modelled after the DPMS states. -1 can be treated as equivilent to 0 for the purposes of H/V sync control.

If mapping directly to HSync and VSync lines, these values are:

Hardware may promote or demote these settings as it sees fit, but this should be documented in hardware documentation as appropriate.

This vector is called to modify the RGB mapping tables, through which the palette entries will be transformed. The palette should be affected immediately. Where the hardware does not support RGB mapping tables it will be necessary to translate all palette operations through the tables. It is expected that unpaletted modes (16bpp, 32bpp) support this operation, even though they do not use palette entries.

This vector is called to control the generic acceleration options provided by the video driver. The core acceleration options are to provide a CPU cached screen. One effect of CPU cached screen is an undesirable delay on data being written to the physical screen memory from the processor. This data should be flushed by the driver regularly, if it detects that data has been written to the screen. It is usual to use abort trapping, domain mapped dynamic areas to manage this process (consult the example VIDC driver).

Bit 0 and 1 can be used to suspend this operation until the next mode change. Clients will probably use this for specialised tasks to ensure that their output is immediately visible, such as within games or high responsiveness applications.

Bit 2 is intended to allow clients to disable all hardware acceleration. Whilst this is generally not desirable, it may be useful to clients who either believe there to be faults within the hardware acceleration or who wish to determine the difference made by hardware acceleration. Hardware acceleration is should not be re-enabled by a mode change as the client may wish to examine mode change timings, or it may be believed that mode change acceleration is faulty.

This vector call is triggered by OS_ScreenMode 4.

This vector is called to cause the screen to be made up to date if necessary such that the data written to it is visible to the user. It is likely that these operations will be used by games. The WindowManager will use this call at the end of a series of redraw operations.

This vector call is triggered by OS_ScreenMode 5 and 6 at present.

This vector is called to inform display device drivers of a device selection. Drivers should claim VSync interrupts when they are enabled and begin generating VSyncs through the VSync dispatch entry point returned when they registered with OS_ScreenMode 255. Drivers should release the VSync interrupts when another device is selected.

This vector is called to request the number of screen banks that can be supported by the current configuration of the display. The driver should return the maximum number of banks that may be supported at the instant that the request was made. Subsequent driver operations may cause this value to change.

This vector is called to request a change of display bank. The display bank is presented to the user. Both display and driver banks should be available in memory simultaneously once selected and may both be written to directly. They may be coincident. Once requested (and the request honoured), the Driver should maintain the memory allocated for that bank until the next mode change. Drivers are not required to page all available, or used, banks into logical memory at any time. At the drivers discretion it may remove mappings a bank which is not the driver or display from logical memory. Clients are not expected to access banks which are not selected. Drivers are not expected to support hardware scrolling of any bank but the display bank. Selection of a pre-existing bank should not clear its contents.

This vector is called to request a change of driver bank. The driver bank is presented to the video drivers for writing to. Both display and driver banks should be available in memory simultaneously once selected and may both be written to directly. They may be coincident. Once requested (and the request honoured), the Driver should maintain the memory allocated for that bank until the next mode change. Drivers are not required to page all available, or used, banks into logical memory at any time. At the drivers discretion it may remove mappings a bank which is not the driver or display from logical memory. Clients are not expected to access banks which are not selected. Drivers are not expected to support hardware scrolling of any bank but the display bank. Selection of a pre-existing bank should not clear its contents.

This vector is called when a client requests a copy of a screen bank be made. If the destination bank has not yet been allocated it should be allocated. The banks requested need not be paged in to logical memory. Drivers which require the banks to be paged in to logical memory for the copy to take place should take the necessary steps to achieve this. This operation must not affect any other bank by the destination. Clients are expected to perform a bank switch to update the display bank, rather than a bank copy.

This vector is called to initialise teletext mode. The values supplied in R0 and R1 are the requested number of columns and rows for the mode. The driver should either fit those values within the graphics limitations of the mode, or modify the values to be acceptable before return. The frame buffer does not need to be initialised.

This vector is called to clear a region of the display. It is used after mode selection and for CLS operations. The frame buffer does not need to be updated.

This vector is called to update the frame buffer with the previously applied changes. This is the primary point at which the frame buffer should be modified.

This vector is called to change the character at a given position. The frame buffer does not need to be updated. The change of the character may change not only the representation of the character at that position, but also all subsequent character on that line and (potentially) the characters on the line below.

This vector is called to scroll a region of the teletext buffer. The frame buffer does not need to be updated. The change of the region may also result in surrounding characters being changed in their representation.

This vector is called to update the state of the display with respect to flashing characters. The frame buffer does not need to be updated. This entry point may be called under interrupts.

This vector is called to read a character from the display at a position. It is used during the character copying routines, via the OS_Byte mechanisms.

This vector is called to invert a cursor on the screen. It is used to flash the cursor whilst updating the display. It may be called under interrupts.

This vector is called in response to VDU23,18,16,flags| to set the quality of the display. Display drivers may use it to provide a higher quality (and potentially slower) implementation.

This vector is called in response to VDU23,18,2,flags| to change the reveal state. Display drivers may update the hidden characters to be visible immediately or defer this until an update.