DOSBox-X offers a flexible video pipeline: theDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/joncampbell123/dosbox-x/llms.txt
Use this file to discover all available pages before exploring further.
[sdl] section controls how the emulator presents its window and which low-level rendering backend is used, the [render] section applies post-processing like scalers and aspect-ratio correction, and the [ttf] section activates a special TrueType font output mode designed for text-mode productivity applications. Getting these sections right makes a tangible difference between a blurry, stretched image and a crisp, pixel-perfect display.
[sdl] — Window and output backend
The [sdl] section is read first and determines the output surface DOSBox-X draws to.
Output renderer
The video backend used to present emulated video to your monitor.
| Value | Description |
|---|---|
default | Automatically pick the best available backend |
surface | Software SDL surface — most compatible, no hardware scaling |
overlay | SDL overlay (SDL1 only) |
ttf | TrueType font output (text modes only; see [ttf] section) |
opengl | OpenGL with bilinear filtering |
openglnb | OpenGL nearest-neighbour (no blurring) |
openglhq | OpenGL with high-quality upscaling |
openglpp | OpenGL pixel-perfect scaling |
ddraw | DirectDraw (Windows only) |
Fullscreen settings
Start DOSBox-X directly in fullscreen mode. Press Host+F (F11+F on Windows, F12+F elsewhere) to toggle back to windowed mode.
Resolution to use in fullscreen. Accepted values:
original— use the emulated resolution (e.g. 320×200)desktop— use the native monitor resolution- A fixed size such as
1024x768or1920x1080
Scale the windowed output to this size. Only works with backends that support hardware scaling (
output=surface does not scale). Use original to display at native resolution, or specify a size like 1280x960.Window appearance
Maximize the DOSBox-X window at startup (SDL2 and Windows SDL1 builds only). For TTF output, use
fullscreen instead.Set the window transparency level. Valid range is
0 (fully opaque) to 90 (highly transparent). Applies in both windowed and fullscreen modes on SDL2 and Windows SDL1 builds.Width of the overscan border in pixels (0–10). Only applies to
output=surface. Adds a coloured border around the image, mimicking the border area of a real CRT monitor.Override the text displayed in the DOSBox-X title bar. Leave empty for the default title.
Show the DOSBox-X version and current emulation speed in the title bar.
Show the cycles count (FPS) and emulation speed relative to real-time in the title bar. Useful for performance tuning.
Show or hide the menu bar. Disable to reclaim vertical screen space, but note that many DOSBox-X features are only accessible through the menu.
Common [sdl] examples
- Windowed pixel-perfect
- Fullscreen desktop
- Maximised OpenGL
[render] — Scalers and aspect ratio
The [render] section applies effects to the emulated video before it reaches the output backend.
Aspect ratio correction
Enable or configure aspect ratio correction. DOS VGA games typically target a 4:3 display; enabling correction prevents games from appearing squashed or stretched on widescreen monitors.
| Value | Behaviour |
|---|---|
false | No correction — image is scaled to fill the window |
true | Correct to 4:3 by padding with black bars |
nearest | Nearest-neighbour correction (sharp but may introduce minor artefacts) |
bilinear | Bilinear correction (smoother, slight blur) |
Override the target aspect ratio for correction.
0:0 uses the default 4:3 ratio. -1:-1 uses the original image ratio (no black bars). Any other value like 16:9 forces that ratio.Scalers
A software scaler applied to the emulated image before display. Append
forced to always apply the scaler even when the emulator thinks it would not help (e.g. hq2x forced). Ignored for output=openglpp and TTF output.Common scalers:| Scaler | Description |
|---|---|
none | No scaling |
normal2x / normal3x / normal4x | Simple pixel doubling/tripling/quadrupling |
hq2x / hq3x | High-quality upscaling with anti-aliasing |
advmame2x / advmame3x | AdvanceMAME LQ scaler, sharp and fast |
xbrz / xbrz_bilinear | xBRZ edge-detection scaler (high quality, more CPU) |
tv2x / tv3x | TV scanline simulation |
scan2x / scan3x | Scanline overlay effect |
gray / gray2x | Greyscale output |
hardware2x … hardware5x | Hardware-accelerated scaling (for OpenGL/Direct3D) |
Scan-line and font rendering
Emit two scanlines per source line, matching real VGA behaviour (e.g. 320×200 renders as 640×400). Disable this for pixel-perfect scaling (
output=openglpp) or when using multi-line scalers like hq2x.Allow 9-pixel wide text-mode fonts instead of the standard 8-pixel width, matching the behaviour of real VGA hardware in 80-column text mode.
Display the Euro symbol (€) in place of the ASCII character at this position (33–255). For example,
euro = 128 substitutes the Euro symbol wherever ASCII 128 (Ç) appears. Set to -1 to disable.Number of emulated frames to skip before drawing one. Higher values reduce the rendering load on the host CPU but make motion appear less smooth. Leave at
0 for normal use.[ttf] — TrueType font output
When output = ttf is set in [sdl], DOSBox-X replaces the rasterised VGA text renderer with a high-resolution TrueType font renderer. This is ideal for word processors and text-based applications where crisp, scalable text is more important than pixel-accurate CRT emulation.
TTF output only works in DOS text modes (80×25 and similar). When a DOS program switches to a graphics mode, DOSBox-X temporarily switches to the output defined by
outputswitch (default: auto).Path or name of the TrueType (
.ttf), OpenType (.otf), font collection (.ttc), or bitmap font (.fon) file to use. If only a name is given (e.g. consola), DOSBox-X searches the working directory and system font directories. Leave empty to use the built-in font.Font point size (minimum 9). When set, overrides the
winperc window-percentage sizing. Set to 0 to let winperc control the size instead.Render bold text visually (requires a word processor set via
wp). Uses the font specified in fontbold if provided, otherwise synthesises bold automatically.Render italic text visually (requires
wp). Uses fontital if provided, otherwise slants characters automatically.Draw underlines on underlined text (requires
wp).Draw strikethrough on struck text (requires
wp).Word processor compatibility mode. Enables application-specific colour schemes and text attribute handling.
| Value | Application |
|---|---|
wp / wp6 | WordPerfect (optionally with version number) |
ws | WordStar |
xy / xy4 | XyWrite (optionally with version number) |
fe | FastEdit |
Control the cursor blink in TTF output.
true enables blinking at the default rate. false shows a static cursor. An integer from 1 (fastest) to 7 (slowest) sets the blink rate. 0 hides the cursor entirely.