SVN-specific manuals | Main | Usage | MB6 Patches
Official manuals | README | Video Instructions

Usage
Contents

1. GENERAL USAGE
2. SPECIAL KEYS
3. PARAMETERS
4. DOS COMMANDS
5. SAVE STATES
6. MENU
7. GLIDE EMULATION
8. Direct3D
9. Opengl-HQ
10. DONGLE SUPPORT

GENERAL USAGE Unzip and run DOSBox executable. That's it. Go to [Quick Launch] from [Main] menu to choose an executable(*.exe, *.com, *.bat) to run. Otherwise, just drag and drop it into DOSBox window. Some DOS games complain due to DOS environment settings like XMS/EMS memory. Others might require CD-ROM mounting.
You can prepare them via menu or commandline in advance for the games to work properly. For details, open official manual to see 11. Troubleshooting section.

To disable automatic-mount on command prompt, open DOSBox configuration file and set automount=false in [dos] section.

Tools:
There are several tools provided in TOOLS directory.

- Run DOSBox configuration.bat : Open DOSBox configuration file with notepad. If DOSBox.Conf does not exist, it will automatically create a new configuration file.
- Reset DOSBox configuration.bat : Remove DOSBox.conf and create a new configuration file.
- Read manuals.bat : View DOSBox manuals.
- Install movie codec.bat : You can install/uninstall ZMBV movie codec used to edit/watch movies captured by DOSBox.
- Run DOSBox without GUI.bat : Run DOSBox without GUI.
- Run DOSBox with DirectX driver.bat : Run DOSBox with DirectX driver. Use if you encounter compatibilty issues.

For all users:

- Do not use a configuration file created by older versions of DOSBox.
- Changing screen output frequently can make DOSBox unstable.
- Hardware2x / 3x scalers do not work with output=surface.
- Disney must be disabled while printer emulation is being enabled. (printer=true, disney=false)
- Disney must be disabled while MIDI is being enabled. (MB6)
- To enable MT-32 (MUNT) emulation, you need some ROM files. Follow the instructions from DOSBox Status window.
- If you encounter graphical issues, try to set linewise, char9, and multiscan to another value. Also search for some utilities like UNIVBE or S3VBE20.
- If you get LPT1 creation failed error message, please set parallel1=file in your configuration file.
- Overscan works when output=surface is set.
- DOSBox mixer cannot control MIDI volume itself when mididevice is set to win32 (default).
- This build may not work properly without SSE2 support. Please check the following list.
  List of CPUs with SSE2 support
  - AMD K8-based CPUs (Athlon 64, Sempron 64, Turion 64, etc.)
  - AMD Phenom CPUs
  - Intel NetBurst-based CPUs (Pentium 4, Xeon, Celeron, Celeron D, etc.)
  - Intel Pentium M and Celeron M
  - Intel Core family (including Intel Core 2, Intel Core i5, Intel Core i7)
  - Intel Atom
  - Transmeta Efficeon
  - VIA C7
  - VIA Nano

For Windows 98 / ME / 2000 users:

- Please use older versions of DOSBox if you encounter any problem

For Windows Vista / 7 or higher:

- You can run an executable with an administrative privilege, but it is not recommended for security.

SPECIAL KEYS Several experimental patches provide the following additional special keys. CPU Core-switch (from gulikoza)

- Ctrl - 1 : Set to Normal core
- Ctrl - 2 : Set to Full core
- Ctrl - 3 : Set to Dynamic core
- Ctrl - 4 : Set to Simple core
- Ctrl - = : Maximize CPU cycles

Daum Cafe features (from ykhwong)

- Ctrl - Alt - Enter : Show/Hide menu bar
- Ctrl - Alt - F12 : Continuous turbo mode (Enabled by DirectDraw output or DirectX driver)

Save / Load states (from ZenJu)

- Alt-F5 : Save States
- Alt-F6 : Prev Slot
- Alt-F7 : Next Slot
- Alt-F9 : Load States

For more information about other special keys, read official manual.

PARAMETERS Several experimental patches provide the following additional parameters. Usage dosbox [-nomenu] [-nogui] [-showcycles]

- -nomenu
  Hide menu bar at startup. To show it, press Ctrl-Alt-Enter.
- -nogui
  Disable Graphic User Interface. It might fix some bugs related to GUI.
- -showcycles
  Show details including the current cycles and FPS on title bar.

Creating a shortcut is recommended for easy use. For other DOSBox parameters, read official manual.

DOS commands The following additional commands are provided from a patch called "More parameters support in internal commands." and FreeDOS, and some other patches provided by Moe and h-a-l-9000. These commands are unofficial part of DOSBox. External commands

