DOS Vectrex Emulator (DVE V1.40)
--------------------------------

Author:            Keith Wilkins  (kwilkins@nectech.co.uk)
Some enhancements: Christopher Salomon
                   (chrissalo@aol.com)


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

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
  2.4      Generating custom overlays

3.0      Emulator Development status
  3.1      Misc history
  3.2      Speed gripes
  3.3      Emulation problems

4.0      With thanks to

5.0      Revision history





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

The Vectrex emulator comes as a selfextracting archive.
A directory 'vectrex' is created while extraction and all files
are unpacked to that directory. Originally that archive comes
without virus, if you distrust your source of the file...
better check again :-)

vectrex.exe
you may delete the archive afterwards... you don't need it any longer...

For those guys using a different operating system then DOS/compatible...
I used RAR for archiving, probably a version of RAR is available for
your OS as well, so you will be able to strip the file of
the selfextracting header.

This emulator should run on 386/486 machines but will run VERY slowly. The
emulator runs OK on a P60, slow but playable.

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

This version of Vectrex emulator supports VESA 2.0. If you have
a graphic card which is able of providing a hardware linear framebuffer
(UNIVBE will enable it!!!), you will definitly have a major speed
increase!

DVE now has sound thanks to Marcel De Kogel's emulation of the AY-3-8912
using the Adlib emulation. Please don't complain about the quality of the
sound I know the noise emulation is not perfect, but heh how much did you
pay for DVE ?? I do this for love not money so I don't need the grief.
If your machine is below a P60 in performance I'd advise you disable the
sound emulation, the faster the machine the better it sounds (See 2.3)



   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 have posted
   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


C. UK/US Vectrex home page

   http://www.parallax.co.uk/~lmw            - Maintained by Lee Witek
   http://www.naples.net/~saturn/vectrex/dve - Maintained by Alan Ricotta

D. My own page...

   http://members.aol.com/chrissalo/vectrex.htm - you might find something
                                                  interesting too...

There now seem to be a number of other sites with the zip, try searching
for Vectrex on lycos.



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>

There is a 2nd copy of DVE bundled in with the source release this can
be run by typing:

Usage: VECTDBG <binary game image>

This has all of the DVE debugging functions built in and is useful
for debugging or just disassembling games. I used it to cheat my way
through to the secret game in patriot. Hit <ALT-M> during the game
to invoke the debugger.

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

Why not unpack Andrew Bond's menu program (menu17a.zip) and type menu.exe
for a nice front end. You'll need the game pack, unpack all of the games
into the DVE directory.



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-G   Capture Screen to PCX file
ALT-W   Save game in progress (saved on exit if enabled)
ALT-L   Load saved game (loaded on start if enabled)
ALT-1 - ALT-9 Save position 1 to 9
1 - 9   Load position 1 to 9


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
debug_monitor          0/1     Boot straight into the debug monitor
                               (Both disabled in released version)

restore_on_start       0/1     Load saved game (corresponding to the rom name)
                               on startup (1) or not (0)
save_on_exit           0/1     Save game on exit to default name
                               (corresponding to rom name)

max_speed              int     Value between 1-1000 to set relative speed
                               upper limit 100 = 100%

sound_enable           0/1     Enable/Disable sound emulation (Adlib)

display_verbose        0/1     Print some graphic stuff information on
                               startup, better redirect output...

display_exact_scaling  0/1     Enables the correct scaling calculation
                               (a bit slower)

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
                                  3 - 1280x1024
                                  4 - 1600x1200 (need 2 MB)

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_clip_x         int     These values will set the screen clipping
display_clip_y                 region. Default values are x=17000, y=18000
                               These numbers are based on the vectrex screen
                               resolution and are automatically scaled to the
                               chosen screen mode.

display_colour         int     Display colour 1-14 1=White,2=Red,3=Green,4=Blue


display_0div_x         int     modify value for exact scaling divider, x
                               coordinate for resolution SVGA640X480
display_0div_y         int     modify value for exact scaling divider, y
                               coordinate for resolution SVGA640X480

display_1div_x         int     modify value for exact scaling divider, x
                               coordinate for resolution SVGA800X600
display_1div_y         int     modify value for exact scaling divider, y
                               coordinate for resolution SVGA800X600

display_2div_x         int     modify value for exact scaling divider, x
                               coordinate for resolution SVGA1024X768
display_2div_y         int     modify value for exact scaling divider, y
                               coordinate for resolution SVGA1024X768

display_3div_x         int     modify value for exact scaling divider, x
                               coordinate for resolution SVGA1280X1024
display_3div_y         int     modify value for exact scaling divider, y
                               coordinate for resolution SVGA1280X1024

display_4div_x         int     modify value for exact scaling divider, x
                               coordinate for resolution SVGA1600X1200
display_4div_y         int     modify value for exact scaling divider, y
                               coordinate for resolution SVGA1600X1200

display_0shifta_x      int    modify value for shifta, x
                              coordinate for resolution SVGA640X480
display_0shiftb_x      int    modify value for shiftb, x
                              coordinate for resolution SVGA640X480
