Copyright M-) Acorn Computers Ltd. 1993 0197,290/FS Issue E **Live** Medusa Screen Mode Selection API Functional Specification ========================================================= ----------------------------------------- | Drawing No : 0197,290/FS | | Issue : D **Live** | | Date : 7th April 1993 | | Author : Tim Dobson | | Sheets : | | Last Issue: D | ----------------------------------------- Contents -------- 1 History 2 Outstanding issues 3 Overview 4 Technical Background 4 1/2 User Interface 5 Programmer Interface 5.1 New SWIs 5.1.1 OS_ScreenMode 5.2 Extensions to existing SWIs and commands 5.2.1 OS_ReadModeVariable 5.2.2 OS_CheckModeValid 5.2.3 OS_Byte (&87) 5.2.4 ColourTrans SWIs 5.2.5 Wimp_SetMode 5.2.6 *WimpMode 5.3 Extensions to Service_ModeExtension 5.4 Extensions to Service_ModeTranslation 5.5 New service call Service_EnumerateScreenModes 5.6 New module: ScreenModes 5.6.1 Overview 5.6.2 *LoadModeFile 5.6.3 MonitorType 7 (File) 5.7 Changes due to hardware differences on Medusa platforms 5.7.1 Monitor lead ID 5.8 Grey-scale modes 5.9 Gamma correction 5.10 External video cards 6 Data formats 6.1 File format for filetype ModeInfo 7 Development Test Strategy 8 Future enhancements Appendix A (in separate file) Screen mode timings 1. History ========== TMD 11-Feb-93 Started Issue A TMD 24-Feb-93 Released for initial review --------------------------------------------------------------------------- Issue B TMD 26-Feb-93 Updated with comments from JRoach, AGlover, CWhyte, MChallis --------------------------------------------------------------------------- Issue C TMD 07-Apr-93 Issue about SWI number for OS_ScreenMode removed - spec now says it will be allocated later. Description of mode selector flags modified and expanded. Description of extensions to Service_ModeExtension expanded. Clarified that VIDC lists type 0 and 1 are not supported (ie existing mode extend modules will not work). Removed remaining references to Jordan. Description of mode selector flags and mode provider flags expanded. Format of block returned from screen mode enumeration service and SWI has been changed to include size field. Section added about default values of mode variables. Section added about grey scales. Section added about gamma correction. Section added about external video cards. Appendix A containing screen mode timings added. Mode selector format changed to include desired frame rate, as is enumeration block format. Default monitor type for monitor ID 0 changed to 3 (VGA) (was 4 (SVGA)). DAC control bit added to video control parameters list (and entries renumbered). Extensions to Service_ModeTranslation added. Section on new monitor types removed. Section on ScreenModes module added. Section on filetype "ModeInfo" format added. Screen mode is now always returned in the format it was selected. New OS_ScreenMode reason code added to select current monitortype. Section added on changes to ColourTrans SWIs. Section added on changes to Wimp_SetMode. Section added on changes to *WimpMode. Service_ModeExtension and Service_EnumerateScreenModes changed to include passing in of total video memory size, and registers for OS_ScreenMode(2) updated to keep in step. --------------------------------------------------------------------------- Issue C TMD 07-Apr-93 Add mode name to ModeInfo file and corresponding field in Service_EnumerateScreenModes records. Extend test strategy to match changes in issue C Add section on !Configure changes - sorts out last two outstanding issues --------------------------------------------------------------------------- Issue D JSR 23-Apr-93 Final tidying up for AMR: Notes on how to select shadow screens --------------------------------------------------------------------------- Issue E JSR 26-May-93 Input from implementation: OS_ScreenMode SWI number is &65 Frame rate in mode specified may be given as -1 to allow a first match scheme Modification to Service_EnumerateScreenModes to allow partial enumeration of screen modes Correction to OS_ScreenMode reason 3 --------------------------------------------------------------------------- 2. Outstanding issues ===================== 3. Overview =========== In RISC OS 2 and 3, screen modes are selected by sending the VDU sequence (22, n) where n is the screen mode number. Since this interface is a byte wide interface, n is limited to 8 bits. Since bit 7 is interpreted as a "shadow mode" indicator, there are only in fact 128 different screen modes available by this interface. Of these 64 are allocated to Acorn, the others being available for third parties or the user. This creates a problem for the Medusa version of RISC OS, as VIDC20 supports higher resolution screen modes, and a wider selection of pixel depths (ie 16- and 32-bit per pixel modes). If all the resolutions we wish to support on Medusa were represented by one new mode number for each available pixel depth, the number of screen modes would exceed 64 (RISC OS 3.1 already uses modes 0 to 46). Therefore a new way of selecting modes is provided. In addition, the RISC OS mode extension system needs to be modified. In RISC OS 2 and 3, modules which provide extra screen modes currently respond to services, returning lists which contain values to be programmed into VIDC1. Since VIDC20 is capable of generating screen modes which VIDC1 cannot, a new list format is necessary to take advantage of these capabilities. Due to resourcing constraints, the code to support old-style formats will not be written for Medusa. Because the range of line frequencies available on monitors varies so widely, it has been decided that rather than create a plethora of new monitortype numbers to cope with this, a new ScreenModes module will be created, which reads the timings for the full set of screen modes from a file on the hard disc. A new file format has been defined for this. 4. Technical background ======================= A "mode selector" is a word-aligned structure of the following format:- Offset Value 0 mode selector flags bit 0 = 1 (always) bits 7..1 = format specifier (zero for this format) bits 31..8 = other flags (must be zero currently) 4 x-resolution (in pixels) 8 y-resolution (in pixels) 12 pixel depth (0=1bpp,1=2bpp,2=4bpp,3=8bpp,4=16bpp,5=32bpp) 16 frame rate (in Hz) (-1 means 'use first match') 20 pairs of words (mode variable index, value) (there may be any number of these, including zero) n -1 (terminator) (The mode variable indexes mentioned here are the same numbers which specify mode variables in SWI OS_ReadModeVariable). A "mode specifier" is either a mode number (in the range 0..255) or a pointer to a mode selector (>255). The range of the value determines which. 4 1/2. User Interface ===================== The user interface described here is that of the Screen dialogue of !Configure. Please find attached the file Templates which gives the replacement Screen dialogue. From top to bottom there are 5 fields: Monitor type: this selects the type of the monitor attached to the computer. Menuing here will bring up a menu with all the monitor types available listed on it. The menu will be: +-------------------------+ | Monitor type | +-------------------------+ | CGA (15kHz) | | Multiscan (15kHz-35kHz) | | VGA (31kHz) | | SVGA (31kHz-35kHz) | | SVGA (31kHz-48kHz) | | XGA (31kHz-64kHz) | | XGA (31kHz-78kHz) | | Auto | +-------------------------+ This being the list of ModeInfo files supplied in the directory !Configure.Monitors with Auto added to the end. The menu button to the right of this field will also bring up this menu. The configured monitor will be ticked, unless the configured monitor isn't one of the !Configure.Monitors files. Colours: and Resolution: select the mode in the same way as the mode selector does (see 0197,254/FS). If monitor Auto is selected then both these fields will come up 'Auto' - you won't be able to change them and the menus won't be available. Blank delay: This works in the same way as the RISC OS 3.1 Blank delay field in !Configure, except its action is only applied if either of Save or OK is applied. Vertical adjust: This is the same as the RISC OS 3.1 Vertical adjust field except that it isn't writeable and its effect is only applied if either of Save or OK is pressed. Below these fields are the following action buttons: Default: This causes machine default values to be filled in. The default values will match the factory shipped values. Save: This saves the settings such that when the machine restarts it comes up with the chosen values. Cancel: Left click - quit the box, no further action. Right click - fill in the values in force when the box was last openned/Saved/OKed. OK: Apply the values in the box, but don't save them. [ Implementation details: A predesktop Obey file should be constructed to action the saved values - this forms the saving of the values. *LoadModeFile should be used for the monitor type and *WimpMode for the mode. To avoid duplication of default setup !Configure should take a copy of the current configuration if it finds it hasn't already got a copy. The Monitors directory inside !Configure should contain the ModeInfo files without any special directory structuring. The file names should be chosen to give the desired menu ordering. ] 5. Programmer Interface ======================= 5.1 New SWIs ============ 5.1.1 OS_ScreenMode (&65) ------------------------- The SWI number for this call will be allocated at a later date, and the functional specification updated to reflect the allocation. This performs various actions relating to screen modes. On entry, r0 gives a reason code which determines which operation is performed. Reason code 0: Select screen mode On entry: r0 = 0 (reason code) r1 = mode specifier On exit: All registers preserved This selects the given screen mode. If a mode number 'n' is given, then the existing mechanisms are used to select this mode, exactly as if VDU 22,n were issued. If a pointer to a mode selector is given, then any mode variables which are not specified are given sensible defaults, based on the specified resolution and pixel depth. Note that the relevant information is copied away by RISC OS, so mode selector structures need not remain valid after the call has returned. If a pointer to a mode selector was given, but the specified mode cannot be selected for any reason, then an error is always returned. Note that this is different behaviour from mode selection by number, which can select a substitute mode in certain cases. The way that RISC OS works out the mode variables for a given screen mode is different when a mode selector is used: When given a mode number, if it is recognised by RISC OS then the mode variables for that mode are loaded from its internal tables; if it is not recognised then Service_ModeExtension is issued and the module which responds to this passes back a workspace list which contains a base mode (which must be known to RISC OS) and a list of changes to mode variables. When passed a pointer to a mode selector, however, the mode variables are initialised to defaults based on the information in the mode selector block, viz. the x and y resolutions and the pixel depth. Any mode variables specified in the mode selector block override these defaults. The default values for these mode variables are as follows: Variable Default value ModeFlags 0 ScrRCol (xres >> 3) -1 ScrBRow (yres >> 3) -1 NColour 1, 3, 15, 63, &FFFF, &FFFFFFFF for pixdepth = 0 to 5 respectively XEigFactor 1 YEigFactor 1 LineLength (xres << pixdepth) >> 3 ScreenSize ((xres*yres) << pixdepth) >> 3 YShftFactor 0 Log2BPP pixdepth Log2BPC pixdepth XWindLimit xres-1 YWindLimit yres-1 Service_ModeExtension still gets issued in the mode selector case, but only if RISC OS does not know the video timings for the resolutions/pixel depth/frame rate asked for, and in this case the module responding provides only timing and other hardware control information, and not any mode variable values. See section 5.3 below for further information on changes to Service_ModeExtension. Note that in the case where pixdepth=3, the default value of NColour is 63. This means that by default, the palette in 256-colour modes behaves as it does on VIDC1-based machines, ie palette entries get modified in groups of 16. This is so that programs which expect the old behaviour will work without modification in these modes. To gain access to fully-palette-programmable 256 colour modes, the following variables should be overridden with these values:- Variable Value ModeFlags 128 NColour 255 Under these conditions, all 256 palette entries become programmable, although the initial palette setting is identical. You might notice that there is no explicit way of selecting a shadow screen mode. In order to get this effect the program should ensure there is sufficient memory in the screen dynamic area before switching screen banks. If there is sufficient memory then switching banks will work without a hitch. Reason code 1: Return mode specifier for current screen mode. On entry: r0 = 1 (reason code) On exit: r1 = mode specifier If the screen mode was selected by mode number, then this call returns that number, otherwise it returns a pointer to a mode selector. Reason code 2: Enumerate screen modes. This call provides a front end to Service_EnumerateScreenModes. It fills in r3 (the current monitortype), r4 (the memory bandwidth available) and r5 (the total amount of video RAM), and then issues the service. See the section on Service_EnumerateScreenModes for more details. On entry: r0 = 2 (reason code) r2 = enumeration index r6 = pointer to block to return data into, or 0 to just count entries r7 = size of block if r6<>0, or zero if r6=0 On exit: r1 = 0 if service claimed, otherwise r1 non-zero. r2 = updated enumeration index r6 = updated block pointer r7 = size of remaining free area in block All other registers are preserved. Note: if r6=0 on entry to this SWI, then no data is returned, but r2 will have been updated to the number of entries that would have been returned, and r7 will have been decremented by the number of bytes that would have been put into the block, therefore -r7 is the size of block that will be needed to hold all the entries. Each entry stored is of the following format:- Offset Value 0 size of entry in bytes (24 for this format) 4 mode provider flags: bit 0 = 1 (always) bits 7..1 = mode info format specifier (zero for this format) bits 31..8 = additional mode info flags (must be zero) 8 x-resolution (in pixels) 12 y-resolution (in pixels) 16 pixel depth (as per mode selector) 20 frame rate (Hz) (to the nearest integer) In the future it is possible that different format entries may be returned by modules, therefore callers of this SWI should check that bits 7..0 of the mode provider flags contain 1 before extracting the other information in this block. If these bits contain a different value which is not recognised by the caller, then the entry should be skipped by adding on the size field at offset 0. For format checking purposes, bits 31..8 should be ignored. Reason code 3: Select current monitortype This call is provided for internal use by the ScreenModes module. It sets the current monitortype value, which is used by RISC OS when various services are issued. This call does NOT change the value configured in CMOS RAM. On entry: r0 = 3 (reason code) r1 = monitortype value to set, or -1 to restore to configured value On exit: All registers preserved Note that SWI OS_ReadSysInfo(1) now returns the current monitortype value, rather than the configured value. 5.2 Extensions to existing SWIs and commands -------------------------------------------- 5.2.1 OS_ReadModeVariable ------------------------- On RISC OS 3 this call is passed one of the following in r0: a) mode number, or b) -1, indicating current screen mode. For Medusa this has now been extended to one of the following: a) mode number, or b) pointer to mode selector, or c) new format sprite mode word, or d) -1, indicating current screen mode. Cases b) and c) are distinguishable because bit 0 of the new format sprite word is always set, whereas it must be clear in case b) because mode selectors always start on a word boundary. 5.2.2 OS_CheckModeValid ----------------------- This call now accepts any mode specifier in r0, not just a mode number. In addition, the returned substitute mode may be a pointer to a mode specifier. 5.2.3 OS_Byte(&87) (Read character under cursor, and screen mode) ----------------------------------------------------------------- This call will now return a pointer to a mode selector, if the current screen mode was selected that way. 5.2.4 ColourTrans SWIs ---------------------- The following SWIs:- ColourTrans_ReturnGCOLForMode ColourTrans_ReturnColourNumberForMode ColourTrans_ReturnOppGCOLForMode ColourTrans_ReturnOppColourNumberForMode previously took a mode number (or -1 for the current mode) as an input parameter. In all cases they now accept a general mode specifier, or -1. The following SWIs:- ColourTrans_SelectTable ColourTrans_SelectGCOLTable ColourTrans_ReadPalette ColourTrans_GenerateTable previously took a mode number, or -1 for the current mode, or a sprite area pointer. The sprite area pointer case was distinguished by the value being greater than or equal to 256 (since mode numbers are only byte quantities). In all cases they now accept a general mode specifier, or -1, or a sprite area pointer. This raises the issue of how a pointer to a mode selector is distinguished from a pointer to a sprite area. However, the first word of a sprite area contains the size of the sprite area, which must be a whole number of words, therefore bits 0 and 1 will be clear, whereas the first word of a mode selector is the flags word which always has bit 0 set, thus they are distinguishable. 5.2.5 Wimp_SetMode ------------------ This call previously took a mode number in r0 on input. It now accepts a general mode specifier. In the case of a pointer to a mode specifier, the WindowManager module makes a copy of the whole structure to use on future mode changes, not just a copy of the pointer. 5.2.6 *WimpMode --------------- This command now allows the mode to be specified either as a number, or in the form of a mode description string, which is a textual form of a mode selector. This is also reflected in the mode chooser application, which also allows this form. The format of this string is described in the Medusa Video Software Functional Specification (0197,254/FS) from issue 1.08 onwards. 5.3 Extensions to Service_ModeExtension --------------------------------------- When this service is issued on RISC OS 3, the registers are as follows:- On entry: r1 = Service_ModeExtension (&50) r2 = mode number r3 = monitor type (-1 for don't care) On exit: All registers preserved if not recognised, else r1 = 0 r2 is preserved r3 -> VIDC list (type 0 or 1) r4 -> workspace list On RISC OS for Medusa, the registers are as follows:- On entry: r1 = Service_ModeExtension (&50) r2 = mode specifier r3 = monitor type (-1 for don't care) r4 = memory bandwidth available (in bytes/second) r5 = total amount of video RAM in system (in bytes) On exit: All registers preserved if not recognised, else r1 = 0 r2 is preserved r3 -> VIDC list (type 3) r4 -> workspace list if a mode number was passed in, or r4 = 0 if a pointer to a mode selector was passed in Note that returning a workspace list is only relevant if a mode number is passed in - if a pointer to a mode selector is passed in, RISC OS can work out what the mode variables should be for that mode, therefore there is no need to return a workspace list, and r4 should be set to zero on exit. If a pointer to a mode selector is passed in, the module should check that bits 7..0 of the mode selector flags hold the value 1. If they hold a different value, this implies that the structure of the rest of the mode selector may be different, so the module should pass the service on, unless it recognises the new format. For format checking purposes bits 31..8 of the mode selector flags should be ignored, as these will only pass in extra information which may be of use to some modules. The mode selector could contain -1 as the frame rate, in which case the first matching mode should be used. RISC OS 3 supports two formats (types 0 and 1) of VIDC list (the first word of the list is the format type). Both these types include values which correspond directly to VIDC1's register formats. These formats are NOT supported on Medusa. This means that mode extend modules for RISC OS 2 and 3 WILL NOT WORK. A new format list (type 3) is available on Medusa RISC OS, which aims to be independent of the video controller used. The format is as follows:- Offset Value 0 3 (format of list) 4 pixel depth (0=1bpp,1=2bpp,2=4bpp,3=8bpp,4=16bpp,5=32bpp) 8 horizontal sync width (in pixels) 12 back porch 16 left border 20 display size 24 right border 28 front porch 32 vertical sync width (in rasters) 36 back porch 40 top border 44 display size 48 bottom border 52 front porch 56 pixel rate (in kHz) 60 sync polarities bit 0 set => Hsync inverted bit 1 set => Vsync inverted bits 2-31 must be zero NB if composite sync is configured in CMOS, the syncs will not be inverted 64 video control parameters list n -1 (terminator) The video control parameters list which is on the end of this list contains pairs of words (control parameter index, value), terminated by a -1 word, which control various additional VIDC registers and bits in registers, as follows (refer to VIDC20 data sheet for detailed explanations of terms):- Control Parameter Index Description Values 1 LCD mode 0 => disable, 1 => enable 2 LCD dual-panel mode 0 => disable, 1 => enable 3 LCD Offset Register 0 0 to 255 4 LCD Offset Register 1 0 to 255 5 Hi-res mode 0 => disable, 1 => enable 6 DAC control 0 => disable, 1 => enable (default) 7 RGB pedestal enables bit0=R, bit1=G, bit2=B 8 External Register [7:0] 0 to 255 9 hclk select/specify See note a) below 10 rclk frequency See note b) below Notes ----- a) This value, if non-zero, forces RISC OS to select hclk as its clock input, and the value itself indicates to RISC OS what frequency is expected to be coming in on this pin (in kHz). RISC OS will then set up the internal divider to try to achieve the pixel rate specified in the main body of the list (normally you would make this the same, so that RISC OS would select divide by 1). The frequency is also used by RISC OS to compute the FIFO load position. If the value is zero, then RISC OS uses rclk or vclk as per normal. b) This value, if non-zero, tells RISC OS that the frequency coming in on the rclk pin is not 24MHz, but is in fact the value specified (in kHz). This knowledge is then used by RISC OS to determine the moduli values for the specified pixel rate and the FIFO load position. In addition, the value is stored in VDU variable VIDCClockSpeed, which is read by the sound system to determine what value to program the Sound Frequency Register with (since the sound system is driven by rclk). It is expected that the control parameters list will normally contain no entries at all for normal video operation - only for special applications is this needed. [ Implementation details: Note: RISC OS needs to compute the moduli for the Frequency Synthesizer Register, based on the requested pixel rate. This requires that either the operating range of the VCO is known at assembly time, or some kind of "biofeedback" code is written which times the output from VIDC using the vsync input. ] Two additional parameters are supplied on entry to Service_ModeExtension, namely the video bandwidth available on the machine, in units of bytes/second, passed in R4 on entry, and the total amount of video RAM in the system, in bytes, passed in R5 on entry. These are useful because the Medusa range of machines encompass a wide range of video capabilities, from DRAM-only machines through to machines with 1 or 2 Mbytes of VRAM. Supplying this parameter allows a mode provider to check that a given screen mode at the specified frame rate can be achieved with the machine's video bandwidth and its amount of video RAM. A mode provider should only respond to this service if the mode being selected would use no more video bandwidth than the amount in R4, and no more video memory than the amount in R5. [ Implementation detail: Since it is impossible for the machine to measure the video bandwidth available, RISC OS will supply one of 3 fixed values, based on whether the machine is fitted with 0, 1 or 2 Mbytes of VRAM respectively. ] 5.4 Extensions to Service_ModeTranslation ----------------------------------------- On RISC OS 3 this service passes in a mode number which is unavailable on the current monitortype, and passes back a substitute mode number. On Medusa, this is extended to allow the substitute mode passed back in r2 to be an arbitrary mode specifier. However, the input mode will only ever be a mode number, as a mode change controlled by a pointer to a mode selector never uses a substitute mode. 5.5 New service call Service_EnumerateScreenModes (reason code &8D) ------------------------------------------------------------------- The function of this service call is to allow "mode chooser" applications to find out what resolutions at what pixel depths are available. Applications should not issue this service call directly - they should instead call OS_ScreenMode with reason code 2 (see above for details). On entry: r1 = &8D (reason code) r2 = enumeration index r3 = monitor type r4 = memory bandwidth available (in bytes/second) r5 = total amount of video RAM in system (in bytes) r6 = pointer to block to return data into, or 0 to just count entries r7 = size of block if r6<>0, zero if r6=0 On exit: r2 = updated enumeration index r6 = updated block pointer r7 = updated size of block This service call provides a means whereby modes can be enumerated. It can be issued in two ways: the first to find out how many modes there are, and how much space is needed to store all of them; the second to actually enumerate them into a buffer. The enumeration form can be done as a partial enumeration so that a fixed size buffer can be used. The following descriptions are from the point of view of the caller: Finding out how many modes there are and how much space they need: On entry: r1 = &8D (reason code) r2 = 0 (enumeration index) r3 = monitor type r4 = memory bandwidth available r5 = total VRAM r6 = 0 r7 = 0 On exit: r2 = -(number of modes) r7 = -(amount of space needed for them) other registers preserved Doing a (partial) enumeration: On entry: r1 = &8D (reason code) r2 = number of modes to skip r3 = monitor type r4 = memory bandwidth available r5 = total VRAM r6 = pointer to block r7 = size of block On exit: Block big enough case: r1 = &8D r2 = -(number of modes in block) r6 = pointer to byte after last filled in byte r7 = amount of unused space in block Block too small case: r1 = 0 (Service_Serviced) r2 = -(number of modes in block) r6 = pointer to byte after last filled in byte r7 = amount of unused space in block As a client of this service call your algorithm should be: Repeat r2 = total number of entries processed so far (ie is 0 first time round) r6 = pointer to block r7 = size of block Call OS_ScreenMode reason 2 (Enumerate screen modes) Process block contents (from block to r6 returned from OS_ScreenMode) Until r1 returned from OS_ScreenMode was non-0 As a module which wishes to respond to this service call your algorithm should be: For each mode that wants to be returned If r2 > 0 Then do nothing, ie skip it Else If r6<>0 Then (enumeration case - filling in block) If r7 >= entrysize Then store entry at r6 r6 += entrysize Else (not enough space for next mode) r1 = 0 (Service_Serviced) Return (service call claimed) EndIf EndIf r7 -= entrysize EndIf r2 -= 1 Next Return (service call passed on) The registers are updated as follows:- r1 = preserved (block didn't overflow) or 0 (block overflowed) r2 = updated enumeration index (decremented by 1 for each entry considered) r3-r5 are preserved r6 = block pointer, updated to point after all entries stored in the block (or stays at 0) r7 = size of remaining free area in block (or gets decremented by amount of space needed by the entries that would have been put into the block had r6 been non-0) The module should return information on all modes that it provides that work on the specified monitor type and which require no more than the specified memory bandwidth, and no more video memory than the specified amount. For each such screen mode, the module stores the following information in the block:- Offset Value 0 size of entry in bytes (24 for this format) 4 mode provider flags: bit 0 = 1 (always) bits 7..1 = mode info format specifier (zero for this format) bits 31..8 = additional mode info flags (must be zero) 8 x-resolution (in pixels) 12 y-resolution (in pixels) 16 pixel depth (as per mode selector) 20 frame rate (Hz) (to the nearest integer) 24 mode name. This will be 0-terminated and then padded with 0s until it is word aligned. For unnamed modes this will simply be a single word whose value is 0. 5.6 New module: ScreenModes --------------------------- 5.6.1 Overview -------------- VIDC20 supports a much wider range of monitors than did VIDC1. Because the range of line frequencies available on monitors varies so widely, it has been decided that rather than create a plethora of new monitortype numbers to cope with this, a new ScreenModes module will be created, which reads the timings for the full set of screen modes from a file on the hard disc. Files containing screen mode information will have the filetype "ModeInfo". The number for this will be allocated at a later date, and the functional specification updated to reflect the allocation. The format for these files is described in section 6.1 below. 5.6.2 *LoadModeFile ------------------- Syntax: *LoadModeFile This command loads a file of type "ModeInfo" into memory, and if the file contains valid information, sets the current monitortype to 7 (file) (using OS_ScreenMode(3)). This then makes available all the screen modes defined in the file, while removing all modes defined in any previously loaded file. 5.6.3 MonitorType 7 (File) -------------------------- This new monitortype is reserved for exclusive use by the ScreenModes module. When a file is loaded by the module, the current monitortype is set to this, which effectively replaces all the screen modes defined in the ROM by the modes defined in the file, because the kernel does not respond to this monitortype. 5.7 Changes due to hardware differences on Medusa platforms ----------------------------------------------------------- 5.7.1 Monitor lead ID --------------------- In order to reduce cost, Medusa platforms can only detect bit 0 of the monitor lead ID. The tables below show the old and the new mappings from monitor lead ID to monitor type, mode and sync type. Mapping for existing machines ----------------------------- ID Bits 3210 Description Monitor Screen Sync type mode type X101 Mono VGA 3 27 0 X110 Colour VGA 3 27 0 X010 Colour SVGA 1 27 0 XH11 Comp.Multisync 1 27 1 X11H TV standard 0 12 1 Other ? 0 12 1 Mapping for Medusa series machines ---------------------------------- ID Bit 0 Description Monitor Screen Sync type mode type 0 VGA capable 3 27 0 H TV standard 0 12 1 1 TV standard 0 12 1 Other TV standard 0 12 1 Because of the existence of the ScreenModes module, determining the monitor type from the monitor lead ID is much less important. Effectively the ID is only useful in setting up an initial screen mode, before the ModeInfo file for the user's monitor has been loaded. 5.8 Grey-scale modes -------------------- The RISC OS kernel will not provide any extra support for grey-scale modes. The WindowManager module will be extended to allow the selection of 16- and 256-level grey scale modes in the desktop - this will be implemented by the Wimp explicitly programming the palette after the mode change. In the 256-level case it will have to select a 256-colour mode with a fully programmable palette by the means described in section 5.1.1. 5.9 Gamma correction -------------------- RISC OS now allows an application to supply tables to perform gamma correction on RGB values being programmed into the palette. There are three 256-byte tables, one for each of red, green and blue. Before being output to VIDC, the red component of the physical colour (in the range 0 to 255) is used as an index into the red gamma correction table - the value obtained is the gamma corrected red value to be programmed into VIDC. In a similar fashion the green and blue components are looked up in their respective tables. The contents of the tables are set up by a call to PaletteV, as follows:- On entry: r0 -> gamma-correction table for red (must be word-aligned) r1 -> gamma-correction table for green (--------""--------) r2 -> gamma-correction table for blue (---------""--------) r4 = 9 (reason code) On exit: r4 = 0 => the video drivers support gamma correction, and the tables have been copied into system workspace r4 <> 0 => the video drivers do not support gamma correction 5.10 External video cards ------------------------- No additional support is provided in RISC OS for video cards. It is believed that the existing interfaces provide enough hooks for these to be added. The main requirement that an external video card has is to be able to redirect RISC OS's bitmap to an area of RAM on an expansion card. This would be in EASI space, and consequently it can allow full 32-bit access. This means that provided that RISC OS's screen address can be changed to point to somewhere in EASI space, the normal graphics primitives will work correctly. It is envisaged that the mechanism used to change screen address would be to switch VDU output into a sprite, where the sprite is situated in EASI space. This would require that there is some RAM immediately before the start of the bitmap, to hold the sprite area and sprite headers. An additional complication is the mouse pointer: its position can be polled on vsync by the external card drivers, and then whatever hardware on the card is producing the screen pointer can be updated with its new position. 6. Data formats =============== 6.1 File format for filetype ModeInfo ------------------------------------- Files of type ModeInfo contain definitions of all the screen modes available on a particular monitor. The mode definitions are written in plain text, so the files can be edited using !Edit. Spaces and tab characters (&09) are allowed anywhere in the file except in the middle of keywords or numbers. Lines starting with any number of spaces followed by the hash character "#" are treated as comments and ignored. The file consists of the following two lines: file_format: monitor_title: followed by any number of mode definitions, where <format> must be 1 for this format file <title> is a textual description for this type of monitor and a mode definition is as follows: startmode x_res: <x-resolution> y_res: <y-resolution> h_timings: <hsync>, <hbpch>, <hlbdr>, <hdisp>, <hrbdr>, <hfpch> v_timings: <vsync>, <vbpch>, <vtbdr>, <vdisp>, <vbbdr>, <vfpch> pixel_rate: <pixel rate> sync_pol: <sync polarities> mode_name: <mode name> endmode where <x-resolution> is the number of pixels displayed across the screen <y-resolution> is the number of displayed rasters The h_timings line controls the horizontal timings, as follows: <hsync> is the width of the hsync pulse in pixels <hbpch> is the width of the horizontal back porch in pixels <hlbdr> is the width of the left hand border in pixels <hdisp> is the number of displayed pixels horizontally (normally the same as <x-resolution>) <hrbdr> is the width of the right hand border in pixels <hfpch> is the width of the horizontal front porch in pixels The v_timings line controls the vertical timings, as follows: <vsync> is the width of the vsync pulse in rasters <vbpch> is the width of the vertical back porch in rasters <vtbdr> is the width of the top border in rasters <vdisp> is the number of displayed rasters vertically (normally the same as <y-resolution>) <vbbdr> is the width of the bottom border in rasters <vfpch> is the width of the vertical front porch in rasters <pixel rate> is the pixel rate required, in kHz <sync_polarities> is a number indicating what kind of sync signals are required, as follows: 0 => hsync normal, vsync normal 1 => hsync inverted, vsync normal 2 => hsync normal, vsync inverted 3 => hsync inverted, vsync inverted 4 => composite syncs <mode name> is a textual name for the mode for use in menus and such. The mode name field must be present, although the <mode name> itself may be blank. Note: VIDC20 imposes restrictions on the above parameters. In particular, all the horizontal timing values must be multiples of 2, and the horizontal total = hsync + hbpch + hlbdr + hdisp + hrbdr + hfpch must be a multiple of 4. See the VIDC20 specification for details of further restrictions. 7. Development test strategy ============================ PHTester scripts will be constructed to test the following SWIs/reason codes: OS_ScreenMode Reason 0 Mode numbers 0-255 will be tried A valid mode selector will be constructed and each of its parameters will be adjusted individually to be: Completely out of range Just out of range Just in range The mode selector with all parameters in range will also be tried Reason 1 For all the above selections reason 1 will be issued and the results displayed assuming the correct behaviour of reason 1. Reason 2 With the machine set up with a known set of screen modes this reason will be issued and the results displayed assuming correct behaviour. Reason 3 This reason will be issued with normal values and with -1 and the results displayed. OS_ReadModeVariable Two different mode numbers and five different mode specifiers will be tried. All mode variables will be obtained using all of these. The resulting mode variable values will be displayed. The mode specifiers must exercise 16 and 32bpp modes as well as 4 and 8 bpp modes. OS_CheckModeValid The same set of mode selectors as OS_ScreenMode was tried with will be tried on OS_CheckModeValid. The results will be displayed. OS_Byte (&87) The same set of mode selectors as OS_ScreenMode was tried with will be tried on OS_Byte (&87). The results will be displayed. Service_ModeExtension The same set of mode selectors as OS_ScreenMode was tried with will be tried on Service_ModeExtension. The results will be displayed. This will be performed with a known machine setup. Service_EnumerateScreenModes With a given machine setup Service_EnumerateScreenModes will be issued to obtain all possible screen modes. This will also be issued with a limited block size to test that the block doesn't get overflowed. A responder to Service_EnumerateScreenModes will be written which will generate each of the control indexes with each of the valid values (for small range indexes) and control values at each end of the ranges and in the middle (for wide range values such as LCD Offset Register 0). ColourTrans SWIs These will be tried with the range of mode specifiers prepared above as well as with the full range of mode numbers. The sprite area pointer tests are expected to be exercised as part of the general video enhancements work. Wimp_SetMode and *WimpMode *WimpMode will be tried with mode numbers - range checking will be tested, and mode description strings - a reasonable variety tried. Wimp_SetMode will be tested to make sure it generates mode specifiers correctly. All mode description string parameters will be tried independantly and then mixed in a number of reasonable varieties. Service_ModeTranslation A module will be written to substitute a fixed mode specifier. This will check for correct response to this service call. *LoadModeFile Valid ModeInfo files for all the RISC OS 3 monitor types will be prepared and tried. One of these will be corrupted with duff field values (each field will be corrupted on its own) and tried on *LoadModeFile. Monitor ID CGA, MultiSync, VGA and SVGA monitors will be tried to ensure the monitor ID algorithm gives a usable screen mode. Gamma Correction A BASIC application to generate gamma correction tables will be written to try this feature. This will be supplied in the Diversions directory. User Interface A mouse script will be prepared to exercise this part of !Configure. All buttons will be pressed with both click and adjust. This will be tried with a sensible Monitors directory as well as an empty one and a full one. It will be tried with both and absent and present defaults file inside !Configure. It will be tried with the configured setting being one of !Configure's files and with it being another file. 8. Future enhancements ====================== With the interfaces described above, it is possible to create a module which reads screen mode parameters from a file on initialisation. We would probably want to include some kind of editor which allows the user to test out new modes she has created. Medusa RISC OS does not understand VIDC lists type 0 or 1 returned from Service_ModeExtension. This may be added at a later date. -- End of screen mode selection API --