- 50.COM, 28.COM : Changes the number of line displayed on shell.
- EDIT.COM : Opens FreeDOS file editor.
- APPEND.EXE : Similar to PATH command.
- COPY.EXE : COPY command with more parameters.
- XCOPY.EXE : Advanced COPY command.
- MOUSE.COM : Enables/disables DOSBox mouse driver. To uninstall it, type "mouse /u". For y-axis reverse, type "mouse /v" (They also can be found in GUI)
- IMGMAKE.COM : Creates a floppy/harddisk (.img) image. (h-a-l-9000) Just type IMGMAKE for more information.
- MOVE.COM : Moves a file or directory to another location
- TREE.EXE : Graphically displays the directory structure of a drive/path.
- FIND.EXE : Print lines of a file that contains a string
- DOS32A.EXE, DOS4GW.EXE : DOS Extenders

Internal commands

- ADDKEY : It generates artifical keypresses. (Moe)
- VOL : View volume name of disk.
- LABEL : Set volume name of disk.
- MORE : Displays output one screen at a time.
- PROMPT : Shows/Changes command prompt. It supports special characters including escape codes. Default value is PROMPT $P$G.

CONFIG.SYS commands

- LASTDRIV.COM
- FCBS.COM
- DEVICE.COM
- BUFFERS.COM
- FILES command is provided by DOSBox configuration. (h-a-l-9000)

The following commands are official part of DOSBox but include some unofficial changes.

- INTRO command shows DOSBox introduction. You can select one of the items by arrow keys.
- DIR displays a list of files and subdirectories in a directory. You can also see volume label and serial number.
- MEM command is available with some parameters like /C and /P.
- COPY command does not exist in shell but provided as a file in Z drive.

For more information about DOS commands, type "HELP" on prompt.

SAVE STATES A patch for saving states to memory was provided by ZenJu. For more information, go to http://vogons.zetafleet.com/viewtopic.php?t=25274. You can save, load or remove states by going to Main menu. For shortcut keys, see section "Special keys" above.

In order to manage your saved states, run "Run save states manager.bat" in TOOLS directory.

MENU A small GUI menu bar has been integrated into my build. It is currently only for Windows 2000 or later.

- Main
- Cpu
- Video
- Sound
- Dos
- Capture
- Drive

Note that this menu bar is still experimental and it is NOT supported by DOSBox developers.

If you want to mount image files with various settings like size(cylinders, heads and sectors specification of the drive), please use IMGMOUNT command instead. (size is only for bootable hard disk images)

GLIDE EMULATION Make sure your game directory must not include glide2x.ovl or glide2x.dll There are two ways to use glide emulation:

- Glide wrapper (glide=true)
  OpenGlide wrapper patch for DOSBox is maintained by Gulikoza.
  Set glide=true in your DOSBox configuration file to play Glide games.
  How to enjoy glide games in FULLSCREEN
  1. Hit Alt-Enter to switch to fullscreen. (or set fullscreen=true in dosbox.conf)
  2. Run your glide game and enjoy.
  Hide menu bar by pressing Ctrl-Alt-Enter if you still see it in fullscreen.
  If you have any problem using other glide wrappers, please follow the instruction below.
  1. Do not change glide2x.ovl with another one. You will only need to change glide2x.dll
  2. Hit Alt-Enter to switch to fullscreen. (or set fullscreen=true in dosbox.conf)
  3. Run your glide game and enjoy.
  NOTE: Make sure that your game directory does not include glide2x.dll / glide2x.ovl
  If you have installed a wrapper like nGlide, please remove glide2x.dll in DOSBox directory to take an effect.

- 3dfx Voodoo chip emulation (glide=emu)
  Kekko's description is here:
  - higher compatibility with titles (even those with integrated .ovl)
  - portability
  - integration with dosbox internal renderer: full-screen, different output modes and video capture would be supported
  - no need of external libs
  - d3d support for win9x games
  How to play:
  Set glide=emu in your DOSBox configuration file. It will use glide2x_emu.ovl instead of glide2x.ovl, resulting in slow performance.
  (On the other hand, if you set glide=true for using glide wrapper, glide2x.dll and glide2x.ovl will be used.)
  You may set your output to OpenGL for hardware acceleration.
  For more information, go to http://vogons.zetafleet.com/viewtopic.php?t=25606
  Do not ask how to build or how to speed up there.

Direct3D Written by gulikoza New options: Direct3D output now supports the use of custom pixel shaders for picture scaling. To use it your card has to support PS2.0 (Radeon >=9500, GeForce >=FX5200) or PS1.4 for scale2x_ps14.fx (Radeon >= 8500).

** These shaders are currently available :
1) General

