model-b -- a BBC emulator for Windows

  INTRODUCTION

    This program emulates the BBC Micro, an 8-bit 6502-based home computer
    manufactured by Acorn Computers Ltd. in the early 1980s. This program
    can emulate a BBC model 'B' or the later BBC model 'B+'.

    model-b is designed primarily for playing games, but it is perfectly
    capable of running other software too.

  SYSTEM REQUIREMENTS

    Pentium II with modern graphics card.

    Windows '95 or later.

    Sound card required for sound.

    DirectX8 recommended; DirectX3 required.

    DIRECTX 3

      There is a DirectX 3 version for people who run Windows NT4 with
      Service Pack 3 or better. (It will run on any other modern version
      of Windows as well.)

      The DirectX 3 version is slightly limited. The main limitation is
      that the emulator cannot trap all keypresses. This means the Windows
      keys, Alt and F10 will all have their usual Windows meaning rather
      than being available for the emulator. (F10 is the default key for
      the BBC's f0. As a convenience, keypad 0 is by default set up to be
      f0 as well, so you won't lose out. All other Beeb keys are
      accessible.)

      In addition, the DirectX 3 version does not support joysticks.

  INSTALL

    Unzip to the directory of your choosing.

    Double click the EXE file. Everything you need to get started is
    supplied. The window with the familiar "BBC Computer 32K" should
    appear straight away.

    The default settings are for a BBC Model B with an Acorn 1770 disc
    interface, with OS 1.20, BASIC 2 and Acorn DFS 2.26.

  GETTING STARTED

    You're advised to read this manual in its entirety. But it's pretty
    easy to get started. If you've never used a BBC before, or can't
    remember how, you can start playing games by following these simple
    steps:

    1. Visit The Stairway to Hell (http://www.stairwaytohell.com) and
       download some games from the Disc Images section.
    2. Unzip games into the directory of your choice.
    3. From the emulator, select Quickstart on the File menu.
    4. Click 'Add dir', select the folder containing the games, and
       click OK.
    5. The list should now contain the games you downloaded. Double
       click one and start playing.

  FILE MENU

    Quickstart

      See the Quickstart section.

    Drive 0
    Drive 1
    Drive 2
    Drive 3

      See the Drive Menus section.

    Exit

      Exits program.

  QUICKSTART

    (Discs must be auto-bootable to work with Quickstart.)

    Presents a list of available games. Double click one (or select and
    hit OK) to have the disc inserted in drive 0 and Shift+Break
    simulated. Makes running games dead easy!

    model-b keeps a list of directories that it looks in to find the
    games. You can add to this list with the 'Add dir...' button, and
    remove directories with the 'Remove dir...' button. It searches these
    directories recursively.

    As a convenience, Quickstart will attempt to find single sided disc
    images that are part of a pair. Each pair will have one entry in the
    Quickstart list; when selected, both drives 0 and 2 will be loaded.

    Two files are paired if they are in the same directory and if one ends
    in '0' or 'A', and the other ends in '2' or 'B' respectively,
    separated from the rest of the name by '-' or '_'. Only the name of
    the disc for drive 0 appears in the list. It is followed by (DS).

    To perform the autoboot, the emulator pretends SHIFT is held down
    until the disc is first accessed or until a key is pressed. (The
    latter is to prevent problems if the boot file doesn't run for some
    reason.)

    The emulator doesn't support ZIP files (at least, not currently), so
    if you've downloaded games as ZIP files you must unzip them before
    Quickstart can find them.

  DRIVE MENUS

    Load

      Loads a disc into the given drive. The disc type is given by its
      extension:

      * .ssd - Single sided, single density
      * .bbc - Single sided, single density
      * .img - Single sided, single density
      * .dsd - Double sided, single density
      * .adm - Single sided ADFS
      * .adl - Double sided ADFS
      * .sdd - Single sided, double density
      * .ddd - Double sided, double density

      Double density support is experimental!

      (As with Quickstart, ZIPped games aren't supported -- you must unzip
      the disc images first.)

    Save

      Saves to disc any changes you have made. The disc is expanded to 80
      tracks when you do this. (The extra tracks are just empty and
      unused, if it's a 40 track disc.)

    Save as...

      As "Save", but allows saves the disc under a new filename. The new
      disc image will have the same number of sides as the loaded image.

    Unload

      Ejects the disc from the drive.

      A double sided disc takes up two drives. You can load a double sided
      disc from either side. Whichever drive it's loaded from, if a double
      sided disc is in a drive the bottom drive of that pair (2 or 3) is
      disabled and the top drive (0 or 1) is used to save or eject the
      disc. To load a double sided disc, both drives must be free.

    ADFS discs are assumed to have 16 sectors per track.

    Double density discs (SDD or DDD) can have either 16 or 18 sectors per
    track. The exact format is determined from the file size, according to
    this table. Only disc images with an extension and file size in this
    list are valid double density images.

    The disc format is given as (sides) x (tracks) x (sectors per track).

    * .sdd, 160K - 1 x 40 x 16
    * .sdd, 180K - 1 x 40 x 18
    * .sdd, 320K - 1 x 80 x 16
    * .sdd, 360K - 1 x 80 x 18
    * .ddd, 320K - 2 x 40 x 16
    * .ddd, 360K - 2 x 40 x 18
    * .ddd, 640K - 2 x 80 x 16
    * .ddd, 720K - 2 x 80 x 18

    Double density support is experimental!

  OPTIONS MENU

    Show status bar

      Toggles display of the status bar. The status bar shows the current
      speed of the emulated BBC (with 2.00MHz being exact BBC speed) and
      some indication of what the disc drives are currently doing.

    Sound enabled

      Toggles sound on or off.

    Limit speed

      If checked, the emulated BBC will run at the same speed as a real
      BBC. Otherwise, it will run as fast as it can.

    Fast forward disc access

      If checked, when accessing the disc the emulator will switch off
      speed limiting (if enabled) and introduce a frame skip of 50. This
      effectively increases the loading speed. (On my PC it goes about 11-
      13MHz, or about 5-6x real speed.)

      Once the disc access stops, the emulator snaps back to normal speed.

      To ppppprevent confusion, the emulator won't fast forward while BBC
      keys other than SHIFT and CTRL are pressed.

    Full screen

      If checked, emulator will run in full screen mode. Full screen mode
      looks better. Additionally, if windowed mode runs too slowly, full
      screen mode should solve your problems.

      The full screen resolution is fixed at 800x600 in 256 colours.
      Select the refresh rate using the Video option on the Options menu.
      If full screen mode can't be set up, the emulator will remain in
      windowed mode.

      The emulator won't leave full screen mode other than by Alt+Tab.
      (Ctrl+Alt+Del on Windows 2000, XP and NT should also do it, but the
      emulator cannot detect this happening. Depending on your system,
      this may leave the display in a strange state.) For best results,
      tap Alt+Tab briefly -- keeping Alt held can give strange results. (A
      bug I intend to fix eventually.)

      The menu bar is hidden in full screen mode. Use the right mouse
      button to access it.

    Windowed scanlines

      Selects the scanlines effect for windowed mode.

      Single

        Normal height graphics.

      Interlace

        Fake "interlace". The effect is quite extreme.

      Double

        Double height graphics. If your graphics card is smoothing the
        output, and you don't like it, you can use this option and select
        the largest window size from the Resolution submenu to get
        unsmoothed output. (If you make the window any larger, though, it
        will be stretched by the graphics card.)

      'Single' and 'Interlace' are the fastest, and about the same speed.
      'Double' will be slightly slower. But if you have a reasonably
      modern PC, there should be no difference when using 'Limit speed'.

    Full screen scanlines

      Selects the scanlines effect for full screen mode.

      Scanlines

        The typical scanlines display as seen in other emulators. Leaves a
        gap between each line.

      Interlaced scanlines

        As 'Scanlines', but alternate frames are drawn 'in the gaps'. This
        generally gives solid-looking pixels but moving things can
        sometimes look rather odd. (For example, Mission Impossible,
        Rocket Raid and Frak.)

      Double

        Doubles each line, giving solid-looking pixels.

      'Scanlines' and 'Interlaced scanlines' are the same speed; 'Double'
      is slower. Again, unless your PC is approaching the bottom end of
      the required scale you shouldn't have any problems with either mode.

    Keymap

      You can select the keymap used from the popup menu.

    Resolution

      Select the resolution from the popup menu.

    Screen type

      Select the monitor type. This changes the palette used to display
      the BBC screen.

      The monitor type is ignored in in windowed mode on a 256-colour
      display.

    ROMs

      Allows setting of contents of ROM slots. Slots with no file contain
      nothing in particular. A slot contains sideways RAM if the 'RAM'
      checkbox is ticked. Sideways RAM can still have files loaded into it
      on startup.

      If the current hardware configuration includes slots that are
      specifically ROM or RAM (currently only B+96K and B+128K, which have
      sideways RAM), the  corresponding slots' RAM status cannot be
      changed.

      You can select the paged ROM slot that contains the DFS ROM. This is
      used by the Hardware dialog to change the DFS ROM automatically when
      the disc interface is changed.

      Click 'OK' to save changes -- they will take place next time the BBC
      is hard reset. Alternatively, use 'Apply (Reset)' to save changes
      and do a hard reset straight away.

    Sound

      Allows configuration of sound parameters.

      The mute left and right options can be used for mono as well as
      stereo. By muting a channel on both left and right speakers it will
      not be heard in mono.

    Keymaps

      Configure keymaps here. Click on a BBC key, and the list of PC keys
      that 'press' that BBC key will appear. Press PC keys to toggle their
      presence in the list. You can also bind joystick button presses and
      axis movements to keys.

      Click OK to save changes, or Cancel to abandon them.

      In the main dialog, click 'Load...' to load a new keymap or
      'Save...' to save the current one. Click Close when done.

      Changing keymaps in the dialog won't change the currently selected
      keymap. If you edit and save over the currently selected keymap, it
      will of course change straight away.

    Hardware

      Select the disc interface to use and the BBC type.

      Each BBC type has a slot for the OS ROM. Types that are sufficiently
      similar (currently B and B with Watford ROM board) share the OS ROM
      setting.

      If you have selected an FS slot in the ROMs dialog, and select a ROM
      file for a disc interface, selecting this interface here will cause
      the FS slot to be overwritten with the corresponding ROM.

      Use the '...' buttons to select a file rather than having to type in
      the name.

      If the filename is blank, there will be no ROM loaded. Not loading
      an FS ROM is fine; not loading an OS ROM will (perhaps obviously)
      cause the computer to fail to boot.

    Joysticks

      You can enable either or both of the BBC's joysticks. Select the
      joystick you would like to use for each port, which axes correspond
      to the BBC X and Y axes and which button corresponds to fire.

      If you're using a pad with 2 sticks, such as a Hammerhead or a PSX
      pad, the right hand stick will probably be X rotation (X axis) and Z
      rotation (Y axis). You can check in the Gaming section of the
      Windows control panel.

      POV hats are treated as digital directional pads and are mapped to
      the joystick X and Y axes. North is mapped to up.

    Video

      Buffer

        Specify width and height of the emulated screen. The default,
        640x272, should be suitable for most things. If you need the
        screen wider or taller, increase the values. (For example, Boffin
        has a wider screen.)

        The minimum size is 640x272, and the maximum is 800x312.

        (The BBC generally only displays up to 256 lines on the screen.
        The extra lines are to allow for games that move the screen up and
        down for effect.)

        The emulator will run more quickly with a smaller screen, but if
        limit speed is checked this should be noticeable only on slow PCs.
        This slowdown is more pronounced in windowed mode.

      Full screen

        Refresh rate for full screen mode. The ones supported by your
        graphics card are listed. Select "Default" to let Windows choose.

        The emulator can also sync its full screen display to the monitor
        refresh rate, to prevent 'tearing' of the display. To activate
        this, select "Sync to refresh rate". (This will work well with any
        refresh rate above 70Hz, but gives poor results with 60Hz.)

        The BBC Micro refresh rate is 50Hz, so for best results use a
        refresh rate that is a multiple of that, but 75Hz also works well.

      Options

        Cleanup frequency

          How often to clear the emulated display completely. This is
          necessary after the screen size changes, otherwise the old
          contents will be left in the new borders. Increasing this value
          may speed the emulator up very slightly.

        Display frequency

          How often to update the emulated display. Increasing this value
          can speed the emulator up, but makes the BBC display appear
          jerky.

        Both frequencies are measured in frames. 1 is every frame, 2 every
        other frame, and so on.

  SPECIAL MENU

    Start recording sound
    Stop recording sound...

      Starts and stops the recording of sound data. Starting recording
      sound will clear the recording buffer and start recording. Stopping
      recording will bring up a file selector allowing you to select the
      file to save the data to.

      The sound data is saved as a .VGM file. This may be played in Winamp
      with a suitable plugin.

    Save screenshot...

      Saves a screenshot to disc. Type in file name (including extension,
      which is used to determine the file type) or select file to save to.
      Supported types are:

      * .bmp - Windows bitmap
      * .jpg - JPEG
      * .png - PNG
      * .pcx - PCX
      * .tif - TIFF
      * .xpm - X pixmap

      One note -- if you are using frame skip, the screenshot saved will
      be the current 'real' frame, rather than just the one being
      displayed.

  STATUS BAR

    The status bar has a volume control for the sound output.

    It also has four status indicators, one for each drive. You can load a
    disc by dragging the file from Windows Explorer onto the relevant
    indicator. This is equivalent to doing File|Drive N|Load disc...

    The status bar also shows the current effective speed in MHz (with
    2.00MHz being exactly the same speed as a real BBC), and the size of
    the BBC display.

  COMMAND LINE OPTIONS

    -inifile FILE

      Loads configuration from the file FILE. By default, the file
      "beeb.ini" is used.

      If the specified file (or indeed "beeb.ini") doesn't exist, the
      emulator will start up with a default set of options and save a new
      set when you exit.

    -inioverride FILE

      After the INI file has been loaded, any file(s) specified by
      -inioverride parameter(s) are loaded. Any settings present in these
      override those used in the main INI file.

    -selectini

      Loads configuration from a file selected by the user. The program
      will list all files with an "ini" extension in the current
      directory. Select 'Cancel' to exit before the program starts.

    -mount1 FILE
    -mount2 FILE
    -mount3 FILE
    -mount0 FILE

      Mounts a disc in the specified drive.

    -autoboot

      Autoboots the BBC when it starts. This works the same way as the
      Quickstart feature.

    -inisave STATE

      STATE should be "on" or "off", indicating whether the INI file, as
      specified by -inifile or as defaulted, should be saved when the
      emulator exits.

    -inisave is provided as a means of overriding the defaults, which I
    hope are sensible. Without any -inisave used, if no -inioverride was
    specified, the INI file _will_ be saved on exit; if any were
    specified, it won't be. (This is to prevent leakage between files.)

    -selectini takes precedence over -inifile; if you use -selectini, any
    -inifile you specify is ignored.

  BBC MODELS

    model-b can emulate three different types of BBC computer.

    Model B

      The standard BBC model B. It is slightly enhanced, having 16 ROM
      slots, any of which may be sideways RAM.

      Sideways RAM works in the Master fashion: a slot may be written to
      only when paged it via the ROM select register at &FE30. The
      supplied Acorn DFS has a *SRLOAD command to allow the loading of
      ROMs from disc, if you need to do that.

    Model B with Watford ROM board

      A standard BBC model B with a Watford ROM board. Any ROM slot may be
      sideways RAM. The RAM is written to by writing any address in the
      &8000-&BFFF range. This means one may load ROM images using *LOAD,
      for example. The slot that will be written in this way is selected
      by writing any value to &FF30+N, where N is the ROM slot.

      Unlike a real Watford ROM board, any slot may contain RAM. However,
      software may expect only slots 0-7 and 14 to be sideways RAM.
      (That's what the manual says are the available slots; I've never
      used this device in real life.)

    Model B+
    Model B+96
    Model B+128

      A BBC B+ with 64K, 96K or 128K. Unlike a real B+, the ROMs may be
      freely set. (A real B+ is slightly limited in this regard; I believe
      BASIC always occupies a particular slot.)

      The 96K and 128K models have 2 and 4 banks of sideways RAM
      respectively. One thing to note about these models is that the
      startup message will only reflect the extra memory when using Acorn
      DFS 2.26. This is the one you'll get by default when using the Acorn
      1770 disc interface.

  COMING ATTRACTIONS

    Better compatibility.

    Master 128 emulation.

  BUGS AND MISFEATURES

    USABILITY

      If you have only a 4MB graphics card (or a 8MB graphics card at
      1600x1200x32bpp) you might see some odd behaviour due to the
      emulator running out of video memory. This should not affect full
      screen mode.

      Once you have selected a FS ROM slot, you can't unselect it. Also,
      you can't change disc interface without resetting the BBC. I don't
      consider either of these a major problem...

    FULL SCREEN

      Sometimes screen isn't redrawn properly behind the popup menu.

      Alt+Tab doesn't work particularly well in full screen mode.

  DISC SYSTEM NOTES

    Double density support is experimental!

    The disc system has been tested by doing *BACKUP and doing a binary
    compare on the resulting disc images. Judging by this, it works
    correctly. If the emulator should corrupt a disc (but I think this
    unlikely) then don't fret, either just unload the disc without saving
    it or back up the disc you've loaded before saving the new (corrupted)
    copy. Nothing gets written to disc unless you ask.

    There's not currently any support for creating blank discs. You have 3
    options:

    1. Copy an existing disc image and format that using a DFS.
       Formatting discs isn't actually emulated, but the important bit
       (where the DFS creates a new, blank catalogue) does work.
    2. Copy an existing disc image and use *WIPE or *DESTROY to
       delete the files.
    3. Make a copy of 'blank.ssd' or 'blank.dsd' and use that.
       These are 80 track disc images supplied for your convenience.
       There's nothing special about them; I just created them using
       BBC Explorer.

  OTHER NOTES

    GRAPHICS FILTERING

      Your graphics card might filter the graphics when they are
      stretched. This gives them a rounded, softened or blurry look.
      Unfortunately (if you don't like it!) there's no way to turn this
      off from within a normal program. Your graphics card _might_ provide
      some way of doing this in the control panel.

      To avoid this effect, use full screen mode. In windowed mode, you
      can avoid it by setting the windowed scanlines mode to double and
      selecting the largest resolution from the Resolution submenu on the
      Options menu.

  WEB LINKS

    The Stairway to Hell: http://www.stairwaytohell.com/

    BBC games site.

    The BBC Lives!: http://bbc.nvg.org/

    General BBC site.

    The BBC Documentation Project: http://www.bbcdocs.com/

    Scanned and/or OCR'd BBC manuals, adverts and relevant datasheets.

    SMS Power, music section: http://www.smspower.org/music/

    Plugin to play VGM files in Winamp.

  CONTACT

    This program's official web page is currently:

    http://modelb.bbcmicro.com/

    Problems/praise, send me your thoughts. Feedback will influence this
    program's development!

    modelb@bbcmicro.com

    I'm interested to hear about games that don't work.

    model-b should never crash or hang up. Please let me know if you have
    any problems of this nature.

  AND NOT ONLY... BUT ALSO

    Thanks to Bill Carr, who suggested features and did some testing.

    Thanks to Dave Moore for providing web space at bbcmicro.com.

    Also thanks to everyone on the BBC Micro mailing list for technical
    help past and present. The programming is in general my own work, but
    the program would not be even half so good were it not for people
    who'd written other emulators or who have solved problems or
    discovered information etc. A list of such people would include, but
    should not by any means be considered to be limited to, the following:

    * James Fidell (Xbeeb)
    * David Alan Gilbert, Richard Gellman and others (BeebEm)
    * Tom Walker (B-em)
    * David Devenport (BeebInC)
    * Thomas Harte (Electrem)
    * Gregory Jeffryes (BBC driver for MESS)
    * James Bonfield (old emulator)
    * Richard Talbot-Watkins (misc technical info, it's why Uridium works)
    * John Kortink (soundchip noise info, it's why Planetoid sounds right)
    * Maxim (misc sound chip info, it's why Speech! works)
    * Michael Foot (BeebIt)

    If you should be on this list, let me know. You will not have been
    omitted through malice.

    WXWIDGETS

      I used the most excellent wxWidgets library for programming all the
      user interface stuff in this program. If you're a programmer, and
      you ever need to do stuff like that, go and visit its homepage:

      http://www.wxwidgets.org/

  LICENCE

    This licence does not apply to the whole archive. It applies only to
    those files making up the BBC emulator software, and not to any ROM
    files distributed with it.

    Copyright (C) 1996-2004 Tom Seddon, and (in places) others as listed
    in the NOT ONLY... BUT ALSO section.

    All rights reserved.

    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, and/or sell copies of the Software, and to permit persons
    to whom the Software is furnished to do so, provided that the above
    copyright notice(s) and this permission notice appear in all copies of
    the Software and that both the above copyright notice(s) and this
    permission notice appear in supporting documentation.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
    OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
    HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY
    SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER
    RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
    CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
    CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

    Except as contained in this notice, the name of a copyright holder
    shall not be used in advertising or otherwise to promote the sale, use
    or other dealings in this Software without prior written authorization
    of the copyright holder.

