DOS Vectrex Emulator (DVE V0.04 - Beta)
------------------------------------------

Author: Keith Wilkins  (kwilkins@nectech.co.uk)


*********************************************************************

DVE is Copyright(c) 1995, 1996 by Keith Wilkins

This licence grants you the following:

Permission to use, copy, and distribute DVE in its entirety, for
non-commercial purposes, is hereby granted without fee, provided that
this license information and copyright notice appear in all copies.

If you redistribute DVE, the entire contents of this distribution
must be distributed.  The software may be modified for your own
purposes, but modified versions may NOT be distributed without prior
consent from Keith Wilkins.

This software is provided 'as-is', without any expressed or implied
warranty.  In no event will the author be held liable for any damages
arising from the use of this software.

If you would like to do something with DVE that this copyright
prohibits (such as distributing it with a commercial product, using
portions of the source in some other program, etc.), please contact
the author.

The author can be contacted via email at: kwilkins@nectech.co.uk

*********************************************************************


Vectrex EXEC ROM image Copyright(c) GCE 1983


*********************************************************************




Index
-----

1.0      Installation
  1.1      Game Images

2.0      Using DVE
  2.1      Screen flicker
  2.2      Default keys
  2.3      VECTREX.INI Settings

3.0      Emulator Development status
  3.1      MineStorm vector bug
  3.2      Misc history
  3.3      Speed gripes

4.0      With thanks to

5.0      Revision history





1.0 Installation
----------------

Unpack all of the files into the directory of your choice.

md c:\emu\dve
cd c:\emu\dve
pkunzip dve004.zip
del dve004.zip

This emulator should run on 386/486 machines but will run VERY slowly. The
emulator runs OK on a P60, slow but playable. On my P120 it runs like a
dream.

DVE does not use the Floating poing Co-Processor, it is all done in integer
arithmatic.



   1.1 Game images
   ---------------

I did not wish to supply DVE with any images because of the copyright issue,
I have only included the EXEC ROM as the one in the archive is corrupt and
I don't wish to have people hassling about the fact that the emulator doesn't
work when its the fault of a corrupt EXEC image.

The sources of games that I know of are:

A. ftp.csus.edu - /pub/vectrex/vectrex.tar.Z - Large collection of carts
                  /pub/dktower/dktower.zip   - Dark tower

   I have them converted into a ZIP file for easier access. I'll post
   them to the site maintainer for inclusion on the Archive.


B. http://www.texel.com/home/pcjohn/index.html
 
   PCJohn's new vectrex games Patriot & Vectrex Vaders are available
   from his site in the section regarding about vectrex game development.
   Patriot is SUPERB and well worth downloading





2.0 Using DVE
-------------

You can run DVE straight out of the "pack" by just typing VECTREX
and pressing return.

If you wish to use a particular game image then.

Usage: VECTREX <binary game image>

If you don't specify an image then the default image from vectrex.ini will
be loaded.


2.1 Screen flicker
------------------

If you experience bad screen flicker try editing VECTREX.INI and changing
the display_auto_refresh line to read:

display_auto_refresh=0

This will turn auto refresh off. When display_auto_refresh is set to
zero then the line marked:

display_update_period=30000

is used to set the frequency with which the display is updated. You should
not need to change this. If you do then the figures below will give some
idea of what to expect.


<5000  - Will give very very bad flicker

15000  - Acceptable image with some games, still bad flicker

30000  - Good stable image with most games

>60000 - Stable image but lots of vector trails, may abort emulator if
         the vector trails become too long.

When auto_refresh is set DVE will constantly adjust the display_update_period
value to what it thinks is most optimum, BUT the method I use is not suitable
for all cases, exceptions are Patriot & Spinball. The auto refresh has upper
and lower refresh limits defined in the INI file:

display_update_max=60000
display_update_min=7500




2.2 Default Keys (Changeable in VECTREX.INI)
----------------

A       Vectrex joypad 1 button
S       Vectrex joypad 2 button
D       Vectrex joypad 3 button
F       Vectrex joypad 4 button

Arrow keys are mapped to joystick left/right/up/down. Joystick is currently
configured as a digital device, this messes up some things i.e Etch-a-sketch.

