The Datafile PD-CD 5

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

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / u / unimode2 / !UniMode2 / Manuals / PRM < prev next >

Wrap

Text File | 1994-05-30 | 21.0 KB | 541 lines

Programmer's Guide ~~~~~~~~~~~~~~~~~~ The ModeDescriptionScript (MDS) Use of Constants and FuNctions The ModeDescriptionFile (MDF) Hints and Tips The ModeDescriptionScript (MDS) =============================== Constant Declarations Machine Specifications VIDC Registers Mode Variables Finalisation If you wish to design your own soft-mode you can do so by creating an MDS. The structure of the MDS must comply with the following 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 script is sub-divided into 4 sections called lists. Each list is headed by a card identifying it. Here are the lists: * Constant Declaration. You can declare up to 16 constants to be used in the script later. * Machine Specifications. This is used to specify the monitortype for which the mode is suitable and how the VidcEnhancer is to be used. * VIDC Registers. Here you can define the values to be programmed into the VIDC registers. * 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("..."). Next follows a list of keywords that can be used within the quotation-marks, and 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 set at 8, 12, 16 or 24. When the VidcEnhancer is switched on, these rates will be 50% higher. It is NOT possible to set PixelRate at e.g. 36. A pixelrate of 36 MHz can be obtained with PixelRate at 24 and 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 are recommended to 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(" ... "). The list of keywords that can be used within the quotation-marks, with their meaning follows. Between brackets an abbreviation for that keyword is given. 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".