home *** CD-ROM | disk | FTP | other *** search
- 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".
-
-