- point.fx - normal (nearest neighbor) resize
- pilinear.fx - bilinear resize (slightly blurry)
- scale2x.fx - advmame2x resize
- scale2x_ps14.fx - advmame2x resize (PS1.4 version)
- 2xSaI.fx - 2xSaI resize
- 2xSaI_sRGB.fx - 2xSai (Gamma Corrected) resize

2) The following are all modifications of the GLSL shaders for OGL2 PSX plugin. Ported to .fx format by guest(r).
Some of the shaders also have settings you can modify by editing the .fx file.

- GS2x.fx
- GS4x.fx
- GS4xColorFilter.fx
- GS4xFilter.fx
- GS4xScale.fx

3) Other shaders...

** How to use
1. Open dosbox.conf with notepad.
2. Set 'output=direct3d' to enable Direct3D. Follow one of these options.

1. Set 'scaler=hardware2x' or 'scaler=hardware3x'
2. Set 'scaler=none'. Set the values like 640x480 in fullresolution and windowresolution.

3. Then set 'pixelshader=' option to one of the shaders.
When pixel shader is active DOSBox will report it in the console: D3D:Pixel shader output enabled
If you don't get this line then pixel shader effects are not in use.

OpenGL-HQ Written by Moe If you have certain problems with OpenglHQ, please set fulldouble to true in your config. This readme documents version 2006-12-15 of OpenGL-HQ, if you got a later version there's a slim chance I forgot to update this :) The current version and screenshots can be downloaded from http://garni.ch/dosbox/

OpenGL-HQ is a video "driver" for SDL that uses your graphics hardware to scale the output to any size you want. It was originally written for 2D games/emulators like dosbox, scummvm or exult.

WARNING:
This is beta quality software. While it works nicely for me and several other people, expect bugs to be present. If something doesn't work, first check for a new version. Please mail me if you encounter anything that's not yet listed in the README.

Features:

- uses your hardware to get fast scaling
- scales any 2D SDL program
- scales with any scaling factor, even fractional ones
- switches back to the native driver if an app tries to use OpenGL
- portable
- configurable like SDL
- see the screenshots at the URL above, really

Requirements:
- a Radeon 9600, GeForce 5700 or higher with current driver (OpenGL extension ARB_fragment_program must be supported and hardware-accelerated, EXT_framebuffer_object is also needed)
- OpenGL-support for your OS in SDL (which means Windows, Linux/X11 or MacOS X)

Limitations:
- may show bad performance with programs that already provide high-resolution output or with high-quality driver settings (Radeon 9600-9800 class chips are driven at their limits)
- MacOS X untested (but should work)
- it has become very unlikely, but it is still possible that desktop resolution is not autodetected correctly; use SDL_OPENGLHQ_FULLRES in that case

Bugs unlikely to be fixed, or of unknown origin:
- ATI's Triple-Buffering feature interferes with some apps; if you see lockups or similar, try setting SDL_OPENGLHQ_DOUBLEBUF as shown below
-- needs to be confirmed against current drivers

Bugs to be fixed: none known

If you see any problems, CHECK THE TROUBLESHOOTING SECTION BELOW. If your problem is not solved there, please write as detailed as you can:
Tell me what you did (exactly!), what you expected to happen, what happened instead, and include screen shots of the problem. Include any relevant config files as well (dosbox.conf for dosxbox, for example).

How to use (Quickstart):
This is a windows quickstart guide. Other systems adjust as needed.

1) Copy SDL.DLL into the application's directory, overwriting the shipped version
2) Create a batch file (using Notepad) with these contents:

> set SDL_VIDEODRIVER=openglhq
> set SDL_OPENGLHQ_WINRES=800x600
> <name of your application>.exe

3) Save the file as <name of your application>.bat in the same directory as the EXE file is
4) Double-click this batch file to start the application; Create a shortcut or adjust existing shortcuts to use this batch file

Configuration:
Configuration is done via environment variables (just like the rest of SDL). It is recommended to set these options in a batch file (see previous section).

- SDL_VIDEODRIVER - set it to openglhq to use OpenGL-HQ
- SDL_OPENGLHQ_WINRES
- SDL_OPENGLHQ_FULLRES - set to a resolution like "960x720" to set the windowed/fullscreen size in all windowed/fullscreen modes; you may add a bit depth as in "960x720-16"; alternatively, you can specify a fixed scaling factor (like "2.5")
  default: windowed: "1", fullscreen: your desktop resolution
