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+'.
    
SYSTEM REQUIREMENTS

    Pentium II with modern graphics card.

    Windows '95 or later.

    Sound card required for sound.

    DirectX8 recommended; DirectX3 required.

    The DirectX3 version is intended for people who run Windows NT4
    with Service Pack 3 or better. It is the same as the DirectX8
    version except that the emulator cannot trap all keypresses. The
    Windows keys, Alt and F10 will all have their usual Windows meaning
    rather than being available for the emulator. (By default, keypad 0
    doubles as F10.)
    
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.

FILE MENU

    Quickstart
    
        See the Quickstart section.
        
    Drive 0
    Drive 1
    Drive 2
    Drive 3
    
        See the Drive Menus section.
        
    Exit
    
        Exits program.
    
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!

    Internally it maintains a list of directories it looks in to find
    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).

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
            
    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.)
        
    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.

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 won't run faster than a real one.
        
    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. If you are having speed problems, it should
        run much faster too.
        
        For various reasons, the full screen resolution is fixed at
        800x600 in 256 colours. Should this mode be unavailable, the
        emulator will do a pseudo full screen using the desktop
        resolution. This looks reasonable, but provides none of the
        speed benefits.
        
        To leave full screen mode, use Alt+Tab. (As far as I can tell,
        this is the only key combination the emulator can't override.)
        
        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 or pseudo full
        screen modemode.
        
        Single
        
            Normal height graphics.
            
        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" is faster, though if you have a reasonably modern PC
        there should be no difference if you are 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.
        
    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. You can select the OS ROM too.
        
        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.

        (Note: there's a bug, you'll need to resize the ROMs dialog
        first time you see it. The position is then saved.)

    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. 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.
        
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.
    
ADVANCED OPTIONS

    There's no UI for these. I don't envisage them being changed as
    often. They can be found in "beeb.ini", which is arranged like a
    normal Windows INI file.
    
    Misc/Model
    
        Model of computer. You have 2 choices:
        
            b
            
                BBC Micro model B.
                
            b+
            
                BBC Micro model B+.
                
        Specifying 'b+' gives you a B+ with 64K. To get a BBC B+128,
        you must emulate an unauthorised home upgrade :) -- simply
        specify 4 slots of sideways RAM in the ROMs section.

    Misc/DiscInterface
    
        Disc interface type. You have 5 choices:
        
            acorn1770
            
                Acorn 1770 board, as used in the B+ and (probably) BBC
                B. I've been testing it with the 1770 DFS 2.10 ROM.
                
            opus1770
            
                Opus 1770 board. I've been testing it with the Opus DDOS
                3.45 ROM.
                
            chal256
            chal512
            
                Opus CHALLENGER "3 in 1", with 256K or 512K for RAM
                disk. I've been testing it with the Opus Challenger 1.01
                ROM.
                
            watford1770
            
                Watford 1770 board. I've been testing it with Watford
                DDFS 1.54T. You'll need this if you have any 62-file
                discs; this was a Watford-specific format, and won't
                work with any other DFS.
                
        Don't forget to load the DFS ROM appropriate for the disc
        interface!
        
    Sound/LenFrames

        Length in frames (1/50th sec) of the sound buffer. This
        determines the latency of the sound, and also how quickly the
        buffer must be filled to prevent crackles and pops. The longer
        the buffer, the greater the latency but the smaller the
        likelihood of crackles and pops.
        
        The default is 4.
        
    Video/FrameSkip
    
        (This should really have a menu option.) Every (1/FrameSkip)th
        frame is drawn. The others are just discarded. This can make the
        emulated computer run faster at the expense of a jerkier
        display.
        
        Internally, the frames are still drawn, but they are neither
        converted nor displayed. This may or may not provide a
        significant speedup -- whilst converting each graphics frame for
        display is the most time-consuming part of the emulator, there's
        still a load of other stuff going on...
        
        (By the way, FrameSkip is a misnomer -- sorry.)
        
    Video/CleanupFrequency
    
        Every CleanupFrequency frames, the screen is erased before being
        redrawn. Increasing this value decreases the amount of time
        spent doing this, but means changes in screen parameters can
        leave garbage in the window until the display is next cleaned.
        
        A CleanupFrequency of 1 gives the nicest display. Try Bugeyes
        II with and without!
        
        The default is 100, or once every 2 emulated seconds.

    Video/Width
    Video/Height
    
        Specifies 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 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.
        
    Video/FullScreenHz
    
        Refresh rate for full screen mode. Make sure it is one your
        graphics card and monitor will support! The default of 0 means
        DirectDraw will use a default refresh rate. If your monitor and
        graphics card support one of 75Hz or 100Hz, you may find the
        display looks nicer.
        
        Setting this to an unsupported refresh rate may prevent full
        screen mode from working, or give you a garbled display, or
        cause your monitor to switch itself off, so take care. (But if
        this should happen, you should be able to get out of it using
        Alt+Tab.)
    
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.
        
    -mount0 FILE
    -mount1 FILE
    -mount2 FILE
    -mount3 FILE
    
        Mounts a disc in the specified drive.
        
    -autoboot
    
        Autoboots the BBC when it starts. The emulator pretends SHIFT is
        held down until the disc is first accessed. (This is how
        Quickstart works too.)
        
    -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.
    