display_0shifta_y      int    modify value for shifta, y
                              coordinate for resolution SVGA640X480
display_0shiftb_y      int    modify value for shiftb, y
                              coordinate for resolution SVGA640X480

display_1shifta_x      int    modify value for shifta, x
                              coordinate for resolution SVGA800X600
display_1shiftb_x      int    modify value for shiftb, x
                              coordinate for resolution SVGA800X600
display_1shifta_y      int    modify value for shifta, y
                              coordinate for resolution SVGA800X600
display_1shiftb_y      int    modify value for shiftb, y
                              coordinate for resolution SVGA800X600

display_2shifta_x      int    modify value for shifta, x
                              coordinate for resolution SVGA1024X768
display_2shiftb_x      int    modify value for shiftb, x
                              coordinate for resolution SVGA1024X768
display_2shifta_y      int    modify value for shifta, y
                              coordinate for resolution SVGA1024X768
display_2shiftb_y      int    modify value for shiftb, y
                              coordinate for resolution SVGA1024X768

display_3shifta_x      int    modify value for shifta, x
                              coordinate for resolution SVGA1280X1024
display_3shiftb_x      int    modify value for shiftb, x
                              coordinate for resolution SVGA1280X1024
display_3shifta_y      int    modify value for shifta, y
                              coordinate for resolution SVGA1280X1024
display_3shiftb_y      int    modify value for shiftb, y
                              coordinate for resolution SVGA1280X1024

display_4shifta_x      int    modify value for shifta, x
                              coordinate for resolution SVGA1600X1200
display_4shiftb_x      int    modify value for shiftb, x
                              coordinate for resolution SVGA1600X1200
display_4shifta_y      int    modify value for shifta, y
                              coordinate for resolution SVGA1600X1200
display_4shiftb_y      int    modify value for shiftb, y
                              coordinate for resolution SVGA1600X1200

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.
                               (cards with ram expansion, animaction
                                for example)

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

force_vesa12                  bool 0/1
digital_volume                int 0-100
force_single_processor        bool 0/1



2.4 Custom overlays (.VOL files)
--------------------------------

The original vectrex had clear palstic overlays with nice borders that
were supplied with each game. These gave some semblance of colour on
the vectrex. DVE V1.0 upwards supports an electronic version of these
overlays.

I have generated one example file for Minestorm just to show how things
work. I have added (as requested many times) the capability for both
overlays and borders. It is up to you the users to generate the VOL files
for the games. I don't have the time. I'm sure some kind sole has the
time and inclination to generate a VOL file editor.

Since DVE 1.20 there is support for PCX overlay pictures. The above mentioned
method is still implemented.
I had the idea to use 'real' vectrex overlays as soon as I saw heaps of
them at a certain ftp site. I converted the minestorm overlay and
added a simple pcx routine to the emulator, voila a very lifelike overlay!
There is no scaling provided for pcx overlays, so you have to create
one for every resolution you would like to play with.
For minestorm I include a 'full' overlay.
(for all five supported resolution that is, scaled)
The Overlay images found, simply scaled down to the required size still don't
fit. Or sometimes you'd like to fit the vectrex to some specified screen
region (if you want to use a vectrexpicture+something as an overlay).
A new (above mentioned) ini-file option for scaling is supported...
Look above for the syntax.

Following are the 'historic' values (defaults):

/******************************************************/
/* DivShftA   DivshftB   error scaled  error to 40000 */
/******************************************************/
          7,         8,  // error 12 : 996
          7,         7,  // error 24 : 1584
          6,         8,  // error 13 : 676
          6,         7,  // error 87 : 3393
          6,         6,  // error 50 : 1650

/***************************************/
/* using exact scaling, divider values */
/***************************************/
          83,            // error  1.92 : 159
          66,            // error  6.06 : 400
          52,            // error  1.23 : 64
          39,            // error  1.64 : 64
          33,            // error 12.12 : 400




COMMAND SYNTAX DEFINITION FOR *.VOL FILES

  screen colour <pen> <intensity> <red> <green> <blue>
  screen clip   <x1> <y1> <x2> <y2>
  screen offset <x1> <y1>

  screen divx  <resolution> <div>
  screen divy  <resolution> <div>

  for not-exact scaling:

  screen shiftx   <resolution> <shift a> <shift b>
  screen shifty   <resolution> <shift a> <shift b>

  border line   <pen> <intensity> <x1> <y1> <x2> <y2>
  border block  <pen> <intensity> <x1> <y1> <x2> <y2>
  border elipse <pen> <intensity> <x1> <y1> <major axis/2> <minor axis/2>
  border triangle <pen> <intensity> <x1> <y1> <x2> <y2> <x3> <y3>

  overlay enable/disable
  overlay block  <pen> <x1> <y1> <x2> <y2>
  overlay elipse <pen> <x1> <y1> <major axis> <minor axis>
  overlay triangle <pen> <x1> <y1> <x2> <y2> <x3> <y3>

  overlay_pcx0 <filename>
  overlay_pcx1 <filename>
  overlay_pcx2 <filename>
  overlay_pcx3 <filename>
  overlay_pcx4 <filename>

  extended_ram
  no_shades
  load_colors_exact

  lightpen

  fullrefresh