- SDL_OPENGLHQ_VIDEODRIVER - set to the name of your SDL video device (the one you'd normally use for SDL_VIDEODRIVER)
- SDL_OPENGLHQ_DOUBLEBUF - override application's choice of doublebuffering; if set to 1, doublebuffering is always on, if set to 0, doublebuffering is always off; if unset, the application's choice is respected
- SDL_OPENGLHQ_STATIC
- SDL_OPENGLHQ_DYNAMIC - two parameters which tweak the HQ calculation; the defaults (static 10, dynamic 33) are fine in most cases; to optimize rendering, play with these values (static 0-255, dynamic 0-100)
- SDL_OPENGLHQ_DATA - a directory with data files for OpenGL-HQ - do not set this

You must set SDL_VIDEODRIVER to get any effect at all. If you want windowed applications to be scaled, set SDL_OPENGLHQ_WINRES. Everything else is usually not neccessary, the settings are autodetected.

If you want to set options for ALL SDL apps, you can do so:
Windows: Control Panel -> System Properties -> Advanced -> Environment Variables
Unix-like systems: add "export <name of evironment var>=<value>" to ~/.profile

Performance:
To put it short: Absolutely great. On hardware barely meeting the minimal requirements, running a demanding protected-mode high-resolution SVGA program in DOSBox with frameskip 0 and scaling by a factor of 2, performance drops by just 20%. At frameskip 4, performance difference is at 5-10%.
At VGA resolution scaling by 4, the difference is reduced even more: 12% performance loss at frameskip 0. Software scaling is far worse: Normal2x costs about 20%, advmame2x is at 25%, hq2x (not my optimized version, but the slower HiEnd3D version) about 40%.

Troubleshooting:
Q: Something doesn't work or looks weird.
A: Check that you are running the latest official video drivers. It has not been tested with hacked drivers, and old drivers are known to fail.

Q: DosBox crashes.
A: DosBox has bad error handling at video initialization. Until that's fixed, a crash most probably means your hardware doesn't support OpenGL-HQ.

Q: DosBox locks up when trying to go fullscreen
A: ATI driver issue. Set "fulldouble=false" in your dosbox.conf, or set SDL_OPENGLHQ_DOUBLEBUF

Q: Performance is terrible!
A: You've probably set forced vsync-waiting in Catalsyst Control Center and your app wants double buffering (like "fulldouble=true" in DosBox). On a Radeon 9600-9800 class chip, that's simply too much at higher resolutions. These first fully programmable chips are used to their limits, so that's barely surprising.

Q: It works partly, but some video modes look exactly like before.
Q: Output looks much worse than in your screenshots, blurry and not sharp at all.
Q: WTF? I did everything as shown, and nothing changed?
A: Disable all software scaling in your program. Many emulators default to some kind of scaling, but OpenglHQ can only work with x1 (no) scaling. Moreover, if the program's output is larger than the selected window size, the output is scaled down using traditional bilinear filtering.

Q: My mouse is slow! How can I speed it up?
A: This should mostly be fixed in the last release, but your backend video driver might change acceleration setting when grabbing the mouse. At least the x11 driver does that, and you can configure it using environment variables.

For more help, search the "DosBox Patches" forum at http://vogons.zetafleet.com for OpenGL-HQ. This code was first developed for DosBox only, and I regularly read that forum.

Please DO NOT mail Sam Lantinga or the SDL team about this. They aren't involved in this in any way at all.

License:
SDL - Simple DirectMedia Layer OpenGL-HQ scaling
Copyright (C) 2005, 2006 Jorg Walter <jwalt@garni.ch>

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

The SDL patch uses code published on the SDL mailing list in January 2005 for desktop resolution autodetect.

Credits:
Many thanks to all VOGONS users who assited in testing and providing windows builds. Even more thanks to gulikoza from the VOGONS forums for porting the code to EXT_framebuffer_object.

History:
2006-12-15 fix a subtle mouse movemement bug mainly observable in fullscreen apps, improve API compatibility, reduce needless pixel copying, working MacOS X support
2006-11-22 fix 16-bit video modes on ATI cards, improve compilation sequence, improve rendering accuracy and speed by reducing complexity
2006-11-21 use EXT_framebuffer_object extension for rendering, fix threading issues, improve performance, port to SDL-1.2, make 64-bit-clean

DONGLE SUPPORT This is DosBox handler of 93c46 copy-protection dongle connected to LPT port. At least Rainbow Sentinel Cplus and MicroPhar are 93c46-based dongles. 93c46 memory chip contain 64*16 words. More on it: http://www.atmel.com/dyn/resources/prod_documents/doc0172.pdf

Few notes:

* It is unable to detect dongle presence on software side, so, software
usually reading some cell (often 0x3F) and check magic value.

* Wiring scheme may differ from dongle to dongle, but usually,
DI (data input), SK (clock), CS (chip select) and power lines are
taken from D0..D7 in some order.

* DO (data output) may be connected to ACK or BUSY printer lines.

More information: http://blogs.conus.info/node/56

-- dennis@conus.info

SVN-specific manuals | Main | Usage | MB6 Patches
Official manuals | README | Video Instructions