Tree [r15] / src /
History



File Date Author Commit
src 2012-08-04 kevodwyer [r13] July 2012
src2 2013-06-15 kevodwyer [r14] June 2013
CHANGES.txt 2013-06-15 kevodwyer [r15] June 2013
LicenceGPL2.txt 2011-08-29 kevodwyer [r2]
README.txt 2013-06-15 kevodwyer [r14] June 2013
build.zip 2013-06-15 kevodwyer [r14] June 2013

Read Me

JavaScript PC Emulator : JsDOSBox
by Kevin O'Dwyer kevodwyer _at_ gmail.com

JavaScript port of jDosbox which is itself a port of DOSBox.  
Built with the assistance of Google Web Toolkit (GWT).

A significant number of changes were required, including but not limited to:
- input event handling
- keyboard key code translation
- output rendering (canvas, webGL)
- threading (lack of)
- date/time/tick handling
- translate dynarec class compile to building Js functions 
- sound mixing and generation. I have tried three different approaches, would benefit from some more work
- unchecked exceptions to checked exceptions (GWT/JS limitation)
- primitive arrays to TypedArrays
- support for Zip file backed virtual file system
and numerous workarounds for various things that don't translate to JavaScript
As with anything that requires R&D, more code was developed and thrown away than actually made it into this codebase.

Project homepage: http://sourceforge.net/projects/jsdosbox/

This program is released under the GPLv2 open source license.
http://www.gnu.org/licenses/gpl-2.0.txt

The following open source projects were used in the making of this project:
jDosbox http://jdosbox.sourceforge.net/	(GPL)
DOSBox	http://www.dosbox.com	(GPL)
gwt-g3d	http://code.google.com/p/gwt-g3d/ (Apache v2)
gwt-nes-port (file upload) http://code.google.com/p/gwt-nes-port/ (GPL v3)  
MIDPath (Zip file handling) http://midpath.thenesis.org/ (GPL)
 - including code from GNU Classpath and phoneME
The Crystal Icon set (config icons) http://www.everaldo.com/crystal/ (LGPL)
Real.java - Java floating point library for MID devices by Roar Lauritzsen (GPL)

HOW TO USE

The first thing to note is that this is a port of DOSBox, so some knowledge is transferable.  
This port is however in beta so not everything DOSBox (or more specifically jDosbox) supports is 
currently available or working.

JsDOSBox has a hardcoded config using:
- 486 machine type with a FPU
- 8 Mb ram
- s3 video card
- sound card emulation

LIMITATIONS
- Only screen modes that use a palette are supported 
- Page faults are not handled correctly
- No network card emulation
- No CD-ROM emulation
- No joystick emulation
- Sound is mono
- No Midi
- No shell

RUNNING

Extract the jsdosbox.zip file from the base source directory.  
This contains all the static JavaScript files to run JsDOSBox.  
The JsDOSBoxTest.html file includes everything to launch and configure the program. 
Take particular note of the input fields at the end of the file that capture the configuration parameters.  
The files are to be copied into the appropriate directory of your favourite web server.  
REMEMBER:  Due to browser caching, make sure to flush your browser cache as you configure the program.


Configuration parameters
    <input id="override" type="hidden" value="false">
If true, a visitor can override the config parameters by appending items to the url query string   
    <input id="screen" type="hidden" value="WebGL">
options are Canvas, CanvasScaled and WebGL.  Default is Canvas (Others currently broken!).  Both CanvasScaled and WebGL use CSS Scaling when necessary.
    <input id="frameskip" type="hidden" value="1"> 
values 0 to 12
    <input id="cycles" type="hidden" value="auto"> 
Indicates cycle strategy. Default is auto.  Values auto, max, limit and ignore.
    <input id="cyclelimit" type="hidden" value="0"> 
The number of instructions the emulator will try to execute up to per millisecond.  Default value is 0 indicating no limit. 
    <input id="core" type="hidden" value="dynamic"> 
either dynamic or normal.  Default is dynamic
    <input id="compilethreshold" type="hidden" value="0"> 
Indicates how often a code block is executed before it is compiled.  Default value is 0 indicating disabled. 
    <input id="mouse" type="hidden" value="false"> 
Mouse emulation.  Default value is false.  This is experimental.
    <input id="maxFPS" type="hidden" value="12"> 
Reduces the number of frames per second to no more then the value set. Default value is 12.
    <input id="forceFPS" type="hidden" value="-1"> 
Attempts to set the internal screen refresh frequency.  Expressed in fps.  Use with caution.  Default value is -1 indicating disabled.
    <input id="autorun" type="hidden" value="imgmount c http://localhost:8080/war/doom.zip -t zip !c:!cd doom!doom.exe"> 

The Autorun parameter captures what gets executed by the emulator.  The '!' character is used as a newline delimiter.  
The first instruction details the specifics of the disk image to use and subsequent instructions indicate what to execute.  
The disk image should be copied into the same directory as the html file and the URL set accordingly.  
The final execution instruction must contain .exe or .com

Currently RAW and zip disk images are supported.  make sure to append -t zip when using zip files.

sound emulation is hardcoded to mono.
PC Speaker emulation suffers from constant ticks.  
The SoundBlaster configuration is set to Interrupt 7, DMA 1 and port 220. No midi
Configuration parameters
<input id="nosound" type="hidden" value="false"> 
enable sound.  Default is nosound=false
<input id="sbtype" type="hidden" value="sb1">
options are sb1, sb2, sbpro1, sbpro2, sb16, gb, none. Default is sb1
<input id="oplmode" type="hidden" value="none">
options are auto, none. Default is auto
<input id="gravis" type="hidden" value="false">
enable gravis emulation.  Default is gravis=false

<input id="mixerrate" type="hidden" value="11025">
it is not recommended using a Mixing Freq > 11025Hz.  A value of 8000 is the current default. Shared by all audio devices.
<input id="jsbuffer" type="hidden" value="2048"> 
the size of the sample sent to Web Audio decoder. Actually it is x2 the real size as mono is the current default
<input id="modfactor" type="hidden" value="55">
optional fudge parameter.  This determines how often sound output is generated. The emulator tries to guess
the right interval based on the jsbuffer size and mixerrate.  The lower the value the greater the rate of output generation.
For a 8000khz mixer and a jsbuffer size of 2048, a reasonable modfactor is 55

Internal sound parameters.  Additional dials to tweak.  The same meaning as the equivalent jdosbox params. 
    <input id="blocksize" type="hidden" value="2048"> 
    <input id="prebuffer" type="hidden" value="40"> 

BUILDING

Built using Google Web Toolkit.  You will need GWT and the GWT eclipse plugin.  
Use at least GWT version 2.5
Everything needed to build is under the src directory.  
You will also need the gwt-g3d jar file from http://code.google.com/p/gwt-g3d/