Copyright � Acorn Computers Ltd. 1993 0197,254/FS Issue 1
Medusa Video Software Functional Specification
==============================================
-----------------------------------------
| Drawing No : 0197,254/FS |
| Issue : 1.09 |
| Date : 9th March 1993 |
| Author : Alan Glover |
| Sheets : |
| Last Issue: 1.0 |
-----------------------------------------
Contents
--------
1 History
2 Outstanding issues
2.1 General
2.2 Other items
3 Overview
3.1 General
3.2 What won't be done
4 Technical Background
4.1 CLUT
4.2 Primary Colour
4.3 Colourtrans in 8bpp
5 User Interface
5.1 Mode Chooser & Palette utility
5.2 !Draw
5.3 !Paint
6 Programmer Interface
6.1 OS_SetColour
6.2 ColourTrans
6.2.1 ColourTrans_SelectTable
6.2.2 Passing Mode Selectors to ColourTrans
6.3 GCOL numbers
6.4 Selecting modes
6.5 Compatibility
6.5.1 VDU 22
6.5.2 VDU 17/18
6.5.3 8 bits of colour component
6.5.4 Colourtrans matching
6.5.5 Altering the palette
6.5.6 8bpp VIDC 1 model
6.5.7 OS_Word 9
6.5.8 OS_Word 11
6.5.9 OS_Word 12
6.5.10 NCOL
6.5.11 VDU 23,17,0-3
6.6 Modeflags bit 7
6.7 Support for the new sprite format
6.8 New ColourTrans matching algorithms
6.9 New PaletteV reason codes
6.10 Use new PalettV reason codes in ColourTrans
6.11 Programming the Supremacy bits
7 Data Formats
7.1 New sprite format
8 Protocols
9 External Dependencies
10 Development Test Strategy
10.1 SWI level comparisons
10.2 Performance Assessment
10.3 Stress Testing Programs
10.4 Application of test methods
10.5 SWIs directly affected
11 Organisation
12 Future Enhancements
12.1 Kernel reduction
12.2 Mode Editor
12.3 Adaptive mode chooser
12.4 Enhanced Colour Picker
12.5 Gamma correction for monitors
12.6 New sprite routines
12.7 New sprite format
1. History
##########
0.00 AMG 29-Oct-92 Started
0.01 AMG 09-Dec-92 Substantial revisions. Still pre-release.
0.02 AMG 14-Dec-92 Embed information from earlier stand-alone
documents. Incorporate the video aspects of
the would-have-been Software Emulation FS.
0.03 AMG 21-Dec-92 More tidying up and new material ready for
pre-draft release.
0.04 AMG 25-Jan-93 Finalise edits during Jan for new release.
(not issued). Change project name.
0.05 AMG 29-Jan-93 Rework to show revised level of work,
and move several items to the futures
section.
0.06 AMG/JSR/TMD Evolve into present FSpec. Various
09-Feb-93 items move to futures section.
Bring back line doubling and VIDC1 emulation
material.
0.07 AMG 17-Feb-93 Move VIDC 1 & Line doubling out of scope
of main FS.
0.08 AMG 19-Feb-93 Move Colour Picker & mode choice out of
scope of the main FS.
1.00 AMG 22-Feb-93 Released for review.
1.01 AMG 25-Feb-93 Update to add additional items, and
clarify future of sprite format.
Change name to Medusa. Move items which
may or may not be done out to subsidiary
documents. Beware - many sections have
been renumbered to close the gaps where
sections have been removed.
1.02 AMG 26-Feb-93 Reinstate the Colour Picker and supporting
stuff in ColourTrans/kernel. Move Colour
Picker out to a separate document to
become a FS in its own right.
1.03 AMG 04-Mar-93 Drop in new Development Test Strategy section
1.04 AMG 08-Mar-93 Various edits to incorporate review comments
1.05 AMG 10-Mar-93 Incorporate edits from the review of the Mode
Choice API.
1.06 AMG 15-Mar-93 Finalise post-review editing and changes
resulting from Colour Picker review.
1.07 JSR 29-Mar-93 Fix typo in Log2bpXs from ReadModeVariable.
Add read function to OS_SetColour for FontMgr.
1.08 JSR 30-Mar-93 Correction to read function of OS_SetColour.
1.09 AMG 16-Apr-93 Fix typo in bit fields for PaletteV 7/8
Describe Spriteextend behaviour when given a
full palette sprite to plot in 16/32bpp
Mode Chooser must now enumerate choices via
the kernel.
Add R0=0 & R3=0 speedup for PaletteV 7/8
1.10 AMG 11-May-93 Correct information for ColourTrans_ReturnGCOL
2.00 JSR 02-Jun-93 Add optional F<frame rate> to mode description string
2.01 SMC 05-Jul-93 Updated section 5.1 (mode chooser) as a result of
implementation.
2. Outstanding Issues
#####################
2.1 General
===========
Final choices for new screen modes/names. Which do we provide? To help the
sprite routines it may be necessary to have a representative 16bpp and 32bpp
screen mode defined in the present manner.
2.2 Other items
===============
This FS contains only the major aspects of the Video Software work. Other
related documents are:
0197_290FS - FS for Mode Choice API
col_API_UI - Colour Picker API and UI (to become a FS in due course)
?????????? - Specification of work needed to printer drivers
3 Overview
##########
3.1 General
===========
Omega platforms produced by the Medusa project will use VIDC20 rather than
the VIDC1/1A used in all RISC OS computers to date.
This gives new 16 bits per pixel (bpp) and 32bpp screen displays, as well as
an 8bpp display which allows 256 independently specified colours (under
VIDC1 the 8bpp displays gave 64 colours with four intensities of grey
added). However the useful capability will depend upon the amount of screen
memory available. In computers with no VRAM, there will be a tradeoff
between DRAM consumption/bandwidth for video and processor usage.
Introducing VIDC20 means that supporting work is essential in the
Kernel, SpriteExtend module and ColourTrans module to support the new
8/16/32 bpp modes.
Furthermore, our present colour picking and mode choosing metaphors
become severely strained with the added range of colours and choice of
potential screen modes.
A new Colour Picker and mode chooser is needed, however neither are
covered fully in this FS. Work to date on the UI & API for the Colour Picker
is available in a separate document, which will be issued as FS in due
course. The Mode Choice API is a separate document, and the Mode Choice UI
is documented herein.
It is also time to modify the sprite format to remove its present dependence
upon the screen mode number that the sprite was defined in, though this FS
stops short of the full new sprite format originally proposed and
distributed in May last year.
Within this FS an extension of the existing sprite format is detailed,
deferring the creation of a new cure-all sprite format for more
consideration as part of the RISC OS Gold project.
3.2 What won't be done
======================
This section lists those items which have been discussed for inclusion in
this FS, but have NOT been included. See also the Future Enhancements
section at the end of this FS for more ideas which "didn't quite make it".
* The sprite format changes here differ from those previously publicised.
* No new Sprite operations are being introduced, specifically support for
dithered plots will not be introduced.
* Changes to BASIC to support the Mode Choice API (though the SWIs may be
used directly).
* BASIC will not be altered in any way to cope with the changes introduced
in this FS (though the SWIs may be used directly).
* No desktop support for use of 8bpp with an arbitrary palette.
* Transparency masks/attached palettes on 16/32bpp sprites are not
supported.
* 1/2/4/8bpp sprites with masks or palettes must be old format (T=0). Using
T=1-4 sprites with a mask or palette will generate an error.
* ChangeFSI will not be specifically updated for Medusa as part of the
planned work. However a suitable version will be shipped with the product.
* Extra mode modules for RISC OS 3.10 and below using the mode extension
interface will no longer work (because support is not included for a VIDC 1
list).
* !Paint will not be able to edit 16 or 32bpp sprites.
4 Technical Background
######################
4.1 CLUT
========
Colour look-up Table. A table of values through which the value stored
in screen memory may be passed to obtain the R,G or B colour intensity to
use. VIDC20 provides three 256 entry CLUTs - one for each primary colour.
4.2 Primary Colour
==================
Red, Green and Blue. These are the three additive primaries - all
colours may be made by adding combinations of these together (though
not all colours which are possible can be displayed on any given
device!)
4.3 ColourTrans in 8bpp modes
=============================
Calculating colour matches in 8bpp modes is the scenario likely to
involve ColourTrans in the most computation.
With 8bpp modes, there is the possibility of 256 completely
independently chosen colours. This means that matching an arbitrary
RGB colour to the best available could involve working out 768 weighted
least square computations to find the closest colour.
To ease this situation there will be two major changes made in ColourTrans.
When mapping from 16/32bpp down to 8bpp or below ColourTrans_SelectTable
will return a structure including a pointer to a 32K table which provides a
mapping for 5 bits of each primary onto a colour number. See section 6.2 for
more details.
For bpp combinations where the target is 8bpp or below ColourTrans
will use new list generating algorithms, together with facilities for
exporting the resultant tables and providing bulk colour matches with a
single call.
With 16bpp and 32bpp modes the palette is to be considered fixed, and should
be changed only for gamma correction.
5 User Interface
################
5.1 Mode Chooser & Palette utility
==================================
The Palette utility will NOT be included in the OS image produced by Medusa.
Mode change facilties will be provided by the Mode Chooser. It will be
possible to 'softload' the palette utility, but no additional work will be
undertaken on the module for Medusa.
The Mode Chooser will be a new application, which will replace all screen
mode related code in the Palette utility.
The objective is to make the choice of screen mode comprehensible by
ordinary users - the mode number scheme is difficult for people to use
because there are many arbitrary numbers to remember with no obvious
relationship between the magnitude of the number and the screen display that
it produces.
Screen modes will be described in terms of the number of colours
provided and the resolution of the screen. The latter may be suffixed
with 'point-of-sale'/'tick-in-the-box' terms such as 'VGA', 'SVGA'
etc. This is a deliberate move away from providing nearly fifty different
screen modes and then trying to find an easy way to present all of them to
the user.
Clicking SELECT on the icon bar icon brings up the Screen Display window.
See diagram1 for a picture of the icon bar icon. See diagram2 for a picture
of the window.
In the Screen Display window the colours/resolution/frame rate fields will
be set to the current screen mode whenever the window is opened. The colours
menu will contain colours available. The resolution menu will contain the
resolutions possible. The frame rate menu lists the possible frame rates for
the currently selected colours and resolution and is useful in DRAM only
systems where it may be necessary to select a lower frame rate to regain
some bandwidth.
The colours menu is as follows:
+--------------+
| Colours |
+--------------+
| Black/white |
| 4 greys |
| 16 greys |
| 16 colours |
| 256 greys |
| 256 colours |
| 32 thousand |
| 16 million |
+--------------+
(256 colours represents a screen mode where the kernel imposes VIDC1
rules on the relationships between palette entries)
The resolution menu will be constructed by enumerating the available screen
modes using the new OS_ScreenMode SWI (see specification 0197,290/FS). The
modes returned by the enumeration call will be sorted and grouped into
classes where each mode in a class has the same resolution. The modes will
be sorted on lowest X resolution then on lowest Y resolution then on lowest
pixel depth and finally on highest pixel rate. The mode name of the first
mode in each class will be used as the menu text in the resolution menu.
The resolution menu will therefore be similar to the following:
+-------------------+
| Resolution |
+-------------------+
| 640 x 256 |
| 640 x 480 (VGA) |
| 800 x 600 (SVGA) |
| 896 x 352 |
| 1280 x 480 |
| 1600 x 600 |
| 1024 x 768 (XGA) |
+-------------------+
None of the entries will be greyed, even though it may not be possible to
display that combination of colour and resolution. What happens when a
choice which is not feasible is made depends upon which menu the most recent
selection was made in.
Working upon the premise that the most recent choice is the most important
to the user it will take the following action:
If a resolution was chosen: the currently selected number of colours will be
used if possible, otherwise the number of colours will be reduced until the
resolution chosen becomes possible. 256 colours will step down to 16
colours. 256 greys will step down to 16 greys.
If a colour setting was chosen: the currently selected resolution will be
used if possible, otherwise the resolution will be reduced until the number
of colours chosen becomes possible.
If either colours or resolution is stepped down as far as possible and no
alternative screen mode is found then the Mode Chooser will then try to
step up to find a valid mode. If a valid mode is still not found then the
following error will be generated:
'That combination is not supported'
When a new colour or resolution selection is made the frame rate field
will be filled in with the highest frame rate available for that
combination of pixel depth and resolution.
It may still not be possible to actually change into the screen mode due to
memory constraints. The Mode Chooser will attept to change to the selected
screen mode by using *WimpMode (see below for the command format). Any error
returned by this command will be displayed by the Mode Chooser. For example,
if there is not enough memory then one of the following errors may be
generated:
'There is not enough memory fitted'
or
'Not enough free memory - nnnK of memory is required for this screen mode'
Clicking Cancel closes the window, and discards the settings chosen by the
user (when Select is next clicked on the icon bar the settings will be
reset to the current mode, so performing the discard).
Clicking OK changes to the screen mode defined by the colour and resolution
choice or produces an error message explaining why it cannot do so.
There is an iconbar menu which allows the screen mode to be changed by
number. The menu has these choices:
+---------------+
| Screen |
+---------------+
| Info > |
| Screen Mode > |
-----------------
Info leads off to a standard information window.
Screen mode leads off to a dbox which allows other screen modes to be
accessed. It consists of a writable icon and an OK icon as illustrated
below:
+---------------------------------+
| Screen Mode |
+---------------------------------+
| +---------------------+ +----+ |
| | | | OK | |
| +---------------------+ +----+ |
+---------------------------------+
The intended purpose of the writable icon is to allow screen modes to be
chosen by the deprecated method of entering a mode number. However, it will
also allow access to screen modes not selectable by the fixed choice of
colours and resolutions available in the chooser. The latter will be
achieved by a combination of the following:
(Spaces/commas are ignored and may be introduced for clarity, all letters
are case-insignificant)
Xnnnn : X resolution (nnnn is three or four digits)
Ynnnn : Y resolution (nnnn is three or four digits)
Cccc : Colours (ccc = 2, 16, 64, 256, 32T, 32K, 16M)
Gccc : Greys (ggg = 16, 256)
EXn : X EIG factor (n = 0-4, smaller values make text larger)
EYn : Y EIG factor (n = 0-4, smaller values make text larger)
Ffff : frame rate (Hz) (fff is two or three digits)
So some examples of the syntax would be (with spaces shown to aid
clarity):
'X640 Y512 C16' (mode 20)
'X640 Y480 C16 EX0 EY0' (mode 27 with extra-large text)
'X320,Y480,C64' (VIDC 1 style 8bpp, VGA with rect. pixels)
'15' (mode 15)
Specifying both G and C is an error. F is optional, and, if left out will
cause -1 to be filled into the mode specifier.
Clicking on OK will cause the screen mode to be selected, or an error to be
generated.
Whenever this dbox is opened it will be set to the current screen mode (in
either mode number or mode selector form (the X/Y/C/G syntax detailed
above).
Implementation notes: when selecting 256 greys it must include a mode
variable pair to override the default ncol of 63 to 255 instead.
The string entered above will be in the same format as that accepted by
*WimpMode, and will be passed straight down to it.
The Mode Chooser will only change modes using *WimpMode ie. a mode selection
string will be constructed when the user clicks on OK in the Screen Display
window which will be passed to *WimpMode using SWI OS_CLI. All palette
bashing eg. for grey modes, will be done by the Wimp as the result of a
*WimpMode command.
5.2 Draw
========
The only work necessary on !Draw will be the plumbing in of the new Colour
Picker. The nature of this work will become clear when the Colour Picker FS
is issued.
5.3 Paint
=========
Paint will NOT be extended to work fully with the new 16 and 32bpp
modes.
It will load all sprite files and present the browser as now. Sprites of
8bpp or below with either type of sprite header may be edited.
If a 16/32bpp sprite (which must therefore be new format) is double clicked
an error will be produced '!Paint cannot edit this sprite'.
However, Paint will retain its ability to produce sprites of specific screen
areas in any screen mode even though it may not be able to edit them
afterwards. This will involve saving new format sprites for 16 and 32bpp
screen modes and old format sprites for 8bpp and below.
!Paint will also need to have the new Colour Picker plumbed in for the Edit
Palette dialogue. The nature of this work will become clear when the Colour
Picker FS is issued. The existing colour grid used for choosing sprite
colours will not alter.
6 Programmer Interface
######################
6.1 OS_SetColour & Colour Selection
===================================
A new flag has been added to extend the call to set the text colour.
When R0 bit 6 is set R1 is the colour number to use for text.
This has been added to provide a way to avoid existing byte-wide interfaces.
Another new flag will be added to OS_SetColour to permit the colour setting
to be read for restoration later. This will be used by the font manager
which currently uses OS_ReadVduVariables and GCOL VDU streams to do the same
job. As noted before GCOLs cannot perform the job properly in 16- and 32-bpp
modes.
The full definition of OS_SetColour becomes:
In
r0 = flags:
bit meaning
0-3 logical operation
4 fg/bg flag
5 colour number/pattern block flag:
0 - colour number
1 - pattern block
6 text/graphics colour:
0 - graphics colour
1 - text colour
7 read/set:
0 - set colour
1 - read colour
8-31 reserved - set to 0
r1 = colour number or pointer to pattern block
Out
set:
all registers preserved
read:
r0 = flags
r1 = colour number or pointer to pattern block
When setting the colour all the flags are used. When reading the colour only
the fg/bg flag and the text colour flag is used. A pattern block must be
supplied for reading as this will be filled in with the ECF if necessary.
The values returned by reading the colour are ready for passing straight to
OS_SetColour to set the colour back.
Implementation note:
Reading returns the following:
Graphics colour wanted:
r0 returns:
bit meaning
0-3 logical operation
4 preserved (fg/bg flag)
5 1 (pattern block flag)
6 0 (text/graphics flag)
7 0 (read/write flag)
8-31 preserved
r1 unchanged, pattern block filled in
Text colour wanted:
r0 returns:
bit meaning
0-3 logical operation
4 preserved (fg/bg flag)
5 0 (pattern block flag)
6 1 (text/graphics flag)
7 0 (read/write flag)
8-31 preserved
r1 = colour number
The following changes were made to ColourTrans for the version included in
RISC OS 3.10 which are relevant to colour choice in Medusa:
* ColourTrans_SetColour and ColourTrans_SetOppTextColour were introduced.
* ColourTrans_SetColour can be used to set text or graphics colours.
Since the RISC OS 3.10 release ColourTrans has been changed to use
OS_SetColour to implement the above calls.
6.2 ColourTrans
===============
6.2.1 ColourTrans_SelectTable
-----------------------------
ColourTrans_SelectTable needs careful extension for the new 16bpp and
32bpp modes because colours would normally be returned as words rather
than bytes (which would naturally upset anything expecting bytes).
This restricts the range of colours returned, but avoids breaking
applications by returning four times more data than is expected (which is
important to preserve mode independence).
The table size which would be generated by an application attempting to map
down from a 16 or 32bpp to a 1-8bpp mode would be excessively large, so
ColourTrans will not return full translation tables in these cases.
To summarise, the revised ColourTrans_SelectTable functionality will
be:
Source Mode..............................
1/2/4/8bpp | 16/32bpp
Dest. Mode |
|
1/2/4/8bpp 1 | 2
--------------------------+---------------------------
16/32bpp 3 | 4
Key:
1: Existing capability of ColourTrans. A new matching algorithm will be
used.
2: Returns a structure including a pointer to a 32768 byte table mapping
from 5 bits per primary colour to a colour number in the destination screen
mode. When the table is first calculated the call may take a few seconds to
return. This table is only valid until the next palette change, mode change,
or switch output to screen/sprite. The structure is:
0 Word = &33324B2E ('32K.')
4 Pointer to table
8 Word = &33324B2E ('32K.')
The guard words either side of the pointer are included to allow
SpriteExtend to check whether the translation table passed to it is of this
form, or is a direct look up table.
3: This will return a byte, representing a colour. This behaviour has been
chosen to provide a safe route for those applications which assume that the
size of the table will always be the number of bytes that there are colours
in the source mode. A new flag (bit 4 of R5) will instruct the call to
return words rather than bytes (indicating that the caller is aware that the
colours/bytes relationship no longer holds true).
4: No look up table will be generated. When plotting between these bpps bit
stretching/packing only will be performed.
6.2.2 Passing Mode Selectors to ColourTrans
-------------------------------------------
Where ColourTrans can be passed a mode number it will be modified to accept
a mode selector. The latter will have bit0 or its flags word set, so it can
be distinguished from a sprite area because the first word of a sprite area
is the size of the area - which must be word aligned, so b0 will always be
0.
6.3 Backwards Compatibility with GCOL Numbers
=============================================
In 16 and 32 bpp modes 8 bit GCOL assignments made via VDU 17/18 will work
as if you were in an 8bpp mode. ColourTrans GCOL calls such as ReturnGCOL
and SetGCOL will accept a word value for 16/32bpp.
6.4 Selecting Modes from Software
=================================
This section is dependant upon the mode picker API.
6.5 Compatibility
=================
The following compatibility issues will arise:
6.5.1 VDU 22
------------
Using VDU 22 to select a screen mode will not allow all new
screen modes to be chosen. It is deprecated henceforth. The new
facilities in the Mode Picker API should be used instead.
However all existing screen modes will still be attainable.
6.5.2 VDU 17/18
---------------
VDU 17/18 will continue to work as before, however it is of limited
usefulness in 16/32bpp modes, since colours may now be words rather than
bytes. Usage of VDU 17/18 is deprecated henceforth. In 256 or lower colour
modes it will continue to work as before. SYS "OS_SetColour" should be used
instead (the colour number to be used can be found by using
ColourTrans_ReturnColourNumber).
6.5.3 8 bits of colour component
--------------------------------
All 8 bits of a colour component are now significant. Do not work in four
bit quantities and copy the other four from the significant four or set them
to zero. Such techniques will only allow access to sixteen of the possible
256 intensities.
6.5.4 ColourTrans matching
--------------------------
As the table above indicates, there is no longer the relationship where the
size of the table returned in bytes is equal to the number of colours in the
source mode. Facilities already exist for determining the size of the table
before requesting it, and these should be used.
6.5.5 Altering the palette
--------------------------
In 16 and 32bpp modes the palette should only be altered for gamma
matching only. Thus VDU 19 should not be used in these modes. Further,
it is no longer necessary to duplicate nibbles - all 8 bits of the
colour component are significant.
6.5.6 8bbp VIDC1 model
----------------------
The existing model of 64 colours and 4 tints is retained in 256
colour modes with the default palette. This may alter with the Mode Choice
API.
6.5.7 OS_Word 9
---------------
Use of OS_Word 9 to read the pixel logical colour is deprecated
since it only returns a byte.
6.5.8 OS_Word 11
----------------
ColourTrans_ReadPalette should be used in preference to OS_Word 11.
6.5.9 OS_Word 12
----------------
ColourTrans_WritePalette should be used in preference to OS_Word
12. Note: Both the ColourTrans calls deal with the whole palette, so the
whole palette must be read, modified, and written back. The bottom byte of
the palette entry is defined to be the supremacy bits. All 8 bits are
reserved, but at present only 4 are used in 32bpp and 1 in other bpp.
6.5.10 NCOL
-----------
NCOL=63 will be returned by default for all 8bpp screen modes. If the Mode
Choice API permits it 63 will be returned for VIDC1-like 8bpp modes and 255
for non VIDC1-like 8bpp modes.
6.5.11 VDU 23,17,0-3 Set Tint
-----------------------------
This will work for both 8bpp NCOL=63 and 8bpp NCOL=255 modes. However it is
of relatively little use in an NCOL=255 8bpp mode.
6.6 Modeflags
=============
Modeflags bit 7 will be set when a 8bpp mode without VIDC1 palette behaviour
is being used.
Note: ColourTrans_ReadPaletteType provides a more packaged result, and
should be used in preference to this facility.
6.7 Support for the new sprite format
=====================================
Important note: This is a different proposal to the 'New Sprite Format' put
forward last year.
Refer to section 7.1 for details of the new format.
The sprite mode word is now termed the sprite type, and has these fields:
Bit Meaning
27-31 T
When T is zero:
00-26 Mode number sprite was defined in
When T is non-zero:
0 1 (distinguishes it as a sprite type rather than a mode
selector to OS_ReadModeVariable)
1-13 Hdpi
14-26 Vdpi
Supported functions:
T=0 everything.
T=1-6 SpriteOps assume mask+palette will not be present. IE if a sprite with
a mask or palette is presented the SpriteOps' action will be to fault the
operation. In future a new mask format will be introduced consisting of one
bit of mask per pixel of sprite, and a new palette format will be introduced
consisting of three 256 byte tables (ie palette entries for each gun). Note
that in Medusa mask/palette presence is not supported and will be faulted.
Left-hand wastage is not supported, so will never be present.
T=7-31 - not supported, and will be faulted.
The following work is required in the kernel for this:
Cope with translating type word into useful information.
Fault mask/palette use on T=1-6 sprites.
The SpriteOps will support the following sprite types: (a - indicates that the
sprite type is not relevant).
SpriteOp Use T=
2 screen save 0,1-6 with no palette/mask
3 screen load 0,1-6 with no palette/mask
8 Read area control block -
9 Init sprite area -
10 load sprite file -
11 merge sprite file -
12 save sprite file -
13 return name 0-6
14 get sprite 0,5,6 (1-4 will be forced to 0)
15 create sprite 0,5,6 (1-4 will be forced to 0)
16 get sprite user coords 0,5,6 (1-4 will be forced to 0)
24 select sprite -
25 delete sprite -
26 rename -
27 copy sprite -
28 put sprite 0,1-6 no mask/palette only
29 create mask 0,1-6 no mask/palette only
30 remove mask 0,1-6 no mask/palette only
31 insert row 0,1-6 no mask/palette only
32 delete row 0,1-6 no mask/palette only
33 x-axis flip 0,1-6 no mask/palette only
34 put sprite user coords 0,1-6 no mask/palette only
35 append sprite 0,1-6 no mask/palette only
36 set pointer shape 0-4
37 create/remove palette 0-6 (can only create for T=0)
40 read sprite info 0-6
41 read pixel colour 0
42 write pixel colour 0
43 read pixel mask 0
44 write pixel mask 0
45 insert column 0,1-6 no mask/palette only
46 delete column 0,1-6 no mask/palette only
47 Y-axis flip 0,1-6 no mask/palette only
48 plot mask 0,1-6 no mask/palette only
49 plot mask user coords 0,1-6 no mask/palette only
50 plot mask scaled 0,1-6 no mask/palette only
51 paint char scaled -
52 put sprite scaled 0,1-6 no mask/palette only
53 put sprite grey scaled 0, with given restrictions
54 remove LH wastage 0,1-6 no mask/palette only
55 plot mask transformed 0,1-6 no mask/palette only
56 put sprite transformed 0,1-6 no mask/palette only
57 insert/delete rows 0,1-6 no mask/palette only
58 insert/delete columns 0,1-6 no mask/palette only
60 switch out to sprite 0,1-6 no mask/palette only
61 switch out to mask 0,1-6 no mask/palette only
62 read save area size -
Values returned for relevant variable numbers are shown below:
3 NColour
T Ret
1 1
2 3
3 15
4 255
5 65535
6 2^32-1
4 XEIG
5 YEIG
ppi EIG
45 2
90 1
180 0
9 Log2bpp
10 Log2bpc
T Log2bpp/Log2bpc bpp=bpc=
1 0 1
2 1 2
3 2 4
4 3 8
5 4 16
6 5 32
6.8 New ColourTrans colour matching facilities
==============================================
A new colour matching algorithm will be implemented in ColourTrans to
allow it to cope better with the much higher number of colour matches needed
by 8bpp modes with independent palette entries.
The new matching algorithm is based on the technique of maintaining a table
of matches within subcubes of the whole colour cube. This speeds colour
matching by reducing the number of colours which need to be tested since a
list of close matches is already available after the first call to provide a
match within that subcube. As well as being exportable to clients like
ChangeFSI or the Colour Picker it will also be used internally within
ColourTrans.
The output of the algorithm is available as a 32K table containing colour
matches for 5bits each of Red, Green and Blue (ie suited for 16 or 32bpp
mapping down to 8bpp or below).
The table will not be generated until it is needed, and is expected to take
under 2 seconds to generate. In some regularly used cases a precalculated
table will be included in the ROM (the two top contenders being 16/32 ->
8bpp and 16/32bpp -> 8bpp greyscale assuming default 8bpp palette in each
case).
The address of the current table will be exported through
ColourTrans_SelectTable and ColourTrans_GenerateTable whenever mapping from
16/32bpp down to 8bpp or below. The table will remain valid until the next
palette change, mode change, or switch output to sprite/screen.
Note that the call will only generate the table when a new table needs to be
built, so when an application is in doubt whether the current table is
correct it should call ColourTrans again. The call will either return
immediately because the table is still correct or it will build/point at the
right table and return. ColourTrans will have access to at least one
calculated table, and one (maybe two) in ROM. If it becomes clear that
ColourTrans is recalculating tables more often than it can return a table
already calculated (whether in RMA or ROM) an investigation will be made
into enabling ColourTrans to cache a number of calculated tables. Although
this will solve the speed problem it will carry a 32K memory penalty per
table (the memory structure used to create the 32K table does not need to be
retained).
ColourTrans will determine for itself whether a 256 grey level palette is in
use by checking the returned palette entries (ie for entry i, each colour
should be i). This will allow ColourTrans to apply optimised matching
routines for the grey palette by weighting each colour.
When an old format sprite with a full palette (ie 256 pairs of entries for
an 8bpp sprite) is plotted in 16 or 32bpp SpriteExtend will ignore any
translation table provided and will instead use the RGB values contained in
the palette to plot the sprite.
6.9 PaletteV
============
Enhancements to PaletteV to allow block read and write of the palette.
Reason code 7 : Read palette entries
------------------------------------
Parameters in:
R0-> list of logical colours (words) or 0
R1 = bit31-bit24 : colour type (16,17,18,24 or 25)
bit23-bit00 : number of colours
R2-> pointer to memory for first flash state colours
R3-> pointer to memory for second flash state colours or 0
R4 = 7 Read palette entries
All pointers should be word aligned.
Parameters out:
R4=0 if successful
The memory pointed at by R2 and R3 will be filled with words giving
the device colour for each flash state.
If R0 is 0 on entry and the colour type is 16, 17 or 18 the call will
return the number of palette entries requested starting from the first
logical colour - this allows a number of consecutive colours to be read
without needing to set up a list.
If the colour type is 16 (read both flash states) and R3 is 0, the area
pointed at by R2 will be used for both flash states (in the order first
state, second state, first state, etc).
R0-R3 preserved
Reason code 8 : Write palette entries
-------------------------------------
Parameters in:
R0-> list of logical colours (words) or 0
R1 = bit31-bit24 : colour type (16,17,18,24 or 25)
bit23-bit00 : number of colours
R2-> list of device colours (words)
R4=8 Write palette entries
All pointers should be word aligned
Parameters out:
R4=0
Notes:
If R0=0 and the colour type is 16, 17 or 18 on entry the number of palette
entries specified by R1 will be written consecutively starting from the
first logical colour.
When the colour type is 16 the device colour entries pointed at by R2 should
be in the order first state, second state, first state etc.
The correct behaviour for a PaletteV claimant in Medusa is to return all
calls, but only set R4 to 0 for those it knows. This avoids problems with
different PaletteV claimants processing some reason codes and passing on
others that it doesn't undertand.
ColourTrans (and other users of these new reason codes) will be written to
try the new reason codes first and then fall back to using reason codes 1
(read) and 2 (write). Should these also fail it will fall back again to
using OS_ReadPalette/VDU19 (this is the current behaviour of ColourTrans).
6.10 Use new PaletteV reason codes in ColourTrans
=================================================
Install use of new PaletteV reasons in ColourTrans_ReadPalette and
ColourTrans_WritePalette.
See details above.
6.11 Programming the Supremacy bit(s)
=====================================
VIDC 1 only provided one supremacy bit. With VIDC20 there are four bits of
supremacy in 32bpp screen modes.
The recommended method of programming this will be to use
ColourTrans_ReadPalette and ColourTrans_WritePalette. The palette entry
passed through these calls will be in the form &bbggrrs0.
s will be the supremacy mask nibble. Where there is only one bit of
supremacy it will appear in bit 7. Where there are four bits they will
appear in bits 7-4. ColourTrans and the kernel will be changed to support
this (at present the kernel only expects one bit of supremacy and ignores
the rest).
7 Data Formats
##############
7.1 New sprite format
=====================
Important note: This is a different proposal to the 'New Sprite Format' put
forward last year.
The new sprite format has been defined to avoid the problems caused by
binding sprite files to a mode number not available on the viewing
machine (typically where a sprite has been created in a soft-loaded
screen mode).
Old header:
Word Meaning
1 Offset to next sprite
2-4 Name
5 Width in word-1
6 Height in lines-1
7 1st bit used (left end of row)
8 last bit used (right end of row)
9 Offset to sprite image
10 Offset to mask/image
11 Sprite's mode
12... Palette data (if present)
New header: (difference indicated by ***)
Word Meaning
1 Offset to next sprite
2-4 Name
5 Width in word-1
6 Height in lines-1
*** 7 0 (Reserved for future use)
8 last bit used (right end of row)
9 Offset to sprite image
10 Offset to mask/image
*** 11 Sprite's type
12... Palette data (if present)
Note that, by definition, there is no left hand wastage.
The sprite type is controlled by the Type field:
Bit Meaning
27-31 T
When the Type is zero, it is an old format mode word, so:
00-26 Mode number (b00-b06 are significant)
When the Type is non-zero:
Bit Meaning
00 1 (required to distinguish this as a sprite type rather
than a mode selector to OS_ReadModeVariable)
01-13 Hdpi
14-26 Vdpi
T meaning
0 This is an old format mode word. The mode is in bits 0-6.
1 1bpp pixels. Palette/Mask faulted if present. This leaves room in
the specification for more efficient palettes and packed masks.
Vdpi and Hdpi are the vertical and horizontal dots per inch of the
sprite. Only 90x90 and 90x45 will initially be supported, these
corresponding to square and rectangular pixels.
2 As T=1, but 2bpp
3 As T=1, but 4bpp
4 As T=1, but 8bpp.
5 As T=1, but 16bpp.
6 As T=1, but 32bpp.
7-31 For future expansion. Ideas have been 24 bpp and CMYK formats.
Notes on Pixel depth/data table values:
0 - gives old format without changes. This is the only format in which an
attached palette and/or mask will be supported. For values of T which are
greater than 0 the mask and palette will be a new format, which is not
implemented by this FS.
Pixels storage for 16/32bpp is:
16bpp
bit use
0-4 Red
5-9 Green
10-14 Blue
15 Reserved (set to 0)
32bpp
bit use
0-7 red
8-15 green
16-23 blue
24-31 Reserved (set to 0)
7-31 - reserved for future use.
When a new format sprite is forced back to a mode number the following logic
will apply:
X dpi Y dpi Screen mode: 1bpp 2bpp 4bpp 8bpp
----- ----- ------------ ---- ---- ---- ----
90 45 0 8 12 15
45 45 4 1 9 13
90 90 18 19 20 21
Notes:
1: 16bpp and 32bpp sprites will always only be in the new format.
2: These mode number choices are extracted from p2-263 of the draft RO3 PRM.
8 Protocols
###########
No new protocols introduced.
9 External Dependencies
#######################
VIDC20.
Systems with varying amounts of VRAM for testing performance.
(Note: the latter could entail one system with maximum VRAM, and temporary
changes in the soft-loaded OS to ignore some or all of it)
10 Development Test Strategy
############################
Tests during coding will take the form of:
a) SWI level comparisons
b) Performance assessment
c) Stress testing
Where such tests are of lasting usefulness they will be created/
documented to enable future use during the Audit phase of development.
10.1 SWI level comparisons
--------------------------
Each individual SWI call will be tested with each possible
combination of parameters, where possible, or a large number of
combinations where not. Comparisons will be made between the results
obtained from modified code and original code in RISC OS 3.10 where existing
facilities are being routed through new or changed code. New facilities
which cannot be tested comparatively will be tested using predicted results
to verify that the expected behaviour happens.
The SWI test harness will be used for this method of testing wherever
possible. This will result in scripts which may easily be used in future, or
run intensively for 'bashing' purposes.
Where the SWI test harness proves unsuitable specific programs will be
written. These will be written and documented in a manner which makes them
suitable for future use.
10.2 Performance Assessment
---------------------------
A number of routines are being written or altered which will have a direct
effect on the perceived speed and responsiveness of the system.
Where these routines are comparable with RISC OS 3.10 they will be tested to
conform to the comparitive criteria in the Project Specification.
10.3 Stress Testing Programs
----------------------------
These will be variants of the test programs outlined above which will trial
routines in an intensive manner to provide assurance that performance under
worst case or invalid scenarios is acceptable.
10.4 Application of test methods
--------------------------------
Each video SWI affected by this Functional Spec (see below for list) will be
tested with various option combinations. Where the number of permutations is
small all permutations will be tested. When the number of permutations grows
too large to cover every possible permutation specific attention will be
given to:
* Often used combinations
* Stressful combinations
* Invalid combinations
The definitions of the above terms in relation to a specific SWI will be
determined by the developer concerned.
All video SWIs will be tested with parameters groups which are:
* Wildly invalid
* Just invalid
* Just valid
* In the middle of valid range
Where there is no invalid range stressful situations will be used instead.
10.5 SWIs directly affected by the work in this FS
--------------------------------------------------
OS_Byte 135 (Return screen mode)
OS_Byte 144 (Set interlace and vertical position)
OS_Byte 160 (Read VDU variable)
OS_Word 9 (Read pixel logical colour)
OS_Word 11 (Read palette)
OS_Word 12 (Write palette)
OS_WriteC (control code/sprite handling)
(and derivatives OS_WriteS, OS_WriteN etc)
OS_SpriteOp (all reason codes)
OS_ReadPalette
OS_ReadVduVariables
OS_ReadModeVariable
OS_CheckModeValid
OS_SetColour
Font_Paint (will be affected by ColourTrans work)
Font_SetFontColours (will be affected by ColourTrans work)
Wimp_SetFontColours (as for Font_SetFontColours)
Wimp_SetColour
ColourTrans: all calls will be tested (there is also new
calibration code awaiting test).
11 Organisation
###############
All items discussed here are in ROM.
12 Future Enhancements
######################
12.1 Reducing the size of the kernel and duplicity of sprite code
=================================================================
Splitting out gfx from the kernel. Merging similar code in the kernel and
SpriteExtend.
12.2 Comprehensive mode editor
==============================
Comprehensive mode editor - one for the apps discs or a third party, using
the new mode choice API to the full.
12.3 Adaptive mode chooser
==========================
Dynamic resolutions menu which tunes itself to the available monitor/machine
capabilities. Ideas include intelligent interaction with the kernel to
choose the list, and limiting the list to a small number of entries (eight?)
to avoid overloading the user with a plethora of choices (and to avoid
having to support N (where N is large) different screen modes).
12.4 Enhanced Colour Picker
===========================
Full Colour Picker, with colour choice saving and named colours.
12.5 Monitor description file
=============================
Create a file format which defines the actual properties of a monitor within
its monitortype. The file could also be used for gamma correction
information for the monitor in the future.
12.6 New sprite routines to overhaul the present situation
==========================================================
This would remove the present situation where some sprite plotting is
handled in the kernel and the other by one of two routines in SpriteExtend.
12.7 A more ambitious revamp of the sprite files
================================================
Proposals for this have already been generated.