Archive Magazine 1996

home *** CD-ROM | disk | FTP | other *** search

/ Archive Magazine 1996 / ARCHIVE_96.iso / discs / utilities / utility_01 / uni_mode / !UniMode / Manuals / Manual next >

Wrap

Text File | 1992-06-21 | 76KB | 2,109 lines

The UniMode Package Manual Last Updated: 21-Jun-1992 ~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~ Contents ~~~~~~~~ Disclaimer Copyright Notice Introduction - What is POST-Ware? - History User's Manual - Terminology - The programs - The HB_Index Programmer's Guide - The ModeDescriptionScript (MDS) - Use of Constants and FuNctions - The ModeDescriptionFile (MDF) - Notes on designing your own mode Error messages Bibliography Acknowledgements Disclaimer ~~~~~~~~~~ The authors will not be liable for any damage, loss of profits, goodwill or for any indirect or consequential loss arising out of your use of this application, or your inability to use it, even if the authors have been advised of the possibility of such loss. All efforts have been made to ensure the accuracy of the application. However, should any errors be detected, the authors would greatly appreciate being informed of them. The above notwithstanding, the authors can assume no responsibility for any errors. Copyright Notice ~~~~~~~~~~~~~~~~ You may freely copy and use the programs in this package under the following conditions: 1. You can GIVE this package to anyone you like, if and only if it is distributed with all original files and with no changes made to it. 2 If you want to put it on a BBS or include it in your PD library, you can do so, taking these notices into account. You may not charge any money for it, apart from postage and storage medium costs. 3. The UniversalMode module may be distributed separately as part of an other application which uses MDF's provided that the module is supplied "as is" and no charges are made for it. The UniversalMode module remains copyright of Hendrix Bros. 4. The entire package remains copyright of Maurice & Jean-Piδrre Hendrix (HendrixáBros.) under all circumstances. The copyright is NOT transferable. 5. You should send a nice picture-postcard to the authors: Maurice Hendrix Jean-Piδrre Hendrix Bergeijkstraat 17 Kanaalstraat 33 5043 BD Tilburg 5104 AA Dongen The NetherLands The Netherlands ** Please specify hardware-configuration when you write us. We're interested to know: ñ Type of computer and OS version ñ Type of Monitor ñ Type of VidcEnhancer (Manufacturer etc.) ñ Version number of !UniMode ñ Does it work or not? Introduction ~~~~~~~~~~~~ This document describes the resources that are contained in the UniMode package. The most important parts of this manual are the User's Guide and the Programmer's Guide. The User's Guide describes how the average user can make the most out of the package. In the Programmer's Guide we try to explain how you can build your own modes. Since it is a Programmer's Guide the VIDC datasheets and/or some experience with programming the VIDC will be necessary. This application should work on the following machines: R series (running under RISC OS) A300 series A3000 series A400 series A400/1 series A500 series A5000 series * Do you have a machine that is part of the Acorn RISC Range of computers but is not in this list? Then we are very interested in hearing from you. * Do you have a machine that is part of the Acorn RISC Range of computers and does UniMode not work on your machine? Let us know and maybe we can find a solution. We hope that you will enjoy using this package. If you do or if you don't let us know. The software in this package is POST-Ware. What is POST-Ware? ================== For programs in the Shareware or Careware domain you pay a small amount of money. Authors of Public Domain programs expect you to send them a small amount of money in appreciation. This does not work. Most people will not pay for Public Domain programs and they come up with the most astonishing reasons. Shareware programs are mostly paid for once. After that they are copied (illegally) many times. POST-Ware programs are based upon the Human-nature of not wanting to pay for anything if you can get it for free. Let's face it, the chances of getting dragged to court by some author are astronomically small. So, knowing this, authors of POST-Ware programs don't expect anybody to pay for their efforts. But they DO like to know whether their program is actually being used (=copied) and how it performs. So, they request each user to send them a picture-postcard. This way the author knows that somewhere out there someone is actually using his program. Since the cost of a postcard and stamp are so small, the chances of receiving a postcard are much bigger than those of receiving any money. If he is lucky he'll get all kinds of postcards from all over the world and he can put them to many uses: 1. Hang them on the wall as decoration 2. Look at them to boost his ego when he is feeling down. 3. Use them as a reference, when applying for a job (success not guaranteed) 4. You can think of a few more, can't you? History ======= Over the years people have been dissatisfied with the screenmodes that were offered by RISC OS and making soft-modes was strictly prohibited to the few who really understood how it was done. Users wanted bigger HiRes modes, small memory-saving modes, VGA or SVGA modes, modes with specific X:Y ratios, etcetera. Out of this need, programs were developed to help people create their own soft-modes. Also, several companies offered programs that supplied ready-made modes. With the coming of the so-called VidcEnhancers the amount of such programs grew extensively. Many of these programs are modules. They supply one or more modes. Unfortunately the user cannot control which modenumber is allocated to a given mode. The problems related to this are obvious: 1. Some modules supply visually different modes but with the same modenumbers. Due to clashing modenumbers the user can only use one of the modules. If he wishes to use the other mode (which has the same modenumber) then he needs to go to the CLI to kill one module and load the other. This can be very frustrating to many a user. 2. A large number of modules supplies modes with a modenumber between 29 and 46. These programs no longer work under RISC OS 3. This is because RISC OS 3 itself supplies modes in the range 0...46. So if you had a favourite mode 42 and you upgrade to RISC OS 3 you'd loose your favourite mode. Or would you? 3. Some of the VIDC Enhancer-Add-On's offered for the RISC OS 2 machines are mapped into a specific bit in the IOC. Others are interfaced using the IIC-bus. When Acorn released their A5000 machine they decided not to support any of these so-called third party products. Therefore all modules that supply a mode that requires a VIDC Enhancer-Add-On do not properly display on an A5000. Even worse, modules designed for one type of VidcEnhancer, do not work properly with ANY other VidcEnhancer. The solution is easy. UniMode was created because we experienced these problems with the newly acquired A5000. UniMode let's YOU decide which mode-definition is allocated to which modenumber and what kind of VidcEnhancer YOU want to use. It is fully RISC OS 2 compliant and runs under RISC OS 3 as well. The entire package was developed and tested on both a 2Mb A5000 (with On-Board-Enhancer) and a 4Mb A310 (with SCSI, ARM3 and VIDC Enhancer-Add-On). It is advisable that programmers read the User's Guide before reading the Programmer's Guide, since some basic information can be found there. User's Guide ~~~~~~~~~~~~ This section tries to explain how UniMode works and how you should go about to make the most of it. Terminology =========== The following terms are introduced with this package: MDF or ModeDescriptionFile: This is a binary file with filetype &103. The VIDC- and Workspacelists of a mode are stored in this file together with some machine specific data. The UniversalMode module loads this file when you use the ModeLoad command. An MDF can be recognized by it's icon and the FileType: UniMode. MDS or ModeDescriptionScript: This is a textfile. This file contains all the information of the corresponding MDF in ASCII-format. This file can be edited to change certain parameters or variables. After that you can compile the MDS back into an MDF. If you are going to edit the MDS, be warned that if you do not know anything about programming the VIDC you may not like the result of your venture. VIDC Enhancer-Add-On: With this we mean the third party products generally known as the "VIDC Enhancer" which are available for 300/3000/400 series of machines from several companies. On-Board-Enhancer: With this we mean the Enhancer-hardware built-in by Acorn in the 500/5000 series and (probably) future machines. VidcEnhancer: We use the term VidcEnhancer when we wish to refer to both the VIDC Enhancer-Add-On and the On-Board-Enhancer. The programs ============ In this section most of the files supplied with the package are explained. The directory path given between the curly brackets is the path where you can find the program. !UniMode -------- This is the application. Double-click on it's icon to install the application on the icon bar. The application supports Acorn's Interactive Help. Shift-Double-click will open the application directory and reveal the following sub-directories: <UniMode$Dir>.Manuals contains this manual and several textfiles. <UniMode$Dir>.Modes contains any MDF-s that you have compiled or extracted. <UniMode$Dir>.ModeScript contains the script files. <UniMode$Dir>.Utils contains the various utilities supplied with the package. If you start the application it will install itself onto the icon bar. When you double-click on an MDF or when you drag an MDF to the icon bar-icon the following window will open: ** See the !Drawfile "Window" ** You can now assign the mode definition to a modenumber. Use the Palette to change the Desktop mode. If you close the window, the mode definition is not loaded. Clicking with Select over the icon bar-icon opens the directory <UniModeMDS$Dir> which contains the ModeDescriptionScripts. Clicking with Menu over the icon bar-icon opens the application's menu. The menu supplies the following options: Info ë .......... Compile ë Expand MDF Info Enhancer ë TimeRaster Directories ë Quit * Choosing 'Quit' will remove the application from the icon bar. However, UniMode and all mode definitions that have been loaded remain active until you RMKill the module, switch off the machine or use *ModeClear to remove a specific mode. * 'Info ë' leads to a standard information window * 'Directories ë' opens the following sub-menu: MDF opens the directory <UniModeMDF$Dir> MDS opens the directory <UniModeMDS$Dir> Manuals opens the directory <UniMode$Dir>.Manuals Utils opens the directory <UniMode$Dir>.Utils * 'TimeRaster' calls the utility "TimeRaster". The effect is that the rasterfrequency of the current mode is displayed. * 'Enhancer ë' leads to a sub-menu with the options On, Off, Auto, Intelligent, Prefs and Quiet. Clicking on one of these options switches the UniMode module in the corresponding state. Refer to the paragraph entitled "UniMode (UniversalMode Module)" for more details. The current of the module is reflected in the menu with a tick-mark. The state of the VidcEnhancer is reflected through the last option in this menu. If the VidcEnhancer is switched on by the module; the menu-item reads: 'Status: On'. If the VidcEnhancer is switched off by the module then the menu-item reads: 'Status: Off'. If the module is switched into its Quiet mode the status of the VidcEnhancer is controlled by other software and hence unknown. This is shown by the last menu-item as: 'Status: ???'. * Clicking on 'MDF Info' opens a dialog window with the title: "Input :". Dragging an MDF or a selection of MDF-s to this window will display some information about the ModeDefinition contained in this/these file(s). * Clicking on 'Expand' opens a dialog window with the title: "Input :". 1 Dragging an MDF to this window, will change the title to "Expand". The icon in the window will change to a Textfile-icon. The filename will appear in the entry-space. You can change this name before you drag the Textfile-icon to a directory-viewer. The MDF that you dragged to the window will then be expanded into an MDS. It will be stored in the directory where you dragged the Textfile-icon under the name that is in the entry-space. 2 Alternatively, you can drag a directory-icon onto this window. The title of the window will change to "Batch Expand". The icon in the window will change into a directory-icon. The name of the source directory will appear in the entry-space. You can change this name before you drag the directory-icon to a directory-viewer. Any MDF's in the source directory will be expanded. If the destination directory does not exist, it will be created first. The destination can NOT be the same as the source. Attempting to do this will generate a 'File Open' error. * Clicking 'Compile >' will result in a dialog window being opened. Dragging an MDS to this window, will change the title to "Compile". The icon in the window will change to an UniMode-icon. The filename will appear in the entry-space. You can now change this name before you drag the UniMode-icon to a directory viewer. The MDS that you dragged to the window will be compiled into an MDF. It will be stored in the directory where you dragged the UniMode-icon. The MDF will be given the name that is displayed in the entry-space. NOTE: The compiler has the option of creating a log-file. (See the paragraph 'CompileMDS' for more details) By default, the log-file will be sent to the null: device. You can change the destination of the log-file to virtually anything (e.g. vdu: or printer: or ram:$.Log etc.) by entering this destination into the writable menu-item behind 'Compile >'. Remember that entering a destination which does not exist can lock up the machine. E.g. sending the log-file to a switched-off 'printer:' can hang the machine. !Boot ----- { <UniMode$Dir> } The !Boot file of the application is inoculated against the Extend virus by default. !Run ---- { <UniMode$Dir> } If you have a Multiscan monitor remove the '|' in front of the second IconSprites command and put it in front of the first IconSprites command. This will load mode 20 icons instead of the default mode 12 icons. Templates --------- { <UniMode$Dir> } This file contains the necessary window templates of the application. !Sprites -------- { <UniMode$Dir> } This sprites-file holds the mode 12 icons, which can be used for all monitortypes. !Sprites22 ---------- { <UniMode$Dir> } This file is used by RISC OS 3. It contains high-definition colour icons for use with VGA, SVGA or MultiScan monitors. !Sprites23 ---------- { <UniMode$Dir> } This file is used by RISC OS 3. It contains monochrome icons for use with Hi-Res Monochrome monitors. UniMode (UniversalMode module) ------------------------------ { <UniMode$Dir> } Before you are able to make your modes with !UniMode you will need to know how the package works. The core of the package is the relocatable UniversalMode module. This module provides all the interfaces with the operating system. The most important reason to write this module, was to gain full control over the VidcEnhancer, and so getting lost of the "AutoVidc" program which was only partly a solution to the problems. You might look at the !UniMode-package as if it is an upgrade from "AutoVidc". The module provides 5 ways in controlling the VidcEnhancer, all of them grew out of need: *Vidc On This command switches the VidcEnhancer on (36 MHz). The pixelrate of any mode is increased to 1.5 times of the default rate. This means that normal B(roadcast)S(tandard)-modes become real calm (50 -> 75 Hz). Or you can use much bigger modes at a respectable rasterfrequency. *Vidc Off This command reverses the *Vidc On effect. *Vidc Auto This command was implemented to emulate the SuperVidc Auto command and the AutoVidc control. Where SuperVidc uses a triggerlevel, or AutoVidc uses an internal table to determine whether the VidcEnhancer should be switched on or off, UniMode uses the VidcEnhancerbit in an MDF. Modes which are generated using the !Unimode-package can be programmed to switch the VidcEnhancer on or off (for details see the description on making an MDS). For standard RISC OS modes, you can load a "VidcOn" or a "VidcOff"-file on that mode. Example: if you want the VidcEnhancer to be switched on when entering mode 12 just type *Modeload VidcOn 12. Alternatively *MDF:VidcOn 12 may be used since RISC OS will recognise the filetype. One minor set-back is that the VidcEnhancer will only be switched off if a "VidcOff" was loaded for another mode, or a *Vidc Off command is issued. *Vidc Intelligent This command switches the module to its "Intelligent" state. This means that a very complex algorithm is used, every time you select another mode, to determine whether the VidcEnhancer should be switched on or off. We have not (yet) found any mode that is judged incorrectly by the algorithm. This is also the default state. *Vidc Prefs *Vidc Prefs is a combination of all goodies, especially included for those who CAN get the Intelligent algorithm to fail. In this state the action taken by !UniMode is modenumber-dependent: RISC OS 3 modes are switched on according to our own preferences. All other modes under 96 will act as if the module is in its Intelligent-state. Modes from 96 to 111 will act as if the module is in its Auto-state. Modes from 112 to 119 will switch the VidcEnhancer on, the remaining modes from 120 to 128 will switch it off. *Vidc Quiet This command switches the module to its "Quiet" state. This means that the module will not affect the state of the VidcEnhancer. This allows other soft- or hardware to affect the state of the VidcEnhancer. A little feedback from the module to the user might come in handy if you are busy programming MDF's. So the *Vidc Status command was included to return some information on the module- and VidcEnhancer-state. Concerning modes, RISC OS 2 has two shortcomings, there are no commands provided to set the mode used by the operating system and/or the WIMP. Up to now; since they were implemented in UniMode: *Mode <mode#> Sets a new screen mode. Eg.: *mode 12 *WMode <mode#> Sets a new mode which will be used by the WIMP. Eg.: *WMode 12 All you need to do, to use a soft-mode, is loading a ModeDescriptionFile (MDF) in the workspace of the module at the modenumber you want. This can be done by using the command: *ModeLoad <filename> <mode#> To remove a modedefinition from the list can be done by using the command: *ModeClear <Mode#> The mode <Mode#> will no longer be available from this module. NOTICE: Never load an MDF at a modenumber which is already provided by RISC OS itself. This won't work properly. There are only two exceptions: the MDF's "VidcOn" and "VidcOff" *HardwareRevision makes it possible to set the HardwareRevision manually in case the determination algorithm used in this module fails. Revision Enhancer type ------------------------------------------------- 0 Atomwide compatible (IO1) 1 Acorn On-Board (eg. A540 A5000) 2 Watford compatible (IIC) 3 Atomwide compatible (IO2) *HardwareRevision without a parameter echoes the current hardwarerevisionlevel set. Commands Syntax: *ModeLoad <FileName> <Mode#> *ModeClear <Mode#> *Mode [<Mode#>] *WMode <Mode#> *VIDC On|Off|Auto|Prefs|Intelligent|Quiet|Status (Default: Intelligent) *HardwareRevision [<level>] Additionally the module sets the systemvariable <MDF$Path> as follows: SetMacro MDF$Path <Run$Path>,<UniModeMDF$Dir>. This means that you don't have to specify the entire path (E.g. in *ModeLoad) of the MDF, instead, MDF: will suffice. NOTE Because we did not know how to interface with the Watford-compatible VidcEnhancer (Revisionlevel 2), this VidcEnhancer is not supported. If YOU do know how to do this let us know so that we can update the software. !RunImage --------- { <UniMode$Dir> } This program supplies the icon bar front-end of the application. Refer to the paragraph '!UniMode' for a description of this program. !Help ----- { <UniMode$Dir> } A small help-file. CompileMDS ---------- { <UniMode$Dir>.Utils } This program compiles an MDS into an MDF. For safety reasons, you can only compile one file at a time. There are two ways of compiling an MDS. The first one is discussed in the paragraph '!UniMode'. The second way of compiling an MDS is via the CLI: SYNTAX: *CompileMDS [<Inputfile> [<Outputfile> [<Logfile>]]] INPUT: Input file : This is the filename of the MDS. The directory is assumed to be the standard directory where all script files are stored: <UniModeMDS$Dir>. Output file : This is the filename of the MDF. The directory is assumed to be the standard directory where all definition-files are stored: <UniModeMDF$Dir>. Run-time logging: CompileMDS reports on virtually everything it is doing (including any anomalies or errors that are encountered). You can redirect this output to virtually any destination (E.g.: null:, vdu:, printer:, serial:, ram:logfile, adfs::0.$.logfile, etc.) Remember that the destination must exist. Sending the logfile to a (non-existent) serial: device can lock the machine. OUTPUT: The program outputs a log to the specified file/device and an MDF to the specified path/filename. NOTE: * The program does NOT check whether an MDF already exists. * An MDS is compiled in four passes. During the first pass the compiler checks the MDS for spelling mistakes. An error during this pass generally means a spelling mistake in one of the variablenames or in either card. Refer to the log to see where the mistake occurred. During the second pass the compiler will attempt to evaluate the value assigned to each variable. At the same time it will check whether the variable is valid. For example HDSR is a VIDC register. It can only occur in .VIDClist. If you would include this variable in .WorkspaceList the compiler would generate an error. Pass 3 is used to evaluate all the values and assign them to the appropriate variable ready for compilation. During this pass the compiler will report which variables will be programmed with which value. The third pass is also used to do a so-called "Cross-check". During the cross-check the compiler tries to find out whether the MDF being created COULD result in a working mode or not. Any warnings generated during the cross-check MIGHT indicate that the defined mode will not give a satisfiable display on your monitor. The compiler will also try to calculate the mode's rasterfrequency. This may deviate from the measured rasterfrequency by ▒ 2Hz. Refer to your monitor's manual to see if this mode can be displayed on your monitor. (Look in the technical specifications for "Vertical Sync", "Vertical Synchronisation", "Raster Frequency" or something similar. Typical values will be in a range between 50...100 Hz) Finally the HB_Index of the mode is calculated. Refer to the paragraph 'HB_Index' for more details. The final pass (Pass 4) is the compilation pass. All that happens here is the creation of the MDF from the results of the previous passes. * If the Logfile is set to null: then errors and warnings are reported to you through a standard text-window (provided that you're compiling from the desktop). If the Logfile is set to anything else the errors or warnings are put in the log. The compiler will display a message that an error or warning has occurred and refer you to the log. Expand / ExpandAll ------------------ { <UniMode$Dir>.Utils } These programs are used to convert an MDF into an MDS. The functional difference between the two is that 'Expand' operates on one file at a time while 'ExpandAll' operates on an entire directory. You can optionally supply the required parameters at the commandline. SYNTAX: *Expand [<Inputfile> [<Outputfile>]] *ExpandAll [<SourcePath> [<DestinationPath>]] INPUT: Input file : ('Expand') This is the name of the MDF. The directory is assumed to be the standard directory where all definition-files are located: <UniModeMDF$Dir>. Output file : ('Expand') This is the name of the MDS. The directory is assumed to be the standard directory where all script files are located: <UniModeMDS$Dir>. Source Path : ('ExpandAll') This is the name of the path where the MDF-s can be found. This is <UniModeMDF$Dir>. by default. Destination Path: ('ExpandAll') This is the name of the path where the MDS-s must be stored. This is <UniModeMDS$Dir>. by default. OUTPUT: The programs output the appropriate MDS(-s) to the specified path/filename. NOTE: * The programs are not recursive, i.e. they only operate on the files in the given directory. * 'Expand' can also be accessed by clicking 'Expand' in the !UniMode menu on the desktop. Refer to the paragraph '!UniMode' for more details. Extract / ExtractAll -------------------- { <UniMode$Dir>.Utils } These programs can be used to extract the mode definitions from a RAM-based module and thus create an MDF. Since copyright laws apply to some of these mode definitions, you may extract them for use in your OWN version of UniversalMode, but you may not pass these MDF-s to others. It is not necessary to disassemble a mode-supplying module. By simply calling OS_ServiceCall &50 'Extract' and 'ExtractAll' can find out all they need to know about a given mode in order to compile an MDF. The functional difference between these two programs is that 'Extract' extracts one mode at a time while 'ExtractAll' extracts all modes defined by RAM-based modules. You can optionally supply the required parameters at the commandline. SYNTAX: *Extract [<Modenumber> [<Outputfile>]] *ExtractAll [<CommonPart> [Q|S]] INPUT: 'Extract' displays the available modes. Type in the number of the mode that you wish to extract. You are offered a path/filename which you can change to your own liking. 'ExtractAll' displays the available modes. You need to enter the common part of the path/file-name. 'ExtractAll' appends the modenumber to this name and saves the MDF-s. (E.g. if the modes 50, 51 and 52 are available and the common part is specified as 'm'. Then the modes are saved as 'm50', 'm51' and 'm52') 'ExtractAll' lets you choose whether to "(Q)uery each" or "(S)ave all". Enter 'Q' and the program will let you change the filename before saving it. Delete the filename and that mode will be skipped. Enter 'S' and all modes will be extracted. OUTPUT: Both programs output MDF-s to the specified path/filename. NOTE: * RISC OS modes can not be extracted, because the UtilityModule does not reply to OS_ServiceCall &50 and no other means of retrieving this data is supplied by RISC OS. * Both 'Extract' and 'ExtractAll' also extract the soft-modes loaded by UniMode. If you do not want this to happen, you should enter *RMKill UniversalMode before starting either of these programs. * 'Extract' and 'ExtractAll' create a MDS with the following MachineSpecs by default: .MachineSpecs VidcOn MultiScan ExtractOS2 / ExtractOS3 ----------------------- { <UniMode$Dir>.Utils } As mentioned above, RISC OS modes can not be extracted by 'Extract(All)'. In some circumstances, however, you need the contents of the RISC OS registers in order to make a working MDF. For instance: If you want to use an MDF based on a RISC OS 3 BaseMode on a RISC OS 2 machine, you have got a problem. The best way around this, is to set BaseMode to the nearest RISC OS 2 BaseMode and then define ALL VIDC registers with the RISC OS 3 values. Using 'ExtractOSn': 1. Create a RAM-disc of approximately 112k. 2. Create a directory 'Modes' on the RAM-disc. 3. Create a directory 'ModeScript' on the RAM-disc. 4. a. On a RISC OS 2 machine run the program 'ExtractOS2' b. On a RISC OS 3 machine run the program 'ExtractOS3' 5. The RAM-disc now contains the MDF's and MDS's of the OS-modes. (All MDF's are automatically expanded using 'ExpandAll' Since distribution of these definitions may violate Acorn's copyright we have not included the RISC OS MDF's in the package. INPUT: - OUTPUT: These programs create MDF's of RISC OS modes. The MDF's are stored on the RAM-disc. The program 'ExpandAll' is called to create the MDS's. NOTE: * The presence of the directories 'Modes' and 'ModeScript' on the RAM-disc is assumed. * It should be obvious that 'ExtractOS2' cannot be used on a RISC OS 3 machine and vv. * It is very likely that 'ExtractOS3' only works on A5000 machines and not on other machines running RISC OS 3. * It is also very likely that 'ExtractOS2' and 'ExtractOS3' do not work on an A540 (different OS versions). We haven't tested this so if you have an A540, let us know! InfoMDF ------- { <UniMode$Dir>.Utils } 'InfoMDF' gives information about a given MDF. SYNTAX: *InfoMDF [<Inputfile>] INPUT: Mode file : This is the name of the MDF. The directory is assumed to be the standard directory where all definition-files are located: <UniModeMDF$Dir>. OUTPUT: Displays some information about the mode. (i.e.: size, colours, memory-requirements etc.) NOTE: 'InfoMDF' can also be accessed through the desktop front-end. Refer to the paragraph called "!UniMode" for more details. ModeInfo -------- { <UniMode$Dir>.Utils } 'ModeInfo' gives some basic information about the modes that you have currently available through RISC OS; loaded into UniMode; or supplied by other modules. SYNTAX: *ModeInfo [<Mode#>] INPUT: - OUTPUT: With no parameters ModeInfo will return the information of all modes currently installed. If you supply a number in the range 0...127 the information (if any) of that mode only is given. UMUserLib --------- { <UniMode$Dir>.Utils } 'UMUserLib' is a library. It is linked into 'Expand(All)' and 'CompileMDS'. The library contains a number of functions. These functions can be used in the definition of the MDF as substitutes for numerical values. See the Programmer's Guide for more details. UniModeLib ---------- { <UniMode$Dir>.Utils } 'UniModeLib' is also a library. It is linked into all utilities including the !RunImage. This library supplies the shared resources for the programs in the package. The contents of this library should not be altered by the user. If you wish to add FuNctions or PROCedures you should add them to 'UMUserLib' instead. TimeRaster ---------- { <UniMode$Dir>.Utils } This Utility can be used to measure the rasterfrequency of the current mode. The result may deviate ▒ 2Hz from what is calculated by CompileMDS. This deviation is due to rounding differences. The HB_Index ============ The HB_Index is a number which gives a rough indication of the speed of a mode. The HB_Index is calculated as follows: 1000 1) R = --------------- Rasterfrequency (bpp * (XWindLimit+1) * (YWindLimit+1) * 1000) 2) M = ---------------------------------------------- 8 M 4E7 - --- R 3) HB_Index = ----------- 4E7 The result is a number between 0.00 and 1.00. A low number typically means a slow mode, while a higher number suggests a faster mode. The speed of a mode can be experienced if the WIMP has to redraw a complete screen - with many different windows overlapping each other - after eg. a mode change (Press F12 followed by [RETURN]) to simulate a mode change). A slow mode will take a longer time to redraw the screen. As a result a fast mode indicates that the ARM has more time left to perform other operations. Generally you will want to perform time-expensive tasks such as printing etc. in a fast-mode. Eg. Mode 0 (which is often used for this purpose) has an HB_Index of approximately 0.97 while Mode 28 (clearly a slower mode) has an HB_Index of 0.55. The HB_Index depends on the Rasterfrequency of the mode. Therefore the compiler calculates an HB_Index for the mode for both VidcEnhancer states. With the currently available hardware (ARM2/ARM3 and 8 or 12 MHz MEMC's) modes with an HB_Index higher than 0.55 are usually experienced as reasonably fast modes. Modes with an HB_Index lower than 0.45 will be experienced as slow or even "snailish". Programmer's Guide ~~~~~~~~~~~~~~~~~~ This part of the manual deals with the structure of the ModeDescriptionFile (MDF) and the ModeDescriptionScript (MDS). The ModeDescriptionScript (MDS) =============================== If you wish to design your own soft-mode you can do so by creating an MDS. The structure of the MDS must follow these rules: 1. The first line of the file must start with the literal text: 'ModeDescription'. Use the space after it to give a short description of the mode, and the date you made it. 2. Comments may be included anywhere in the file. A comment must be preceded by either a ';' or a '|'. 3. The description is sub-divided into 4 sections called lists. Each list is headed by a card identifying it. Here are the lists: a. Constant Declaration. You can declare up to 16 constants. b. Machine Specifications. This is used to specify the monitortype for which the mode is suitable and how the VidcEnhancer is to be used. c. VIDC Registers. Here you can define the values to be programmed into the VIDC registers. d. Mode Variables. Here you can specify the values to be programmed into the Mode Variables. 4. To use a list you must enter its card at the start of a line. Each successive line contains the name of a variable followed by an appropriate value. Variablename and value must be separated by one or more spaces. Edit the MDS "ExampleMDS" or "DIY_BSDM" to see an example. 5. The last line in the file must start with the literal text: .End Below, each list will be discussed to make its use more clear. Constant Declarations (Card: .Declarations) ------------------------------------------- This list enables you to declare up to 16 constants (C(0) ~ C(15)). A constant can be used to make a definition more clear. <Value> can be anything that can be passed through BASIC's EVAL function Syntax: C(<VariableNumber>) <Value> E.g.: You could declare C(0) to hold the number of bits per pixel, C(1) could hold the number of columns and C(2) the number of rows. You can then define ScreenSize in the WorkSpaceList as follows: ScreenSize C(0)*C(1)*C(2)/8 Machine Specifications (Card: .MachineSpecs) -------------------------------------------- This list lets you define the required machine specifications. Syntax: <Specification> Specification Meaning ----------------------------------------------------------------------------- VidcOn|VidcOff Turn VidcEnhancer On|Off when this screenmode is selected and Unimode is in 'Auto'-mode. Standard50Hz This screenmode can be displayed on a Standard 50Hz monitor MultiScan This screenmode can be displayed on a MultiScan monitor MonoHiRes64Hz This screenmode can be displayed on a HiRes Monochrome monitor VGA60Hz This screenmode can be displayed on a 60Hz VGA monitor SVGA This screenmode can be displayed on a SVGA monitor (RISC OS 3 only) LCD This screenmode can be displayed on a LCD (RISC OS 3 only) E.g.: .MachineSpecs VidcOn MultiScan LCD Meaning: This mode is valid only for a MultiScan monitor or LCD display. When UniMode is in 'Auto' mode, the VidcEnhancer will be switched on. VIDC Registers (Card: .VIDCList) -------------------------------- You can program each of the VIDC registers defined below. If the WorkspaceList is present the VIDCList must also be defined. The value with which you program each register must be EVAL-able by BASIC. If you do not define a register, its value will be copied from the basemode that you defined. You must therefore at least define the variable BaseMode. Syntax: <Registername> <Value> *** Note, however, that the definition of the registers of a RISC OS 3 mode is not necessarily identical to the definition of the same mode under RISC OS 2!! E.g. In RISC OS 2's mode 12 the register HBSR has the value of 217, while under RISC OS 3 the same register HBSR of mode 12 has the value 135! Discussed below are the VIDC registers which can be programmed using the Unimode-package. They're only used by the VIDC. Refer to the !Draw-file: "VIDC_Regs" to see how the registers, discussed below, are mapped to the screen. We advise you to print this file if you want to study it. This will improve the readability of the texts. HCR: Horizontal Cycle Register. This register defines the period of the complete horizontal scan, in units of a pixel. It can be programmed with values from 2...2048, and must be even. pixelrate HCR = --------- = HBER + HorizontalFrontPorch linefreq HSWR: Horizontal Sync Width Register. This register defines the width of the horizontal sync (HSYNC) pulse, in units of a pixel. It can be programmed with values ranging from 2...2048, and must be even. HSWR = pixelrate * HSYNCDuration [MHz] [╡s] HBSR: Horizontal Border Start Register. This register defines the time from the start of the HSYNC-pulse to the start of the border, in units of a pixel. It can be programmed with values ranging from 1...2047, and must be odd. If no border is demanded, then HBSR should equal HDSR. HBSR = HSWR + HorizontalBackPorch HDSR: Horizontal Display Start Register. This register defines the time from the start of the HSYNC-pulse to the start of the active display, in units of a pixel. It can be programmed with values ranging from 1...2047, and must be odd. HDSR = HBSR + LeftBorderWidth HDER: Horizontal Display End Register. This register defines the time from the start of the HSYNC-pulse to the end of the active display (i.e. the first pixel which is NOT part of the active display), in units of a pixel. It can be programmed with values ranging from 1...2047, and must be odd. HDER = HDSR + PixelsOnActiveDisplayLine HBER: Horizontal Border End Register. This register defines the time from the start of the HSYNC-pulse to the end of the border (i.e. the first pixel which is NOT part of the border), in units of a pixel. It can be programmed with values ranging from 1...2047, and must be odd. If no border is demanded, then HBER should equal HDER. HBER = HDER + RightBorderWidth HIR: Horizontal Interlace Register. If an interlaced display is required, this register should be programmed. In all (most) other cases it may be omitted. It can be programmed with values ranging from 1...2047, and must be odd. *** NOTE: Interlaced displays have never been tested by the authors, so we recommend either not to use it OR take very, very much time for it (debugging the Unimode-utilities might be needed). When using a multiscan monitor, interlaced displays should not be used. (Most can't display them anyway.) VCR: Vertical Cycle Register. This register defines the period of the complete vertical scan, in units of a line. It can be programmed with values ranging from 1...1024. linefreq pixelrate VCR = ----------- = ----------------- = VBER + VerticalFrontPorch rasterfreq HCR * rasterfreq VSWR: Vertical Sync Width Register. This register defines the width of the vertical sync (VSYNC) pulse, in units of a line. It can be programmed with values ranging from 1...1024. no. lines during VSYNC VSWR = ---------------------- linefreq VBSR: Vertical Border Start Register. This register defines the time from the start of the VSYNC-pulse to the start of the border, in units of a line. It can be programmed with values ranging from 1...1024. If no border is demanded, then VBSR should equal VDSR VBSR = VSWR + VerticalBackPorch VDSR: Vertical Display Start Register. This register defines the time from the start of the VSYNC-pulse to the start of the active display, in units of a line. It can be programmed with values ranging from 1...1024. VDSR = VBSR + TopBorderHeight VDER: Vertical Display End Register. This register defines the time from the start of the VSYNC-pulse to the end of the active display (i.e. the first line which is NOT part of the active display), in units of a line. It can be programmed with values ranging from 1...1024. VDER = VDSR + ActiveDisplayLines VBER: Vertical Border End Register. This register defines the time from the start of the VSYNC-pulse to the end of the border (i.e. the first line which is NOT part of the active border), in units of a line. It can be programmed with values ranging from 1...1024. If no border is demanded, then VBER should equal VDER. VBER = VDER + BottomBorderHeight CR: Control Register. For this register, a special function has been included in the 'UMUserLib'. It can be called with FNCR("..."). Here is a list of keywords that can be used within the quotation-marks, with their meaning. Between brackets is given an abbreviation for that keyword. Since the string is decoded by RISC OS' "OS_ReadArgs", all keywords must be preceded with a '-'. * -PixelRate <value> (-PR). This is the VIDC-pixelrate in MHz, and can be programmed with 8, 12, 16 or 24. When the VidcEnhancer is switched on, these rates will be 50% higher. It is NOT possible to program PixelRate with e.g. 36. A pixelrate of 36 MHz can be obtained by programming PixelRate to 24 and setting VidcOn in the MachineSpecsList. * -BitsPerPixel <value> (-BPP). This is the number of bits per pixel, and can be programmed with values 1, 2, 4 or 8 (for resp. 2, 4, 16 and 256 colour modes). * -DMARequest <value> (-DR). This is the moment the VIDC will try to get four new words from the main memory. It can be programmed with one of the values 0, 1, 2, 3, 4, 5, 6, 7 or 8, where 0 and 4, 1 and 5, 2 and 6, 3 and 7 have the same meaning (DMA request after resp. word 0, 4 etc.). Since it is difficult to give a clear explanation of which value should be programmed in which case, a value of 8 asks the computer to compute a sensible value and fill it in. * -InterlaceSync (-IS). This is a switch. Presence only is important. It must only be used if an interlaced display is required. Interlaced displays have never been tested by the authors, so we recommend either not to use it OR take very, very much time for it (debugging the Unimode-utilities might be needed). When using a multiscan monitor, interlaced displays should not be used. (Most can't display them anyway.) Examples: CR FNCR("-PixelRate 16 -BitsPerPixel 4 -DMARequest 8") CR FNCR("-PR 16 -BPP 4 -DR 8") DATA: It may be desirable to program a VIDC register that has not been mentioned above. In such a case you can include "DATA" followed by the value you want to write to the VIDC. The value must be 32-bits wide. The registeraddress must be contained in the top 6 bits (bits 26...31). The data to store in the register is contained in bits 0...23. Bits 24 and 25 must be zero. Theoretically you should not be needing this statement. But you never know... Example: In theory, the value to be programmed into the Control Register can be defined in three different ways: 1. Via a function CR FNCR("-PixelRate 8 -BitsPerPixel 4 -DMARequest 2") 2. Via a numerical value CR 59 or CR &3B or CR %00111011 3. Via a "DATA" statement DATA &E000003B NOTE: Remember that this is only an example and you should use option 1. or 2. if the register to be programmed is supported by the compiler. "DATA" should only be used as a last resort for programming unsupported registers!! Mode Variables (Card: .WorkspaceList) ------------------------------------- This list contains the definition of each of the variables that are reported through OS_ReadModeVariable. If the VIDCList is present the WorkspaceList must also be defined. The value with which you program each variable must be EVAL-able. If you do not define a variable, its value will be copied from the basemode that you defined. You must therefore at least define the variable BaseMode. These variables are also discussed in the RISC OS 2 PRM on pages 350...352. ModeFlags: For this variable, a special function has been included in the 'UMUserLib'. It can be called with: FNMF(" ... "). Here is a list of keywords that can be used within the quotation-marks, with their meaning when included. Between brackets is given an abbreviation for that keyword. All keywords act as switches, if they're not present they will be automatically UNset. Since the string is decoded by RISC OS' "OS_ReadArgs", all keywords must be preceded with a '-'. * -NonGraphicsMode (-NGM). The mode does not support graphics. With the current hardware, a mode can always support graphics. * -TeletextMode (-TM). The mode is a Teletext mode, like mode 7, and thus acts a little different with respect to certain charactercodes. * -GapMode (-GM). The mode is a GapMode. This means that a character does not use the normal 8 lines, but it uses 10 instead. This can improve readability of the mode enormously. * -BBCGapMode (-BBCGM). The mode is a BBC compatible gapmode (e.g. mode 3 and 6). * -HiResMonoMode (-HRMM). The mode is to be displayed on a high resolution monochrome monitor. * -VDUCharsDoubleHeight (-VCDH). VDU characters are displayed in double height. * -HardwareScrollNotUsed (-HSNU). The hardwarescroll available in the ARM-based computers will not be used. This can slow down your machine enormously, especially when using large modes. ScrRCol: This is the number of characters on a line minus one. If the active display is 640 pixels wide (this can be derived from [HDER] - [HDSR]), it must be programmed with 640 / 8 - 1 = 80 - 1 = 79. ScrBRow: This is the number of character-lines minus one. If the active display counts 256 lines (this can be derived from [VDER] - [VDSR]), it must be programmed with 256 / 8 - 1 = 32 - 1 = 31. If it is a GapMode, the active display might count 250 lines, and ScrBRow should be programmed with 250 / 10 - 1 = 25 - 1 = 24. NColour: This is the number of colours minus one (1, 3, 15). However 256 colour modes should be programmed with 64 - 1 = 63. It must conform to the CR setting. XEigFactor: This is the number of times an X-coordinate must be divided by 2 to derive the actual pixel. If there are 640 pixels in the active display on a line, and XEigFactor is set to 1, RISC OS will work with coordinates in the range from 0 to (640 * 2) - 1 = 1279. When set to 2, this range is from 0 to (640 * 2 * 2) - 1 = 2559. YEigFactor: This is the number of times a Y-coordinate must be divided by 2 to derive the actual pixel. If there are 256 lines in the active display, and YEigFactor is set to 1 RISC OS will work with coordinates in the range from 0 to (256 * 2) - 1 = 511. When set to 2, this range is from 0 to (256 * 2 * 2) -1 = 1023 LineLength: This is the number of bytes on a pixel row. It should equal (chars per line) * (bits per pixel). ScreenSize: This is the number of bytes one screenbuffer occupies. It should equal (chars per line) * (bit per pixel) * (active lines). YShftFactor: This variable should not be used. It is kept for compatibility reasons only. Log2BPP: This is the ▓log(bits per pixel). This is for 2, 4, 16 and 256 colour modes resp. 0, 1, 2, 3, and must conform to the CR setting. Log2BPC: This is the ▓log(bytes per character). It usually equals Log2BPP. XWindLimit: This is the number of pixels on an active line, minus 1. So it should equal [HDER] - [HDSR] - 1. YWindLimit: This is the number of active lines, minus 1. So it should equal [VDER] - [VDSR] - 1. Syntax: <Variablename> <Value> Finalisation (Card: .End) ------------------------- This card is used to signal the end of the definition. Anything beyond this card is ignored. Use of Constants and FuNctions ============================== The value programmed into either a VIDCRegister or a ModeVariable can be virtually anything. Of course you can program it with a normal integer. But, you can also pass a formula like: 480*256*4. Or if you have declared a constant something like: C(0)*C(1)*C(2). But that's not where it ends. You can make it even more complex. For instance: LOG(C(2))/LOG(2) to calculate Log2BPP. This can be done because the value is passed through the function EVAL before it is programmed into the MDF. The great advantage of this mechanism is the fact that FuNctions can be part of the value. For this purpose the library 'UMUserLib' is linked into the compiler. Currently the following FuNctions are provided by this library: FNCR() Instead of thumbing through the Functional Description in the VIDC Datasheets and manually working out the contents of the Control Register, you can simply use this function to calculate the correct value for you. Refer to the paragraph 'VIDC Registers' for a description of this function. FNMF() The variable ModeFlags is a compound variable. Each bit has a different meaning. By using this function you needn't calculate the contents of this variable yourself. Refer to the paragraph 'Mode Variables' for a description of this function. FN_DecodeCR This function reverses the effect of FNCR() and is used by 'Expand(All)' when creating an MDS. FN_DecodeMF This function reverses the effect of FNMF() and is used by 'Expand(All)' when creating an MDS. You can of course add other functions to your personal copy of the library to enhance the package to your own personal needs. If you do, however, we would like to hear from you, as we may want to include these enhancements in future releases of the package. The MDS's "ExampleMDS" and "DIY_BSDM" are working examples of how you can create your own MDS. The ModeDescriptionFile (MDF) ============================= In order to use a ModeDescriptionScript (MDS) you need to compile it into a ModeDescriptionFile (MDF). Refer to the paragraphs "!UniMode" and "CompileMDS" for an explanation about how this can be done. The MDF can be loaded into the memory with the command *ModeLoad from the CLI. It can also be loaded via the desktop front-end "!UniMode". Refer to the appropriate paragraph for more details on this. The MDF is a binary file with the filetype &103 ("UniMode"). The structure of this file is as follows. Offset into File Contents ----------------------------------------------------------------------- &00000000 MachineSpecs word &00000004 Offset to the VIDC list from the beginning of the file (If bit30 of the MachineSpecs word is set) &00000008 Offset to WorkSpaceList from the beginning of the file (If bit30 of the MachineSpecs word is set) [&00000004] VIDC list (format of the list as defined on page 708 of the RISC OS 2 PRM) +0 0 (indicates format of list) +4 VIDC basemode : +n -1 (n equals: [&00000008]-4) [&00000008] Workspace list (format of the list as defined on page 709 of the RISC OS 2 PRM) +0 0 (indicates format of list) +4 Basemode : +n -1 The bits of the MachineSpecs word have the following meaning bit meaning if set --------------------------------------------------------------------- 0..n MonitorType n is supported by this mode. b0 = Standard 50Hz monitor b1 = MultiScan monitor b2 = Mono HiRes 64Hz monitor b3 = VGA 60Hz monitor b4 = SVGA monitor (RISC OS 3 only) b5 = LCD display (RISC OS 3 only) 30 VIDClist & WorkSpaceList are included 31 VidcEnhancer should be switched on On the whole you will find that the only MDF's that do NOT have bit30 of the MachineSpecs word set are "VidcOn" and "VidcOff". Notes on designing your own modes ================================= Below you will find a compilation of hints and notes that, we think, may be of value to you. As we were developing and experimenting with this package we gradually built this library of general knowledge and tips. They are in random order, added to the manual as we encountered them. * A Broadcast Standard Display Mode (BSDM) is specifically designed for Standard50Hz monitors (MonitorType 0) and has these specifications: ñ linefrequency : 15625 Hz ñ rasterfrequency : 50 Hz ñ line time : 64 ╡s ñ HSYNC : 4.5 ╡s ñ HorizontalBackPorch : 5.8 ╡s ñ HorizontalFrontPorch: 1.3 ╡s ñ VCR : 312 lines ñ VSYNC (=VSWR) : 3 lines ñ VerticalBackPorch : 15 lines ñ VerticalFrontPorch : 10 lines Refer to the MDS 'DIY_BSDM' for an example of how to make your own BSDM. Other modes must obey the monitor's specs. Look for them in your manual. * Both porches, front and back, are with respect to the SYNC-pulse. Thus the frontporch is between the end of the border and the start of the SYNC-pulse of the next line (flyback). The backporch is between the end of the SYNC-pulse and the start of the border. * All registers and variables must be correctly programmed, to obtain a useable mode and all depend on each other. * Normally a character is 8 by 8 pixels. This means that if you want RISC OS to print readable characters, you should use multiples of 8 pixels and lines when defining the width and height of the active display. * The first line of an MDS contains the word 'ModeDescription'. Use the space after it to give a short description of the mode, and the date you made it. * Linefrequency = the number of times a horizontal line is written by the monitor per second. * Rasterfrequency = the number of times a complete screen is written per second. It should at least equal 50Hz, otherwise the screen will become flickery. There is a utility included: 'TimeRaster' to measure the rasterfrequency of the current mode. You can also calculate it with this formula: PixelRate * 1E6 --------------- = Rasterfrequency HCR * VCR * A pixel is not necessarily part of the active display. To define the H-registers, the unit pixel is also used. In this case only the time a pixel takes is important. Only pixels part of the active display can be given another colour (apart from the one-coloured border). * The active display is that part of the entire screen that can be seen and changed by other programs. It is the part you usually work on. * For those of us who cannot afford a VidcEnhancer, there might be a software solution: when the original mode has a pixelrate of 8, 12 or 16 MHz you can 'turn on' your 'VidcEnhancer' by changing these values to resp. 12, 16 or 24. 12 MHz modes can be changed to 16 MHz, and so use a higher scanrate, but the it does not equal the Enhancer-on-off-ratio of 1.5. * [VCR]...[HCR] gives you a rectangle. Within this rectangle the actual mode is programmed. * When you are designing a new mode you can save yourself a lot of work if you use the MDS of an existing mode. Especially RISC OS modes extracted with 'ExtractOSn' are very suitable. Simply take the MDS of a mode that looks like what you want and change the appropriate registers and/or variables. * The HSWR is the register which is the most difficult to define. The HSYNC must be long enough so that the DMA Address Generator in the MEMC can reset the screen pointer. This takes 2125ns. You can therefore calculate the minimum value that must be programmed into the HSWR with the following formula: 2125 * pixelrate HSWR = ---------------- 1000 During the HorizontalBackPorch the Video FIFO needs to load at least one word 4 pixel-times before the display starts. The length of the HorizontalBackPorch can be calculated with: 1437 * pr + 4000 ---------------- = HorizontalBackPorch 1000 (Round up to the next integer) These values are needed to calculate the HBSR as follows: HBSR = HSWR + HorizontalBackPorch NOTE: IF your machine has a faster MEMC (i.e.> 8 MHz ) you might be able to program the HSWR with a lower value without any problems. The compiler will still give a warning and the MDF may not give a good result on other machines. The minimum value suggested by the compiler ensures that the MDF works on almost all machines. Keep also in mind that the HSWR must be long enough for the monitor to synchronize to it aswell !! * If you want UniMode to 'intelligently' switch the VidcEnhancer on whenever you select the mode, make sure that the rasterfrequency of the mode is less than 50Hz (with the VidcEnhancer switched off). You can (sometimes!) do this by increasing the HCR and/or VCR. After that you may have to re-align the display by changing the other registers also. Remember, that this method is not guaranteed to work and you may not like the result. * 8 MHz; 1 bpp modes (with VidcOff) are not supported by the VIDC-chip. Sometimes however you may be able to display them if you switch the VidcEnhancer On and Off again. * You can use ARMBE (the ARMBasicEditor) with your favourite mode if you load the ModeDescriptionFile at modenumber 22. Then setup the ARMBE to use mode 22. Make sure that you have enough ScreenMemory available and that the MDF has been loaded prior to entering the BasicEditor or the BasicEditor will re-configure the mode used to 0. * When you expand a file you drag the Textfile-icon to a directory-viewer. Alternatively, you can drag the icon to a icon bar-icon. If the application (eg. !Edit) supports data-transfer via Wimp$Scrap the MDS will be automatically loaded into the application. This can be very useful if you want to expand an MDF and immediately start editing it. * Usually Log2BPP and Log2BPC will contain the same value. * It is our experience that people will try to define a mode which takes their own monitor to it's very limits (Eg. The highest or lowest rasterfrequency possible; or a very wide display that only just fits). Although this is perfectly "legal" in your own case remember this: Not all monitors have the same specs. And the MDF you created may not work properly on other monitors. * Do you see flickering pixels in the upper-right corner of the display? Does the first display-line behave "strangely"? These are the telltale signs of a (too) short HorizontalBackPorch. As explained, the HorizontalBackPorch must be long enough to allow the Video FIFO to load one word four pixel-times BEFORE the display starts. If the HorizontalBackPorch is too short this word will not have been loaded into the Video FIFO resulting in the first few pixels not being displayed properly. * While experimenting you may discover that your monitor can display modes with a rasterfrequency higher than the specifications of your monitor given by the manufacturer. Your monitor's manufacturer had a good reason for those specifications, so stick to them. We can't tell what might happen... * What to do if the VidcEnhancer does not respond. 1. Check the *HardwareRevision set and adjust it to yours. 2. Check if there are any modules providing modes or controlling the enhancer are loaded (except UniversalMode). *RMKill them, perhaps you might like to Extract some modes from the modules first. 3. You may have a Watford VidcEnhancer. This VidcEnhancer IS recognised by UniMode but we don't know how to control it. If you DO know how to do this let us know and we'll send you an update. 4. You may have a VidcEnhancer that we have never heard of. * On some monitors the colour white may appear to be somewhat yellowish. You may want to improve the visual appearance of white. There is a trick that is used in the paper-making industry to make paper appear more white, the same trick is also used by many people when they do their laundry. The trick is to add some bleu to the whites. The visual appearance of white with a teint of blue is: "Whiter than white" as they say in washing-powder commercials. How do you implement this trick on your desktop? It's easy: 1. Click SELECT over the palette icon on the icon-bar. 2. Click SELECT over the colour white (colournumber 0) 3. Reduce the amount of red by one unit. 4. Reduce the amount of green by one unit. You may want to save this palette to a convenient spot (the Library-directory perhaps?) on your boot-disk and include the filename into your !Boot file. Thus, these settings will be loaded whenever you start your computer. NOTE, however, that this does not work on 256 colour modes because a different method of colour selection is used here. * If you discover any bugs or if you encounter difficulties which you cannot solve or if you have any questions, the authors would greatly appreciate hearing from you. It is our policy to give users all the support that we can give. Keep in mind that more (clearer) information supplied to us increases your chances of satisfaction. If you send us a disc containing the offending MDF, MDS or utility and a clear description (maybe even a log-file?) of the problem we will most certainly try to solve your problem. Since we only have a low budget; including some stamps (or cash to buy them) will guarantee you the return of your disc. Error messages ~~~~~~~~~~~~~~ The error messages produced by !UniMode or one of the utilities are generally self-explanatory. If an error occurs the programs will try to indicate what is wrong. Below you will find a list of all the error messages that are generated by the programs themselves. (i.e. NOT the error messages produced by BASIC or the Wimp and reported THROUGH these programs.) Where necessary an explanation of the error message is given. Source: icon bar front-end * To save, drag the icon to a directory viewer! * Can't handle more than one file at a time. (Enter a mode-number or close the window) * Fatal error in UniMode. Must exit immediately. = If you encounter this error-message then you have a copy of the ▀-version. Update to a later version. * Not a ModeDescriptionFile * Mode number must be less than 128! * Mode number must be greater than or equal to 0! * Filename too short. (Must be at least 1 character) * Filename too long. (Must be 10 characters or less) = A filename can not be longer than 10 characters. The path need not be included here. Once you drag the icon to a directory-viewer the program will know where to put the file. Source: CompileMDS Errors from BASIC reported through this program can be recognized by the inclusion of the text "(from 'CompileMDS')". The program can report three kinds of errors: 1. Fatal RunTime error. This error is usually caused by BASIC. If the error was caused by the EVAL function then the compiler will try to show where it went wrong. 2. FATAL ERROR. This error is generated by the compiler when it can not finish the compilation. Here too the compiler will try to give a hint as to what is wrong. 3. WARNING. This error is generated by the compiler. The compiler will not abort the compilation because the circumstances that caused this error might have been created on purpose. Nevertheless, you should take a look at the log before using the MDF. Some of the errors below are merely listed, because they CAN be generated by the program. Generally, other errors will occur before these can be triggered. Nevertheless, they are still in the program because of "Murphy's Law". * Unknown variable ( <Var> ) in line <line#> : '<line>' = This indicates a spelling mistake. The variable or registername <Var> could not be matched. * No .END encountered * Variable <Var> is not valid in this list. Line <line#> : '<line>' = The variable/register <var> does not belong in the current list. You have probably added a VIDC register in the WorkspaceList or a Mode Variable in the VIDCList. * MachineSpecs MUST be defined! (Can't live without 'em) * Can't have a WorkspaceList without a VIDClist. (At least specify BASEMODE) * Can't have a VIDClist without a Workspacelist. (At least specify BASEMODE) * BASEMODE must be defined in VIDClist * BASEMODE must be defined in WorkspaceList * Can't proceed. No bpp-defined. = This error should not occur since the bpp-setting is derived from the BASEMODE. * Size count error = This means that the amount of memory allocated for the compilation of the file is too large. It indicates possible duplicate register or variable assignment(s). Check the MDS to see if you used the same variable or registername more than once. * Conflict in bpp-setting! = The number of bits per pixel are defined via: 1. the BaseMode of the VIDClist 2. the BaseMode of the WorkspaceList 3. the Control Register (CR) 4. the value of NColour 5. the value of Log2BPP All must result in the same bpp-setting. * This does not fit in the register! (Line <line#> : <line> ) = The value being programmed into a register can only be 10 bits wide (after conversion). Refer to the paragraph entitled 'VIDC Registers' in the Programmer's Guide for details about maxima and minima. * Can't EVALuate parameter ( <parm> ) in line ( <line#> ) : <line> = The offending parameter <parm> in line <line> has caused BASIC's EVAL function to fail. The error message from BASIC is included in the log. This will generally clarify the problem. * Can't EVALuate parameter ( <parm> ) in line ( <line#> ) with formula ( <formula> ) * This is not a ModeDescriptionFile * BaseMode does not exist on this machine. = The BaseMode specified is not supplied by the OS version on your machine or your machine has been configured for a monitortype that does not support this BaseMode. * BaseMode should not be a soft-mode. = The BaseMode specified DOES exist. But it is claimed by a module in RAM. Remove the module by '*RMKill'-ing it and try again. RISC OS does not allow, the use of soft-modes as BaseMode. * Can't establish type of connected monitor = For newer versions of RISC OS the monitortype can be configured as "Auto". In such a case the computer tries to 'sense' what kind of monitor is connected. At the moment of this release we did not know how to find out the monitortype in such a case. If you DO know, please let us know. This does not affect the compiler in any way. It is just a message from the compiler that it can not check whether the mode can be displayed on your monitor. * Configured monitor is not in the .MachineSpecs = The monitor for which your machine has been configured has not been specified in the list MachineSpecs. This means that the mode MAY not display correctly on your monitor. Try and find out. * HSWR should be : <val> or greater. = The minimum value of HSWR is calculated by the compiler. Refer to the paragraph "Notes on designing your own mode" * HBSR should be : <val> or greater. = The minimum value of HBSR is calculated by the compiler. Refer to the paragraph "Notes on designing your own mode" * <reg1> can not be greater than <reg2> or <reg2> was not defined. * value assigned to <reg> must be even. * value assigned to <reg> must be odd. * The width of the display (HDER-HDSR) should be a multiple of 8 pixels. * (HDER-HDSR) must be equal to (XWindLimit+1) * The height of the display (VDER-VDSR) should be a multiple of 8 pixels. * (VDER-VDSR) must ve equal to (YWindLimit+1) * Minimum required screenmemory : <val> = Make sure that the value assigned to ScreenSize is equal to / (HDER-HDSR) * (VDER-VDSR) * 2^BitsPerPixel \ ( ------------------------------------------ +255 ) AND &7FFFFF00 \ 8 / This does not apply in certain situations (e.g. Teletext Modes) * VSWR must at least be 1. * LineLength should be : <val> * Wrong definition PR = PR (means PixelRate) must be programmed with 8, 12, 16 or 24 * Wrong definition BPP = BPP (means BitsPerPixel) must be programmed with 1, 2, 4 or 8 * Wrong definition DR = DR (means DMARequest) must be programmed with 0, 1, 2, 3, 4, 5, 6, 7 or 8 Source: Expand / ExpandAll Errors from BASIC reported through these programs can be recognized by the inclusion of the text "(from 'Expand')" or "(from 'ExpandAll')". * Not A ModeDescriptionFile * *** Warning *** Unsupported VIDCList ! = The programs are all compatible with RISC OS 2. The VIDClist-version is always '0'. If, in the future, other VIDCs are introduced, they may require a different VIDClist and hence have a different VIDClist-version. Re-compiling such modes MAY not give the desired effect. * *** Warning *** Unsupported WorkspaceList ! = The programs are all compatible with RISC OS 2. The WorkspaceList-version is always '0'. If, in the future, other VIDCs are introduced, they may require a different WorkspaceList and hence have a different WorkspaceList-version. Re-compiling such modes MAY not give the desired effect. * ;DATA &xxxxxxxx ;This is unrecognised VIDC data = If the program encounters data which it cannot translate it will include the raw (unprocessed) data into the MDS as a comment. In such a case you can try to find out what the data means. This is therefore not a real error message as it is only reported in the MDS. Bibliography ~~~~~~~~~~~~ Books for further reading: - RISC OS Programmer's Reference Manual (Acorn Computers Ltd.) - Acorn RISC Machine Family Data Manual - The 32-bit RISC Microprocessor System - (Prentice Hall) Acknowledgements ~~~~~~~~~~~~~~~~ Special thanks are due to (in random order) : - Acorn Computers Ltd., Cambridge UK - Velobyte CV., Rotterdam NL - B. Bles, Woerden NL - E. DorrΘ, NL - FKW & ETJ v/d Pol, Hoeven NL - VLSI Technology Inc., San Jose USA - Prentice Hall International Ltd., London UK - J.P. Hendrix, Dongen NL - M. Hendrix, Tilburg NL Ho! Ho! Ho! to the bottle I go To heal my heart and drown my woe. Rain may fall and wind may blow, And many miles be still to go, But under a tall tree I will lie, And let the clouds go sailing by. J.R.R. Tolkien