If you wish to change the key bindings then this can be done in vectrex.ini
by altering the relevant key maps, these should be speficied as scan codes.


ALT-X   Exit the emulator
ALT-M   Invoke the debug monitor
ALT-R   Reset (Warm Start)
ALT-B   Reboot emulator (Cold Start)
ALT-P   Pause

ALT-F1  \
.       
.        - Reset emulator and run cartridge assigned to relevant key
.          (Cartidge list defined in VECTREX.INI
ALT-F12 /


If you enter the debug monitor and wish to exit, press enter before entering
any command as there is a bug in the keyboard driver that leaves unseen
junk in the buffer and the 1st command you type will always be rejected:

run     Restart the emulator and exit the monitor
quit    Exit back to DOS
help    Display command list




2.3 VECTREX.INI
---------------

Here are all the INI settings for those who wish to tinker:

debug_enable           0/1     Enable/Disable debug logging (Not available)
debug_monitor          0/1     Boot straight into the debug monitor

display_enable         0/1     Enable/Disable screen emulation

display_auto_refresh   0/1     Enable/Disable dynamic refresh estimation

display_update_period  int     Number of system ticks between display refresh

display_update_max     int     Bounding limits for auto refresh adjustment
display_update_min     int


display_line_period    int     Number of refreshes a line will survive
                               (Don't modify this)

display_mode           int     System resolution:
                                  0 - 640x480
                                  1 - 800x600
                                  2 - 1024x768

display_enhance        0/1     Setting to one will cause DVE to repair
                               any vector damage caused by undrawing
                               old vectors. This will cause slght
                               slowdown.

display_clipping       0/1     Setting to one will clip all vectors to
                               the edge of the vectrex display. Improves
                               the look of scramble, Pole position...

display_colour         int     Display colour 0-3 White,Red,Green,Blue

rom_image              string  Name of system rom file

rom_write_enable       0/1     Allows a program to write to the System
                               ROM area if set to 1. 

ram_image              string  Name of ram image file

default_cart           string  Name of default cartridge to run

cart_write_enable      0/1     If set to 1 allows a program to write
                               to the cartridge area.

cartridge01            string  Cartidge carousel files for F1-F12
cartridge02
cartridge03
cartridge04
cartridge05
cartridge06
cartridge07
cartridge08
cartridge09
cartridge10
cartridge11
cartridge12

player1button1         int     Key bindings. Use the scancodes for the
player1button2                 keys of your choice
player1button3 
player1button4 

player1up
player1down
player1left
player1right

player2button1
player2button2
player2button3
player2button4

player2up
player2down
player2left
player2right






3.0 Current Status
------------------

6809 Emulation is now complete, including IRQ and FIRQ functions.

Most games are now playable, unless they use the 3D imager, as I have no
info on this I can't make the emulator support it. There is still an
image offset problem on some games, notably Spinball & Clean Sweep. I
haven't tried to fix it yet.

NOTE: If anyone out there has information on how the 3D system works
then I'll attempt to emulate the 3D games (red/green glasses time)

Some people have complained that the emulator doesn't work and hangs at the
opening screen. This is NOT the case, the opening screen makes the emulator
work very hard due to the number of vectors on screen even on a P120 speed
drops off badly at this point, hence the programmed 4 second delay can
stretch out to 50 seconds on a really slow machine.

HINT: Press ALT-R at the reset scree, this will reset the emulator, by
      default the vectrex skips the opening screen on a warm reset.

The vectrex.tar.Z file contained in the csus.ftp.edu archives contains an
image of the vectrex system ROM (vectrex/binary/vecmon.com). DO NOT USE
THIS FILE WITH THE EMULATOR as it is suffering from the advanced stages of
bit rot and is badly corrupted. Many thanks to Marc Woodward for sending
me an uncorrupted system image.

Emulation speed:    P75  approx 30-50% actual speed.
                    P120 approx 50-90% actual speed

Emulation speed has a lot to do with the number of vectors present on
screen at a given time. I've put quite a lot of effort into optimising
DVE but alas I've failed my goal of 100% on a P60. There are more things
that can be done but its a law of diminishing returns.

It seems on some graphics cards the 800x600 mode doesn't work correctly
but I haven't figured out why.



3.1 Minestorm vector bug
------------------------

Thanks to those people who mailed me about the large vector occasionally
corrupts mine storm. I've traced this to a bug in the Mine Storm code.
If you fire and hit a fireball mine BEFORE the mine starts moving it
causes the mine drawing routine to be called with the vector list pointing
to an unoccupied area of memory ($3408), my default memory fill was $FF
which causes lots of relative -1,-1 vectors, the vector list is only
terminated by a number >0. So what happens is these little vectors get
drawn until the pointer hits the RAM area at $c800. The fix for this is
simple fill the unused memory with $08's. Simple eh!!
($08 is an illegal opcode).



3.2 History
-----------

DVE is written in Watcom 'C' and Assembler. All of the 6809 opcode emulation
is 100% assembler, the main sequencing loops and all hardware emulation is
still written in 'C'. The program uses my homebrew VESA setup and linedraw,
not the fastest but much faster then the watcom libs.

I started DVE back in March 1993, spent around 2 months on/off writing the
debugger and disasembler. I then got bored and dropped the project in
favour of something more interesting (doom most likely). There it sat until
about Feb 96 when seening that someone (PCJohn) was writing new games it
spurred me into action. 

I currently have 3 pet projects:

1. DVE
2. Stella DOS, Port of Brad Motts Linux/X Atari 2600 emulator to DOS.
3. The Atari Lynx emulator.....someday when DVE is complete.



3.3 Speed Gripes
----------------

For those people who complain that xxx emulator does 100% on a 8MHz 8086
why can't DVE hack it, heres my reason why.

  The vectrex uses a 6809 running at 1.5Mhz (External clock is 6MHz)

  On a 60MHz Pentium this means I have only 40 Pentium clock cycles in
  which to emulate a single 6809 cycle. If you said that each pentium
  instruction takes 2 cycles then I can only execute 20 machine code
  instructions.

  For each emulated vectrex cycle the emulator must do the following:
      
            Update the 6809 model
            Update the 6522 model (shift register & 2 counters)
            Increment the time reference for hardware emulation

  The big problem is screen emulation, the emulator must keep a list of
  all vectors on screen at a given time. Any time a new vector is drawn
  it must be compared against all existing vectors to see if it is a
  new vector or an old one being re-drawn. The opening screen has around
  300 vectors constantly being updated.

  Periodically the emulator must age the list of vectors in an attempt
  to emulate the persistance of the monitor, ie Undrawn vectors must
  fade away, all old vectors then have to be undrawn.

  Maybe now you have some idea why getting 100% speed is not as easy
  as it sounds.





4.0 Many thanks to
------------------

Lee Witek      - For doing the Web page and being an all round mate.
                 (Someday THE game WILL be finished)... Plum

Fred Taft      - Without your dissasembly of the system ROM I'd have had
                 a devil of a time sorting some of the bugs. It would have
                 been impossible for me to rebuild system.img from the
                 corrupt version.

John Sandhoff  - The kind soul who sent me the Vectrex System manual 3 years
                 ago when I started this project.

Phil Jones     - (fil@muon.demon.co.uk) Many thanks for the code you released
                 to x2ftp.oulu.fi for setting VESA modes. 

Mark Woodward  - For the uncorrupted system image

Brad Mott      - Who licensing text I've borrowed & modified.


To all of those avid vectrex fans who've sent me email encouraging me.




5.0 Revision History
--------------------

22/4/96 V0.01 - First public release of the emulator, work in progress.

23/4/96 V0.02 - Additional opcode emulation and bug fixes. Mine Storm
                now runs properly although buttons still cause exceptions

29/4/96 V0.03 - More opcodes, some bugfixing, some optimisation.

24/5/96 V0.04 - Bug-fixing.
       (Beta)   Optimisation.
                6809 Emulation completed
                Interrupt handling added.
                VESA Mode code added.
                linedraw code added.
                Some new INI options added: display_enhance
                Documentation overhaul


To be done for V1.0 release:

  Implementation of window clipping
  Emulator to work with all known non 3D games where possible
  Fix offset bug: Spinball & Clean sweep
  Colour overlays
  Popup windows for exceptions and conditional compile of debug monitor
  Sound