VALUE BOUNDS

  pen value       0 to 15
  intensity value 0 to 15
  red/green/blue  0 to 255
  x1/y1/x2/y2     -20000 to +20000

  NOTE: For x/y values you MUST keep these values exact multiples of 64.
        If you do not do this then you'll find that some of your items
        won't line up correctly. This is all due to the method used to
        convert vectrex coordinates to screen coordinate as it uses a
        a bit shift to divide.
        This is for old style overlay definition only!


SCREEN COMMANDS

  screen colour <pen> <intensity> <red> <green> <blue>

    This command allows you to customise DVE's screen colour selection.
    You have a choice of 14 pens (1-14) and 16 intensities of each pen
    (0-15). I would suggest that you use pen 15 for setting up colours
    for use in the border setup. The red/green/blue values must all be
    in the range 0-255.

    You should define intensity 15 to be the brightest. Intensity 0
    should always be black (0 0 0). e.g.

        # Light blue gradient for pen 14
        screen colour 14 0    0   0   0
        screen colour 14 1    4   4  16
        screen colour 14 2    8   8  32
        screen colour 14 3   12  12  48
        screen colour 14 4   16  16  64
        screen colour 14 5   20  20  80
        screen colour 14 6   24  24  96
        screen colour 14 7   28  28 112
        screen colour 14 8   32  32 128
        screen colour 14 9   36  36 144
        screen colour 14 10  40  40 160
        screen colour 14 11  44  44 176
        screen colour 14 12  48  48 192
        screen colour 14 13  52  52 208
        screen colour 14 14  56  56 224
        screen colour 14 15  60  60 240

    Pens 1-4 have already been defined (you can overwrite them) in the
    following manner:

        Pen 1 - White
        Pen 2 - Red   (255 0 0) - (0 0 0)
        Pen 3 - Green (0 255 0) - (0 0 0)
        Pen 4 - Blue  (0 0 255) - (0 0 0)

    All other pens have been set to black (0 0 0) on all intensities.

    Pen 0 exists to, but these colors act now as in the PCX overlays...

     pen 0 color 1 -14 are used for erase pen colors,
     pen 0 1 is erase color for pen 1
     pen 0 2 is erase color for pen 2 ...


  screen clip   <x1> <y1> <x2> <y2>

    This will set the active clipping region for all vector drawing
    no vectors will be draw outside of this box. The vectrex screen
    coordinates go from about -20000 to +20000 units in both X and Y.

    Because of the linearity problem described in "Emulation Problems"
    some games need a wider clipping box than others (Vaders).

  screen offset <x1> <y1>

    This will allow you to shift the 0,0 origin around on the screen.

Scalability of Emulator Output