EMULATED HARDWARE

    6502 CPU

        All legal instructions emulated, and hopefully correctly too!
        The illegal instructions are supposed to work as they did on the
        Beeb's CPU. There's still a bit of work to be done, but the
        commonly used illegal instructions seem to work OK.
        
    Video system

        It should correctly handle all the usual Beeb stuff, and also
        split palette, split mode, vertical rupture, smooth scroll and
        screen positioning.

        There's a few Lars 0sterballe demos that don't look like they
        work properly, and screen positioning isn't _quite_ right. Most
        games seem fine though.
        
    6522 VIA

        Still some bugs (I should think!) but timers are accurate and
        timer based decryption should work. Shift register and
        associated features are not supported.
        
    1770 FDC

        Read track and write track commands are not supported, the
        Reset command isn't fully supported, the timing is totally
        wrong, and there will be some bugs still.
        
    ADC/Serial/Econet/Tube/Speech/etc.

        Not emulated. Sorry!
        
    B+ extra features
    
        I don't think the shadow RAM _quite_ works the same as on a real
        B+. (Without a real B+ to test it with, it's a bit hard to
        tell.) Any side-effects of this will be only cosmetic.
        
        32K ROMs aren't supported. You'll have to split the file and
        load each half separately. A side effect of this is that the
        ROMs can be used more freely than in a real B+; slots 14 and 15
        don't have to both contain BASIC, and slots 0 and 1 can be
        filled.
        
COMING ATTRACTIONS

    Better compatibility.
    
    Speech! fixed in stereo.

    UI for more of the Advanced options.

    Joystick support.
    
    Master 128 emulation.
    
    Proper B+128 support -- will set up sideways RAM for you
    automatically.
    
    Super fastforward disc load. Like the existing one, but additionally
    feeds data to the CPU as needed rather than in an
    evenly-timed stream. Should give an extra 3-4x speedup (on top of
    the existing one) depending on how the DFS is written!
    
BUGS AND MISFEATURES

    An ever-growing list.
    
    USABILITY

        First time you run program, ROMs dialog comes out as small as it
        gets and you have to resize it.
        
        The monitor type setting is not saved between runs. The emulator
        always starts up in colour mode.
        
        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.
        
    COSMETIC

        Speech! and samples don't work with stereo sound.
        
        Some modes are not properly centred.
        
        Cursor is wrong after *TV255.
        
    FULL SCREEN
    
        Sometimes screen isn't redrawn properly behind the popup menu.
        
        The emulator is perhaps over eager in leaving full screen
        mode...
        
    DISC SYSTEM NOTES
    
        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.
         
        Unfortunately, double density mode is not (yet) supported.
    
INCOMPATIBLE GAMES

    I'm keeping a list here:
    
    Skirmish
    
        Screen whacked, game unplayable. Same on BeebEm.
    
    Stix
    
        Key response odd, you always move right if possible! Same on
        BeebEm.

    Sphere of Destiny
    Sphere of Destiny 2
    
        Screen a bit broken, game playable though. Works fine on BeebEm.
    
    Pedro
    W.A.R.
    
        Game hangs when loaded. Annoyingly, both of these used to work!
    
    Check out 'compatibility.csv' -- it's a spreadsheet (that should be
    comprehensible in a text editor) containing my experiences with a
    number of Beeb games. This is now extremely out of date, and needs
    updating. I haven't had the inclination (to be honest!) to play my
    way through all 250+ games again.

OTHER NOTES

    WXWINDOWS

        I used the most excellent wxWindows 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.wxwindows.org/
    
    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 minimize the effect, either use full screen mode, or set
        windowed scanlines mode to double and select 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://www.tomseddon.plus.com/beeb/beeb.html
        
    Problems/praise, send me your thoughts. Feedback will influence this
    program's development!

        bbc@tomseddon.plus.com

    I'm interested to hear about games that don't work.
    
    Please let me know if the emulator crashes or does anything
    untoward.
    
AND NOT ONLY... BUT ALSO
    
    Thanks to Bill Carr, who suggested features and did some testing.
    
    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.
    
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-2003.
    
    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.
