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.
[render] section governs how DOSBox-X translates the raw emulated video signal into what you see on screen, including frame skipping, aspect-ratio correction, software scalers, and scanline doubling. The [ttf] section configures the TrueType font output mode, which replaces the standard raster video pipeline with a high-quality scalable font renderer — ideal for text-mode applications, word processors, and terminal use. Both sections work together when output=ttf is selected in [sdl].
Frame Rendering
Number of emulated frames DOSBox-X skips before drawing one frame to the host screen. Increasing this value reduces the host GPU load at the cost of visible jitter. A value of
0 means every frame is drawn. Values greater than 0 are occasionally useful on very slow host hardware.When enabled, double-scanned video modes emit two identical scanlines for each source line, faithfully reproducing the physical VGA output behavior (e.g. 320×200 is rendered as 640×400). When disabled, double-scanned modes are rendered at their native source resolution. Turning this off is recommended when using pixel-perfect scaling (
output=openglpp) and may be required for some scalers to work correctly.Aspect Ratio
Aspect-ratio correction mode. When the emulated display pixel ratio is not 4:3, enabling this setting adds black bars or adjusts the image to restore the correct proportions. Possible values:
false/no/0— no correction; image is stretched to fill the windowtrue/yes/1— correct to 4:3 using the output driver (recommended for OpenGL/Direct3D)nearest— correct with nearest-neighbor samplingbilinear— correct with bilinear sampling
output=surface, correction is done by adjusting the rendered line count (may cause slight quality loss and does not mix well with multi-line scalers like hq2x/hq3x).Explicit target aspect ratio used during aspect-ratio correction, expressed as
W:H. Special values:0:0— use the default 4:3 ratio-1:-1— preserve the original image ratio without correction- Any other ratio, e.g.
16:9, forces that specific ratio
Text Mode Options
Allow 9-pixel wide character glyphs in text mode, matching how real VGA hardware renders the standard IBM PC font. When disabled, all characters use 8-pixel wide glyphs. Affects the visual fidelity of box-drawing and line characters in text-mode applications.
Display the Euro symbol (€) in place of the ASCII character at the specified code point (valid range: 33–255). For example,
euro=128 replaces the Ç character (ASCII 128 in CP437) with the Euro symbol. Set to 0 or -1 to disable this substitution.Scalers
Software scaler used to enlarge or enhance low-resolution video modes before output. Append
forced after the scaler name to apply the scaler even when the result may not look ideal (e.g. normal2x forced). Append prompt to show a confirmation dialog before forcing. Scalers are ignored for output=openglpp and TTF output.Available scalers:none— no scalingnormal2x,normal3x,normal4x,normal5x— simple pixel replicationadvmame2x,advmame3x— AdvMAME pixel-art scalersadvinterp2x,advinterp3x— AdvInterp scalershq2x,hq3x— high-quality scalers (not suitable withoutput=surfaceaspect correction)2xsai,super2xsai,supereagle— 2xSaI family scalerstv2x,tv3x— TV scanline effectrgb2x,rgb3x— RGB phosphor dot effectscan2x,scan3x— scanline simulationgray,gray2x— grayscale outputhardware_none,hardware2x,hardware3x,hardware4x,hardware5x— pass-through for hardware (OpenGL/Direct3D) shader pipelinexbrz,xbrz_bilinear— xBRZ high-quality edge-preserving scaler (handles aspect correction internally when used withoutput=surface)
Path to a GLSL shader source file for use with OpenGL output (
output=opengl or variants). Set to none to disable, default for the DOSBox-X default shader, or one of the built-in shader names: advinterp2x, advinterp3x, advmame2x, advmame3x, rgb2x, rgb3x, scan2x, scan3x, tv2x, tv3x, sharp. Can also be an absolute path or a file in the glshaders subdirectory of the DOSBox-X config directory.Direct3D pixel shader effect to use (Windows only). The
.fx effect file must reside in the Shaders subdirectory. Append forced to apply the shader even when the result may not be ideal.When enabled, best-fits the rendered image to the window. Intended for use with
output=direct3d, fullresolution=original, and aspect=true.Color palette for monochrome display emulation (MDA, Hercules). Append
bright for a brighter luminance. Possible values: green, amber, gray, white.TrueType Font (TTF) Output — [ttf]
The[ttf] section is active when output=ttf is set in [sdl]. In this mode, all text-mode rendering is performed by scaling a TrueType (or compatible) font rather than using rasterized VGA glyphs.
Font Selection
TrueType font to use for TTF output. Specify a font name (e.g.
consola), a relative path (searched in the working directory and the system font directory), or an absolute path. The .TTF extension may be omitted. OTF, .FON, and .TTC fonts are also supported. For CJK code pages, a font containing CJK characters (e.g. GNU Unifont or Sarasa Gothic) is required. Leave blank to use the built-in font.Optional bold TrueType font used to render bold text when a word processor (
wp) is configured. For example, consolab uses Consolas Bold.Optional italic TrueType font used to render italic text when a word processor is configured. For example,
consolai uses Consolas Italic.Optional bold-italic TrueType font used to render bold-italic text when a word processor is configured. For example,
consolaz uses Consolas Bold Italic.Layout & Sizing
Font point size for TTF output. When set to a positive value (minimum 9), it overrides the
winperc window-percentage sizing. Set to 0 to use winperc instead.Window size as a percentage of the screen when using TTF output (100 = full screen). Ignored if
ptsize is set to a non-zero value.When enabled (the default), the TTF window size is limited to 60% of the screen. Disable this limit when using more than 25 lines in a TTF window, so that larger font sizes are not artificially constrained.
Number of text rows displayed in TTF output mode.
0 uses the default (usually 25).Number of text columns displayed in TTF output mode.
0 uses the default (usually 80).When enabled, text is rendered from right to left instead of the normal left-to-right order. Useful for Arabic, Hebrew, and other right-to-left scripts.
Output backend DOSBox-X switches to from TTF mode when a graphical (non-text) video mode is requested by a DOS program. Possible values:
auto, surface, opengl, openglnb, openglhq, openglpp.Word Processor Mode
Activate word-processor-specific display features. Specify the abbreviation and optionally a version number:
WPorWP6— WordPerfect (with optional version number, e.g.WP6)WS— WordStarXYorXY4— XyWrite (with optional version number, e.g.XY4)FE— FastEdit
Render bold text visually in TTF output. Requires a word processor to be set via
wp. Uses the font specified by fontbold if available, otherwise applies automatic bold rendering.Render italic text visually in TTF output. Requires
wp to be set. Uses fontital if available, otherwise automatically slants the characters.Render underlined text visually in TTF output. Requires
wp to be set.Render strikeout (strikethrough) text visually in TTF output. Requires
wp to be set.Cursor & Colors
Controls the text cursor blinking behavior in TTF output. Set to
true for a blinking cursor or false to disable blinking. You may also set an integer from 1 (fastest blink) to 7 (slowest blink), or 0 for no cursor at all.Custom color scheme for TTF output. Provide all 16 DOS color values (indices 0–15) as space-separated RGB tuples
(r,g,b) or HTML hex values #RRGGBB. Leave blank to use the default DOS color palette.Automatically enable double-byte character set (DBCS) rendering for Chinese, Japanese, and Korean characters when a CJK code page (932, 936, 949, or 950) is active. Applies to both screen display and printing.
When enabled, forces the current TrueType font (set via
font) to be used for printing output in addition to display rendering.Enable the GBK character set extension (beyond the standard GB2312 charset) for Simplified Chinese TTF output or DOS/V emulation. Requires a font with GBK coverage.
Enable the ChinaSea and Big5-2003 extension (beyond the standard Big5-1984 charset) for Traditional Chinese TTF output. A TTF/OTF font with ChinaSea characters (such as the included SarasaGothicFixed font) is required.
When enabled, activates FEP (Front-End Processor) control for Japanese DOS/V applications and changes character-attribute blinking to high-brightness mode.