I bet you never looked at it, right?
The ability to scale the Vectrex Display used to be only available in the
'vectrex.ini' file. With the overlay pictures available at ftp.csus.edu
a problem became apparent. The output is not exactly scaled as the overlays,
the overlays themself have different sizes amongst each other (astonishing,
isn't it?). From now on the output can be scaled from each overlay file as
well, the overlay-file scaling overrides scaling values found in vectrex.ini.
The picture at the top of this page gives an example of a downscaled
Minestorm. Now the ship doesn't disappear anymore if it moves out of the
screen, it moves directly to the other side, as it supposed to be like.

Syntax:

for exact scaling:
SCREEN DIVX     -RESOLUTION- -DIV-
SCREEN DIVY     -RESOLUTION- -DIV-

for not-exact scaling:
SCREEN SHIFTX   -RESOLUTION- -SHIFT A- -SHIFT B-
SCREEN SHIFTY   -RESOLUTION- -SHIFT A- -SHIFT B-

For Minestorm in 640X480 Resolution following seems to be OK:

SCREEN DIVX 0 98
SCREEN DIVY 0 92

While you are at it, ever used the SCREEN OFFSET thing? You can move vectrex
emulation anyplace on the screen you like!
How about a picture of a vectrex console, and the emulator right on it?
You can do it, if you want!


BORDER COMMANDS

These commands can be used for drawing the non-transparent parts of the
vectrex overlays. You can setup the colours using the SCREEN COLOUR
command. I would suggest you use pen 15.


  border line   <pen> <intensity> <x1> <y1> <x2> <y2>
  border block  <pen> <intensity> <x1> <y1> <x2> <y2>
  border elipse <pen> <intensity> <x1> <y1> <major axis/2> <minor axis/2>
  border triangle <pen> <intensity> <x1> <y1> <x2> <y2> <x3> <y3>

    These commands will generate an rectangular/eliptical/triangular solid
    colour areas.



OVERLAY COMMANDS

These commands WILL NOT draw anything visible to the screen area unless
you have the DEBUG command present in the VOL file. The overlay commands
will generate the equivalent of the clear coloured plastic parts of the
vecrex overlays.

When used with the SCREEN COLOUR commands to define a pen/intensity
selection and and OVERLAY XXXX commmand you can generate areas of the
screen which will have different colour vectors. See my example
SYSTEM.VOL file. When the screen beam passes over an overlay it will
change colour to the given <pen> colour as defined by the SCREEN COLOUR
commands.

  overlay enable/disable

    By default the overlay function is disabled because of the slight
    speed hit that it causes. It will not disable the drawing of any
    border or screen commands. So you can have borders without overlays
    if thats what you require.

   DO NOT ENABLE OVERLAY IF YOU DON'T USE IT!!!
   The screen will remain black, since no colors are defined!!!

  overlay block  <pen> <x1> <y1> <x2> <y2>
  overlay elipse <pen> <x1> <y1> <major axis> <minor axis>
  overlay triangle <pen> <x1> <y1> <x2> <y2> <x3> <y3>

    These commands will generate an rectangular/eliptical/triangular
    coloured transparent areas. Whenever the vector beam passes over
    this area it will draw in the colours you have defined for <pen>
    with the SCREEN COLOUR command.

PCX COMMANDS

  overlay_pcx0 <filename> for SVGA640X480
  overlay_pcx1 <filename> for SVGA800X600
  overlay_pcx2 <filename> for SVGA1024X768
  overlay_pcx3 <filename> for SVGA1280X1024
  overlay_pcx4 <filename> for SVGA1600X1200

Load an overlay PCX file. The PCX MUST be a 256 color file with exactly
the correct resolution.
-all colors of the PCX file are used and set
-clipping is provided by the pcx file
-overlay is provided by the pcx file

Enhanced the PCX overlay again (DVE v1.20a).
Now some 'shinethrough' or what ever you want to call it is added.
Overlay PCX layout:

color#0       : Not used (might be solid)

color#1-14    : Shinethrough colors for pen 1-14
                (these are treated as solid too)

color#15      : Not used (might be solid)

color#16-239  : 14 pen colors, each 16 color width
                These colors define transparent overlay
                parts of the PCX picture.

                Only the last color from each 16color block is
                read from the pcx file
                the 15 previous colors are ranges from that
                color to black (or shinethrough)

color #240-255: Solid colors, are loaded and shown as in PCX file


You can use up to 14 different pen colors.
These pen colors define areas of the pcx where a vector will be
displayed. As the PCX file is read pixels with these colors
are NOT displayed, since they define transparent colors.
The pen colors are (colors range from 0-255 in a pcx file):
31,47... 239
colors in between the above mentioned are ignored!
Colors 1-14 are shinethrough colors

--------
Difference to V1.20 Overlays.
Well, a deleted vector was allways drawn in background color. That was
color#0, usually black. I still haven't seen a Vectrex, but I'd imagine,
that even when the beam was not illuminating the screen some color would
be visible. For Minestorm for example that might have been a very dark
blue'ish 'shinethrough'. Now colors 1-14 are the corresponding
'shinethrough' colors for their respectiv pen.
Why use different colors than the darkest pen color? Dunno, seemed to be
a good Idea at the time, can't remember. Perhaps just to add to the confusion.
--------

The downscaled colors are calculated while loading the pcx file as intensities
of the pencolors. The RGB values of for example color 15 are divided by 16,
every color below 15 has 1/15 less RGB value, down to 0. Thus
we have the required intensities for our vector.
Colors 240-255 define solid colors. Pixels with that color are put on the
screen and are visible all time.
Clipping is performed in the way that pixels with solid colors define
clipped regions and pixels with transparent colors are none-clipped regions.
If you don't understand this at all,... don't bother, look at the
overlay pcx files that come with the emulator, they should clear up everything,
as this is really a simple method...


VARIOUS

EXTENDED_RAM

If you put this switch in the *.vol file, the cartridge is treated as having
a extra ram area at $2000-$2800 regarding save files.
The only known cartridge to support this is animaction.


NO_SHADES

Emulator behaves like befor the bugfix (I think) regarding color shadings.

LOAD_COLORS_EXACT

Do nothing to the colors of the PCX file. You could actually programm
colored vectrex games with this, as the shades don't have different
brightnesses but different colors. Up to 16 colors per overlayblock!
(Haven't tried it, but sounds cool)


LIGHTPEN COMMANDS

LIGHTPEN


This enables lightpen emulation. Lightpen is emulated via mouse.
A tiny mouse pointer is shown (one Pixel for now).

The mousepointer uses two colors.
Color 254 and Color 255 (pen 15 intensity 14 (==254) and intensity 15 (==255)).
The pointer will be color 255 if no mousebutton is pressed and the other
color if any or all mousebutton is (are) pressed.
The lightpen is considered off screen while no button is pressed and
touching the screen while a button is pressed.

To change these colors without loading a pcx overlay with appropriate
colors at the correct position you might use the following syntax:

screen colour 15 15 255 255 255
screen colour 15 14 255 0   0

This will give you a white pointer and red 'active' pointer.

If you enable the lightpen you should enable exact scaling as well.
This is not done automatically!
The mouseposition is converted to vectrex scanline position using the
divider for exact scaling as a multiplier.
Backwards operation of the two shifts is just a bit difficult to manage.
If you still don't want to use exact scaling,
you might try using a different exact scaling value while using
'not exact scaling' to avoid the differences between the two calculation
methods. (Didn't try that)


Note: I found no documention regarding how a lightpen for Vectrex
      exactly works. I found a dissassembled ArtMaster Rom
      file at a certain ftp site (look at links...).
      Thanks for that again Fred!
      I tried some reverse engeniering,... and it actually works now
      for the three lightpen using images I found so far:

      Art Master
      Melody Master
      Animaction

      I don't know if I got it completly right. If something does not
      work... you may try contacting me...

How I think the vectrex lightpen works:
(forgive me if something in here doesn't sound very professional,
 cause I really am a technical illiterate, I just describe what I found
 out looking at the Art Master Rom...
 and ... I never programmed a 6809 processor)

Artmaster uses sort of two different ways to locate the lightpen:
a. check known positions if something is there
b. search the hole screen for a lightpen

a. To put it simple: The last lightpen position is known, Vectrex thinks
   the lightpen must still be somewhere near, so it draws something like
   a spider net arround the last position.
                                   /-----\
                /---\             /       \
    /-\        /     \            I       I
    I*I        I  *  I            I   *   I         ...
    \-/        \     /            I       I
                \---/             \       /
                                   \-----/

   If it is found somewhere on the WEB Vectrex is happy :-)!
   If not it stops searching and is unhappy :-(!
   You will see that very often using Artmasters Sketch or Connect
   Menu (everytime you release the button!).

   Emulating this was fairly simple, since the only thing to be added
   was mouse position information.
   The lightpen will generate an interrupt on the PIA line CA1.
   So I only changed the analog section of the emulator, if
   the position of the vector ray was near the mouse position
   then...
   t6522IFLG|=E6522IFLG_CA1;
   change the PIA interrupt register so that it thinks an interrupt had
   occured. Actually I didn't like to put it in the Analog section,
   since it is a PIA interrupt, and all other PIA interrupts are triggered
   in the PIA section of the code... but than again it is triggered sort
   of by the vector beam too...

b. The method used in animation modus is somewhere different, for
   you can put 'new' lines anywhere on the screen, so 'webbing' would
   be sort of unefficent.

   ArtMaster scans the whole screen for the lightpen position.
   It draws lines from bottom to top (search_screen_for_scanlines (0721)).
   (0x7a lines by the way (0721)) These lines are drawn every
   0x0200 (0766) vectrex coordinates (y-axis that is).
   It starts at position 14944 (decimal)(0726) and goes up (screen upwards)
   to -17888.

   A line is drawn all the way, after it is finnished there is a check if
   a lightpen pick occured, if so then further testing regarding the
   horizontal position is done (find_point_of_intersection (076d)).
   If it doesn't find a pick at all it leaves the routine
   (being unhappy again...).

   The horizontal position is somewhat trickier to get. ArtMaster
   calculates the position. It redraws the scanline (0770...) where
   it found the lightpen pick, starts a counter (register b=0x7f (0798))
   draws the line and while decreasing the counter waits for an
   interrupt to occur. (lightpen interrupt on PIA CA1, 0776...)
   If an interrupt occurs, the position is calculated and stored
   (process_ISR (07B7)).
   Finished.

   So I had to implement a new interrupt, the vectrex emulator
   did not react on CA1 interrupts (this was done in five minutes, since
   it was virtually nothing!).
   After me having optimized the processor to multi-ticks (that's what
   I call it) calculation of the horizontal position was somewhat
   difficult. I actually had to reimplement the old single-tick cpu
   again to calculate the position correctly, furthermore an analog
   tick HAD to occur every cycle, otherwise the emulator could miss
   the position it was looking for.
   The beam position had to be integrated every tick and could not
   be calculated per ticks since last integration.
   All this makes lightpen emulation sort of inefficient :-(.
   BUT I only use this sort of testing and integrating when BOTH
   mousebutton is pressed and an CIA interrupt is enabled... so
   most of the time emulation goes smooth still.

   While we are at it... I cheated somewhat here!
   ArtMaster tries to disable interrupts with following code
   (disable_interrupts (07aa)):

   clra
   sta   0x0e

   Which doesn't really clear anything, since the interrupt vector
   to be cleared must be specified, it should be something like:

   lda   #0x02
   sta   0x0e

   This incorrectness caused a slowdown once the interrupt was enabled
   the first time and the mouse button was pressed...
   The workarround to that was, that EVERYTIME an interrupt is cleared
   bit two is set!
   (emu6522.c function: UBYTE f6522Addr0EWrite(UWORD tAddress,UBYTE tData))
   This shouldn't really concern any other vectrex rom, since that
   interrupt is only used by the lightpen (I think).
   But I really hated doing that, since emulation
   perfection is somewhat broken...
   The other way would have been to change the ROM, but that would
   have been a none trivial task, since there is not so much
   space for new code in there...

   The width for a mouse position to be recognized is 0x100 vectrex
   coordinates, I derived that value of the ArtMaster
   search_screen_for_lightpen routine, which scans in intervalls of
   0x200. Sometimes with the emulator lightpens are not recognized,
   this relates directly to the above mentioned 0x100. It could
   probably be a bit wider range, but a miss happens fairly seldom,
   so why bother, I guess it happened with a real lightpen too.
   To take a wider range than 0x100 would have made
   for example connect and scetch somewhat inaccurate, so I left it at
   0x100...


Another thing:
For lightpen support I added one further option to *.vol files.
This one is called:

FULLREFRESH

This has to do with the way the emulator refreshed vectors and how the
mouse cursor is implemented.
To minimize the processor time at mouse support, it is
not checked whether there is a vector behind the mouse or not.
It is checked if there is an overlay section behind the mouse or not.
If an overlay is there, the overlay is restored (or a window for that...)
If there is no overlay... the screen is just cleared.
If the mouse moves over a vector, the vector is broken at that point,
because one or more pixel(s) is (are) erased.
The emulator doesn't usually redraw 'stable' vectors, if vectrex is
redrawing a vector which is allready in position, it's time stamp is
updated, but the vector itself is not redrawn, so after a while
using the mouse the screen can become somewhat garbled.
FULLREFRESH now enables redrawing all vectors
every display tick, the screen stays tidy and clean... though it is a
bit slower...

For Programmers: If you use the mouse, don't option the compiler with
                 the '/et', the programm will die of a page fault disease!

3D-IMAGER
                  3D_IMAGER_GAME
                  WHEEL_TICKS #number#
                  COLOR_1_DEGREES #number#
                  COLOR_2_DEGREES #number#
                  COLOR_3_DEGREES #number#
                  IMAGER_MODE #number#

                  Most of these are fairly selfexplanatory, but here is what they
                  do anyhow.

                  3D_IMAGER_GAME - tells the emulator, that the game for this
                  *.vol file is a GOGGLE-GAME.

                  WHEEL_TICKS #number# - you tell the *.vol file the speed with which
                  the wheel has to spin. One tick is 1/1500000 second.
                  (vectrex 6809 runs at 1.5Mhz) Good values to start with are
                  between 40000 and 60000.

                  COLOR_?_DEGREES #number# - these three things are used to
                  tell the emulator, what the wheel looks like.
                  In degrees how much of the half wheel is covered by the
                  corresponding color.
                  It is very strongly recomended, that these three
                  values add up to 180 degrees, though I don't check it...
                  BTW..., COLOR1 is 15, COLOR2 is 13, COLOR3 is 14...

                  IMAGER_MODE #number# - number between 0 - 6.
                  This determines how the imager is to be emulated to the
                  screen.
                  At some time there was sort of a discussion going on in some
                  newsgroup how the goggles could at all be satisfyingly
                  emulated. Well probably can't suit you all, but
                  I couldn't think of much more, save to insert some goggles
                  to the joystick port... (no, I won't do that!)
                  Here is what these 7 modes do:


                  # 0 only the 'left' side is displayed, unicolor, therefor
                      an overlay picture can be used

                  # 1 only the 'right' side is displayed, unicolor, therefor
                      an overlay picture can be used

                  # 2 red/blue for left and right side, if you have some glasses
                      you might be lucky and get a glimps of true 3d :-)

                  # 3 only the 'left' side is displayed, in the colors corresponding
                      to the wheel colors (overlays must be enabled nonetheless)

                  # 4 only the 'right' side is displayed, in the colors corresponding
                      to the wheel colors (overlays must be enabled nonetheless)

                  # 5 both sides are displayed in colors corresponding
                      to the wheel colors (overlays must be enabled nonetheless)
                      this most probably looks like a real vectrex seen without
                      the helmet on :-)

                  # 6 left side is displayed on the leftmost side of the screen
                      right side is displayed on the rightmost side of the screen
                      (scaling must be set manually to fit...)
                      Actually I like this setting a lot...

Just for the sake of completeness.
Somebody said one could get something out of beating the 4 button on the
second joystick. That is probably right, but it used not to be right
with the emulator. Keith forgot (or didn't think it important) to
map that key to CA1 register of the VIA. There it can trigger an IRQ, which
in turn is the thing vectrex waits for. It is emulated now, though I still
didn't try bashing at the keyboard...

Oh, by the way, thanks again to Fred Taft for his dissassembling of
"Narrow Escape" which proved to be quite usefull :-)




3.0 Current Status
------------------
KEITH:
As far as I'm concerned DVE is pretty much complete at V1.0. I am not
planning any further versions unless it is to bug fix V1.0.

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. With the new hashing
search on vectors for V1.0 then this should no longer be a problem.

HINT: Press ALT-R at the reset screen, 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. (Matrox Millenium)



3.1 History
-----------

For Version 1.00, Keith:
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.

Adding for version 1.20, Chris:
...



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


3.3 Emulation Problems
----------------------

There are two games I desparately wanted to get running perfectly as they
are the only two with graphical faults : Clean Sweep & Spinball. It seems
unlikely that the vector offset problem will be fixable without considerable
effort on my part to improve the modelling of the integrators within the
vectrex.

The gist of the problem is that DVE models "perfect" integrators that always
reach the point they were programmed to reach, in a linear fashion. On the
real machine the integrators arent perfect, its this imperfection that is
very hard to model correctly.

The problem manifests itself slightly in most games, the most obvious is
the non-centred text on the boot screen. This feature also prevents line
clipping being implemented fully as the edge of the screen is in different
places for many games, i.e Vectrex Vaders is much wider than others.
Although each game can have its own VOL file and as such you can have
different clipping for each game.



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

Alan Ricotta    - For maintaining the US home page.

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.

Marcel De Kogel - For the use of his AY-3-8912 emulation for Adlib.

Luc Miron       - For producing menu.cfg

Andrew Bond     - For offering menu.zip for inclusion in DVE distribution.


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

7/8/96  V1.00 - Hashing table added for line search.
                (~2x speed up on boot screen 19% -> 36%)

                Sound emulation added.

                Speed limiter has been added for the day when a machine
                is found that'll run DVE >100% (P133 or better should do it).

                Fixed Timer1/2 IRQ bug (Bedlam now works)

                Added custom overlay file capability (VOL files)

                Clipping modified to be screen mode independant, now
                based on vectrex screen coords,

                Fixed Dark Tower bug. Bug with Dark Tower not setting
                the direct page register correctly and using the 6522
                data direction register as a RAM location.

                Fixed Cosmic Chasm bug. Caused by typo in the opcode
                lookup table, some page 3 opcodes were calling page 2
                instructions.

??.10.96:V1.20
                Ah, well speed improvements...
                - new vesa routines for VESA 2.0 support
                  (hardware linear framebuffer, if your card supports it)
                - new clipping strategy
                - emulation processing changed
                  (thanks for the tip Keith)
                - more 'inline' functions

                ->a speed increase sometimes up to (and exceeding) 100%

                PCX overlay files added

                Exact scaling supported

                Lightpen support

                Note: The vectrex.exe file is considerably larger
                than the last version. The old version was packed, this
                one isn't. And for different options I used
                different functions, so I avoided many if... then... else
                clauses, but on the other hand I used up much
                more space than Keith...

                Note: The emulator uses much more memory than it used to...
                This is due to some large arrays...
                For example for clipping I use an array the size of the
                resolution. That takes nearly 2MB for the highest resolution!

                If you want a FAST emulation:
                -be sure to have a hardware linear framebuffer card
                -disable overlay
                -disable exact scaling
                -disable display enhance
                -disable lightpen
                -disable fullrefresh
                -disable display_auto_refresh and chose something as
                 refresh value which suits you
                -use mode 2 (for me somehow its the fastest)
                -do a clean DOS boot, without ANY memory manager

                with that I have been able to get 100% with some games...
                (Intel P100, Diamond Stealth 64 2MB VRAM)

??.10.96:V1.20a Changed the PCX overlay organization a bit, people start
                asking how to do these things, I though it was pretty much
                selfexplanatory, I was wrong I guess

??.12.96:V1.20b Lost in time, HD Crash... (Had a graphical startup menu to
                select images...) Will be some time till I do that again,
                I hate implementing things twice

27.02.97:V1.20c Bug fix, overlayed colors were not drawn in the correct
                brightness, actually they were drawn in full illumination all
                the time

28.02.97:V1.20d Implemented that Snapshot ability (ALT W and ALT L), wanted
                to do that for quite some time now, never came arround doing
                it though

02.03.97:V1.20d ALT 1 to ALT 9 Save games to different files, loadable with
                1 to 9. Two *.vol file options included on demand (I don't
                like them), Lightpen fixed.

??.??.97:V1.20e Carousel overlay bug fixed

??.??.97:V1.20f - save format changed slightly

                - a bit speed improve I think

                - keys don't react quite as good (well a bit of loss somewhere)

                - old overlay style fixed, though display colors now start with
                  pen 1 instead of zero
                  pen 1 is white
                  pen 2 is red
                  ...
                  as in the pcx overlays
                  pen 0 color 1 -14 are used for erase pen colors,
                  pen 0 1 is erase color for pen 1
                  pen 0 2 is erase color for pen 2 ...

                  because of that some changes must be made to existing *.vol
                  overlays, though they shouldn't be dramatic

                  and in vectrex.ini
                  display_color only ranges from 1 to 14 instead from
                  0 to 15...    (old default is 0 now is 1)

                - two new overlay comands (old style)
                  border triangle pen intensity x1 y1 x2 y2 x3 y3
                  overlay triangle pen x1 y1 x2 y2 x3 y3
                  wonder what they do?
                  (on demand... didn't test them all that much...)

27.06.97:V1.30  - Clay wrote the following:
                  "The emulator has some quirks-- it will display
                   vector intensities with the high bit set (the
                   Vectrex shows black for any intensity of %1xxxxxxx)"
                   fixed!

                - new ini command "force_vesa12", if set to one a
                  banked (VESA 1.20 compatible) mode will be forced,
                  hopefully that will work with people who have trouble
                  with VESA 2.0 modes, though it is about 10% slower...

                - thanks to Clay I added digital sound support
                  this can be heard in spike or in clays moon lander
                  (or the sample file he gave me :-))
                  New ini command "digital_volume", can be set to
                  a procentage. The digital volume can be regulated with
                  that (with my system, it is quite another volume than
                  the non digitized...).
                  In order to enable digital samples, a
                  soundblaster/compatible card must be used AND the BLASTER
                  environment variable must be set!
                  Note: If emulation runs to fast, the samples will all
                  speed up! The speed settings will not work fine
                  with digitized audio, since speed is regulated by
                  a timer interrupt (18.2 times per second),
                  the emulator runs sort of in small burst if the
                  machine is to fast. This has weird effects on
                  samples (which are written directly to the DSP DAC).
                  I tried setting the timer interrupt up to 1000 times per
                  second and synchronizing to that, but it doesn't really
                  make any difference.
                  What I did was add another ini command:
                  "force_single_processor" (boolean, 0 or 1)
                  If set that will slow down emulation considerably
                  and probably will be to slow (unless you have a fast
                  processor :-)).
                  Whenever I get a really fast processor, I will add a delay
                  to the above single_processor_mode, that should fix the
                  speed things with digital samples once and for all,
                  since the emulator will than be able to run
                  cycle exact at 100% speed...

30.06.97:V1.40  - 3d Imager support!
                  Finally I had some time to look at it. It sort of works, it is not
                  perfect yet, but...
                  First some drawbacks...
                  I have no 3d imager, neither have I seen one working yet, I
                  don't really know what the games look like, so if
                  I have some color settings wrong, feel free to do better...
                  Right now I'm emulating a fixed speed for the spinning wheel.
                  Vectrex usually wants to fiddle with that speed, that is not suported
                  yet (dunno if it ever will be...).
                  "Narrow Escape" and "Crazy Coaster" work just about fine.
                  "Mine 3d" so so, I suspect it to change the rate of the
                  color wheel during the startup screen, since I can't find a
                  speed setting that will satisfy both the game and the startup...

                  There are some new settings for the *.vol files, as e.g.:

                  3D_IMAGER_GAME
                  WHEEL_TICKS #number#
                  COLOR_1_DEGREES #number#
                  COLOR_2_DEGREES #number#
                  COLOR_3_DEGREES #number#
                  IMAGER_MODE #number#

                  Most of these are fairly selfexplanatory, but here is what they
                  do anyhow.

                  3D_IMAGER_GAME - tells the emulator, that the game for this
                  *.vol file is a GOGGLE-GAME.

                  WHEEL_TICKS #number# - you tell the *.vol file the speed with which
                  the wheel has to spin. One tick is 1/1500000 second.
                  (vectrex 6809 runs at 1.5Mhz) Good values to start with are
                  between 40000 and 60000.

                  COLOR_?_DEGREES #number# - these three things are used to
                  tell the emulator, what the wheel looks like.
                  In degrees how much of the half wheel is covered by the
                  corresponding color.
                  It is very strongly recomended, that these three
                  values add up to 180 degrees, though I don't check it...
                  BTW..., COLOR1 is 15, COLOR2 is 13, COLOR3 is 14...

                  IMAGER_MODE #number# - number between 0 - 6.
                  This determines how the imager is to be emulated to the
                  screen.
                  At some time there was sort of a discussion going on in some
                  newsgroup how the goggles could at all be satisfyingly
                  emulated. Well probably can't suit you all, but
                  I couldn't think of much more, save to insert some goggles
                  to the joystick port... (no, I won't do that!)
                  Here is what these 7 modes do:


                  # 0 only the 'left' side is displayed, unicolor, therefor
                      an overlay picture can be used

                  # 1 only the 'right' side is displayed, unicolor, therefor
                      an overlay picture can be used

                  # 2 red/blue for left and right side, if you have some glasses
                      you might be lucky and get a glimps of true 3d :-)

                  # 3 only the 'left' side is displayed, in the colors corresponding
                      to the wheel colors (overlays must be enabled nonetheless)

                  # 4 only the 'right' side is displayed, in the colors corresponding
                      to the wheel colors (overlays must be enabled nonetheless)

                  # 5 both sides are displayed in colors corresponding
                      to the wheel colors (overlays must be enabled nonetheless)
                      this most probably looks like a real vectrex seen without
                      the helmet on :-)

                  # 6 left side is displayed on the leftmost side of the screen
                      right side is displayed on the rightmost side of the screen
                      (scaling must be set manually to fit...)
                      Actually I like this setting a lot...

                  Strangly these different mode sometime need different values
                  for the other above described settings.
                  I don't really know why. You just have to keep experimenting
                  with the values a bit. Whatever mode suits you most... you
                  probably must find the settings on your own.

--- END OF FILE ---
