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

GENERAL USAGE
Unzip and just run dosbox.exe. That's it.

Go to [Quick Launch] from [Main] menu to choose an executable 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, 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 you do not have DOSBox.Conf, it will automatically 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 WINDIB driver.bat : Run DOSBox with WINDIB driver.
  • Run save states manager.bat : Run saved state files manager.

For all users:

  • Do not use a configuration file created by older version of DOSBox.
  • Changing screen output frequently can make DOSBox unstable.
  • Hardware2x / 3x scalers do not work with output=surface.
  • Disney should be disabled while printer emulation is being enabled. (printer=true, disney=false)
  • To enable MT-32 (MUNT) emulation, you need some ROM files. Follow the instructions from DOSBox Status window.

For Windows 98 / ME / 2000 users:

  • If DOSBox does not start properly, set output=ddraw in dosbox.conf.
  • Otherwise, you can remove dosbox.conf and run "Run DOSBox configuration.bat" in TOOLS directory and select 2.

For Windows Vista / 7 or higher:

  • Do not overwrite/extract to "Program Files\DOSBox" or "Program Files (x86)\DOSBox" directory.
  • You can run an executable with 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 - F9 : Show/Hide menu bar
  • Ctrl - Alt - F12 : Unlock/Lock speed

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.exe [-nomenu] [-nogui] [-showcycles]

  • -nomenu
    Hide menu bar at startup. To show it, press Ctrl-Alt-F9.
  • -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 for dosbox.exe is recommended for easy use. For other DOSBox parameters, read official manual.


DOS commands
The follwoing 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 editor.
  • APPEND.EXE : Similar to PATH command.
  • XCOPY.EXE : Advanced COPY command.
  • MOUSE.COM : Enables/disables DOSBox mouse driver. To uninstall it, type "mouse /u". (It also can be turned on/off in menu)
  • 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.
  • DOSIDLE.EXE : CPU idling software for DOS
  • 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.
  • TIME : Displays time or synchronizes it with host. (h-a-l-9000)
  • DATE : Displays/Changes date or synchronizes it with host. (h-a-l-9000)

CONFIG.SYS commands

  • LASTDRIV.COM
  • FILES.COM
  • FCBS.COM
  • DEVICE.COM
  • BUFFERS.COM

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.

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


SAVE STATES

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.
To list and remove saved states, run "Run save states manager.bat" in TOOLS directory.


MENU

A nice GUI menu bar has been integrated into my build. Though it is currently only for Windows 2000 or later, I am working on implementing the menubar for the other platforms.

  • Main
  • Cpu
  • Display
  • Sound
  • DOS
  • Capture
  • Drives

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 should 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-F9 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. If you still encounter the issue, run "Run DOSBox without GUI.bat" in TOOLS directory and try again.
  • 3dfx voodoo chip emulation (glide=emu)
    According to kekko's description:
    - 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. (might be slow)
    (If you set glide=true, you will get glide wrapper (glide2x.dll) and glide2x.ovl.)

    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

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