dosbox-staging 0.75.0 Release Notes

Installation instructions:

The dosbox-staging project was created September 15, 2019 as a soft-fork of the SourceForge-based DOSBox project, which is a separate project having its own schedule and development priorities.

Abstract

These release notes summarize the changes made to dosbox-staging since the project's inception through to the release of version 0.75.0. This includes:

Table of Contents

§ Introduction

This document contains the release notes for dosbox-staging 0.75. It describes recently added, changed, or deleted features of dosbox-staging.

All users are encouraged to consult the New Features in Detail and Known Issues sections before using dosbox-staging, as these describe important interface changes as well as information discovered late in the release cycle or after the release.

§ New Features in Detail

New features originating from our upstream (DOSBox) are marked with "SVN".

§ Upgrade to SDL 2.0

SDL 2.0 is a major update to the SDL 1.2 codebase, which has been unmaintained since 2013. SDL 2.0 supports more input devices; more output interfaces such as Wayland, and OpenGLES 1 and 2; low-latency audio using OpenSL ES; and improves cross-platform consistency.

The migration to SDL 2.0:

One example includes the new texture output mode, which uses SDL's 2D hardware-accelerated API rendering to a platform-specific backend.

For example, Windows users can test:

[sdl]
output           = texture
texture_renderer = direct3d11

macOS users can try Metal:

[sdl]
output           = texture
texture_renderer = metal

and everyone can use OpenGL as texture backend:

[sdl]
output           = texture
texture_renderer = opengl

Or just use texture_renderer = auto to let SDL pick the backend appropriate for your Operating System.

§ Support FLAC, Opus, and MP3 CD-DA tracks

FLAC, Opus, and MP3 (as well as MP2 and MP1)-encoded audio can be imgmounted as CD-DA tracks in dosbox-staging, in addition to the usual WAV and Vorbis tracks supported by DOSBox. WAV support has been expanded to include Sony's Wave64 format.

dosbox-staging also supports tracks having sample resolutions of 24 and 16-bit; sampling rates of 96, 88.2, 48, 44.1, 22.05, and 11.025 kHz; and stereo or mono channel counts (to the extent each codec supports these variations). You can mix-and-match these properties and track types to best suit each track's content.

The following sample CUE file depicts the use of every codec supported by dosbox-staging:

FILE "data.iso" BINARY
  TRACK 01 MODE1/2048
    INDEX 01 00:00:00

FILE "track02.opus" OPUS
  TRACK 02  AUDIO
    PREGAP 00:02:00
    INDEX 01 00:00:00

FILE "track03.flac" FLAC
  TRACK 03 AUDIO
    INDEX 01 00:00:00

FILE "track04.mp3" MP3
  TRACK 04 AUDIO
    INDEX 01 00:00:00

FILE "track05.w64" W64
  TRACK 05 AUDIO
    INDEX 01 00:00:00

FILE "track06.ogg" OGG
  TRACK 06 AUDIO
    INDEX 01 00:00:00

FILE "track07.wav" WAV
  TRACK 07 AUDIO
    INDEX 01 00:00:00

For devices with sufficient storage, we recommend ripping your CD-ROM audio to (lossless) FLAC tracks and adding seek-points using:

flac -8 --output-name=trackXY.flac trackXY.wav
metaflac --add-seekpoint=1s trackXY.flac

FLAC typically achieves between 50% and 35% compression while producing binary-identical output versus WAV files.

For limited-storage devices such as ARM single-board computers, Opus provides state-of-the-art lossy compression that exceeds all other formats, including Apple's AAC and AAC High-Efficiency formats. Opus allows even further space savings over MP3 or Vorbis track while matching or exceeding them in output quality.

For example, CD-DA tracks consisting of monaural speech can be encoded with:

opusenc --speech --bitrate 24 --downmix-mono trackXY.wav trackXY.opus

When applied to Sierra's Jones in the Fast Lane audio track, Opus compresses it from 373 MB down to 6.4 MB (98.2% savings in disk space) with no discernible loss in quality.

For CD-DA tracks consisting of sound effects and relatively simple music, Opus does fine with a bitrate between 54 and 70, whereas more complex musical tracks might need a bitrate of up to 84. Experiment and find your sweet spot!

opusenc --bitrate 70 trackXY.wav trackXY.opus

If your CD-DA tracks are encoded at 48 kHz (which is Opus's default internal rate), then feel free to configure dosbox-staging's mixer rate to match, which ensures your CD-DA will not be resampled through your audio chain; as your sound card, USB speakers, and HDMI interface all (likely) operate at a native rate of 48 kHz.

[mixer]
rate = 48000

§ Pixel-perfect scaling mode

Pixel-perfect output scales the image by the largest integer multiplier that fits within your monitor's native resolution. For example, given a 1920x1080 monitor and a 320x200 game requiring aspect-correction, each of its pixels would be scaled by 4x5 to produce a 1280x1000 image. This preserves the original artwork without any edge blurring.

To enable pixel-perfect output, apply the following settings to the indicated [section]s of your dosbox-staging configuration file, as follows:

[sdl]
fullscreen = true
output     = texturepp

[render]
scaler   = none
glshader = none

Pixel-perfect looks like this on a 1080p screen:

HoMM2

Heroes of Might and Magic 2 (1996)
640x480 with a pixel aspect ration (PAR) of 1:1, upscaled to 2x2

Wolf3D

Wolfenstein 3D (1992)
320x200 with a PAR of 1:1.2 (non-square pixels), upscaled to 4x5 with a PAR of 1:1.25

§ Resizable window

Being able to click and drag to resize an application's window is not a revolutionary feature by any measure; however it's a welcome addition for dosbox-staging!

This feature is a work-in-progress: it's available on Linux by default, and can be enabled for testing on Windows and macOS by setting the following (but note that it does not yet work correctly on these systems):

[sdl]
windowresolution = resizable

On all systems, the resizable window is only available for output = opengl and glshader = sharp. Support will be expanded to more outputs and shaders in the future versions.

§ AUTOTYPE command

AUTOTYPE is a command-line tool provided by dosbox-staging that performs scripted keyboard entry into the running DOS program or game.

It can be used to reliably skip intros, provide input to answer initial startup or configuration questions, or conduct a simple demo.

Simply run the command to learn more:

Z:> autotype

Some games that benefit from AUTOTYPE on startup are listed on the wiki page.

§ Changed rendering defaults

The following default configuration settings were changed to improve the out-of-the-box experience for the majority of games running on modern hardware.

The default video settings now use SDL's OpenGL rendering backend, apply a 4:3 aspect ratio correction, and scale the image using the sharp OpenGL shader to provide relatively sharp pixels when in fullscreen mode.

Battle Chess

Battle Chess (1988) at 1080p using the default dosbox-staging settings

§ Expand mouse control methods

The prior "autolocking" mouse option used by DOSBox has been renamed in dosbox-staging to capture_mouse, which is configured using two values defining how the mouse behaves.

The first value defines how the mouse is controlled:

The second value defines how middle-clicks are handled:

For example:

[sdl]
capture_mouse = onclick middlerelease

Will capture the mouse on the first click inside dosbox-staging's window, and a middle-click will release the mouse. Note that the prior method to release the mouse still works (pressing Ctrl-F10).

Note that dosbox-staging defaults to seamless mouse capture both to simplify multi-tasking in windowed-mode and provide a frustration-free experience for new users. However, some games and Windows 3.1 make their own adjustments to the mouse position and will cause an offset-effect. In these cases, we recommend switching to fullscreen (Alt-Enter) or configuring the mouse to capture onclick or onstart.

These options do not affect the mouse behavior in fullscreen (Alt-Enter), as the mouse is always captured.

§ Nuked OPL v1.8

The cycle-accurate Nuked OPL3 emulator is now used by default, this change improves AdLib and SoundBlaster FM music emulation accuracy.

This improved accuracy comes at a slightly higher CPU use-cost, which is insignificant for the vast majority of users on typical desktop or laptop hardware.

However, those using dosbox-staging on old or CPU-limited hardware (capable of 30,000 dosbox "cycles" or less, such as the Raspberry Pi 3) will be served best using the fast OPL emulator (see the oplemu documentation provided in the configuration file).

§ Reload key bindings in runtime

Built-in CONFIG shell command is old, but a little-known feature allowing user to reconfigure dosbox-staging at runtime. This is a nifty way to change configuration using e.g. batch scripts based on user input.

Reloading key bindings

User can now change key bindings at runtime by loading them from a file:

Z:\> config -set "sdl mapperfile=<path-to-file>"

Other new options (SVN)

DOSBox added a number of features to the config command. To list them all, run:

Z:\> config /?

§ Configuration file locations

Linux

dosbox-staging's configuration-file location has been updated to comply wit the XDG Base Directory Specification. This means dosbox-staging will no longer going create configuration directories directly in your home directory.

Configuration files are now located in:

~/.config/dosbox/

Users can customize the parent (.config/) location by setting the XDG_CONFIG_HOME environment variable, according to the XDG Specification.

macOS

The path was slightly changed to avoid spaces in the default configuration filename and to group all configuration files in a single directory:

~/Library/Preferences/DOSBox/

Windows

No changes; the configuration files are created in:

C:\Users\<username>\AppData\Local\DOSBox\

§ Modem Phonebook

You can map fake phone numbers to Internet addresses which is useful for programs where limitations on phone number input field are too strict. Create a text file with the name specified in phonebookfile entry in [serial] section in the DOSBox configuration file and add phone-address pairs per line, for example:

5551234 towel.blinkenlights.nl:23

Now you can dial the specified phone number and the emulated modem will connect to the address it's mapped to. Note that phone book does not allow any characters in the phone number that are ignored or denied by a real Hayes compatible modem.

§ 64-bit Dynamic Recompilation (SVN)

DOSBox has had dynamic recompilation support for a long time, but it was limited to 32-bit builds. Support for 64-bit dynarec improves CPU emulation speed and quality across the board - this is especially visible to Linux and macOS users.

Stargunner (1996) freeware; running on Linux x86_64 via Boxtron

Before 64-bit dynarec, this game had serious emulation problems resulting in fluctuating emulation speed (sometimes too fast, sometimes too slow - regardless of cycles settings). This game was designed to run with constant 70FPS and now it runs with constant 70FPS.

* - dosbox-staging 0.75.0 stable Windows build is still 32-bit; Linux and macOS builds are 64-bits.

§ CGA improvements

CGA modes comparison

Maniac Mansion (1987), with forced CGA mode

CGA monochrome mode

Many CGA games from the 80's were designed to support monochromatic cathode-ray tube (CRT) monitors that used either an amber, green, or grayscale-shaded phosphor coating. As such, some games look much better when rendered using a similar monochrome palette. This mode is designed to emulate such displays.

Use machine = cga_mono

User can switch between green, amber, white, and paper-white palettes at runtime using F11.

CGA Composite mode (SVN)

Technical artifacts caused by the composite video format were cleverly used by game developers to generate extra colors (versus non-composite CGA) by manipulating pixel positions on the screen. For example, adjacent pixels would be partly "averaged" (through horizontal overlap), producing interposed solid colors or generating rudimentary transparency effects.

Composite mode was added to DOSBox's CGA emulator in 2012 but was never back-ported to any of its stable releases. Most users know this mode as its commonly included in other DOSBox forks.

User can switch between Color and Composite mode, between CGA early and late models, and adjust hue (all at runtime).

The default keyboard binds for manipulating CGA modes conflict with other essential binds. It's advisable to change them, if you plan to play with this. The default key for turning on composite is F12.

§ GLSL shader support (SVN)

Shaders written in OpenGL Shading Language (GLSL) offload the task of processing the emulated game's output to your GPU hardware.

This allows the image to be altered in many ways, such as emulating the analog artifacts (scanlines, shadow masks, and phosphor glow) present in circa-1980's and 90s CRT monitor, on modern 1080p and greater LCD panels.

The user can change shader by setting the glshader value in the configuration file:

[render]
glshader = sharp

It's also possible to provide your shader implementations by placing .glsl file in the configuration directory, e.g.:

Place test.glsl file in the configuration directory:

(Linux)   ~/.config/dosbox/glshaders/
(macOS)   ~/Library/Preferences/DOSBox/glshaders/
(Windows) C:\Users\<username>\AppData\Local\DOSBox\glshaders\

And select it in the configuration file:

glshader = test.glsl

X-Wing Collector's Edition

STAR WARS™ - X-Wing: Collector's CD-ROM Edition (1994)

Using CRT-Lottes shader on 1080p screen; click to see the fine details. This shader is not bundled with dosbox-staging (yet), you can download it from here.

Note: when using a glshader, we recommend setting the scaler type to none to ensure image post-processing is performed exclusively by the shader (and not a mix of the two).

§ DATE and TIME commands (SVN)

DOS's traditional DATE and TIME commands were added to DOSBox. This allows the user to change the perceived date for software running inside the emulator:

Z:\> text
Current date: Fri 05/01/2020
Type ´date MM-DD-YYYY´ to change.

Z:\> time
Current time: 11:08:23,34

This feature is useful for running old batch scripts and bypassing date checks in some old software.

§ Mount overlay support (SVN)

This feature allows the user to redirect new and changed files to a different location transparently. The files in the overlay and normal drive are merged on startup and kept up to date when the game writes something.

This feature is useful for redirecting save files or configuration files to a different location (e.g. for backup or cloud saves).

Example usage:

Z:\> mount C real
Drive C is mounted as local directory real/

Z:\> mount C backup -t overlay
Overlay backup/ on drive C mounted.

Z:\> C:
C:\> echo foo > test.txt

C:\> type TEST.TXT
foo

File TEST.TXT is written to directory backup, and not to real.

§ Overview of Changes

§ Removed Features

§ Development Changes

§ Known issues

Submit new issues or learn more about existing ones using our bug-tracker: github.com/dosbox-staging/dosbox-staging/issues

§ Contributors

During the dosbox-staging 0.75 development period:

We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project. Thank you!

Maintainers:

Patryk Obara, kcgen, Anton Shepelev (ant-222)

Direct contributors:

Anton Shepelev (ant-222), Joshua Fern, kcgen, Marco Maccaferri, NicknineTheEagle, Nopey Nope, numberZero, Patrick McMorris, Patryk Obara, Troy Campbell, Wouter Wijsman

Testers and wiki contributors:

GranMinigun, kas1e, nemo93, rderooy

Indirect contributors (library or patch authors, upstream SVN developers, etc):

Alexey Khokholov (nukeykt), Arthur Ouellet, David Reid, jmarsh, NY00123, Peter Veenstra, ripsaw8080, Ryan C. Gordon, Sean Barrett, Sjoerd van der Berg, VileRancour, Yann Collet

Changelog

You can read detailed changelog via Git, e.g. using the following command:

git shortlog ^v0.75.0-pre v0.75.0 --no-merges

§ Merged-in community patches and libraries

The following lists those merges performed by maintainers either on behalf-of or making use of patches or libraries authored by community members (in alphabetic order).

kcgen:

Patryk Obara:

Peter Veenstra:

Changes merged-in to SVN:

Michael Zijlstra:

Copyright © 2020 The dosbox-staging project.

DOSBox project: Copyright © 2002-2020 The DOSBox Team.

Arm® and Arm7® are trademarks or registered trademarks of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Clang and LLVM are copyright the University of Illinois/NCSA and at Urbana-Champaign, http://llvm.org

Coverity® is a registered trademark of SYNOPSYS, INC.

The Free Lossless Audio Codec (FLAC), Opus, Vorbis, and Ogg are copyright the Xiph foundation.

The GNU Compiler Collection (GCC) and Git are copyright the Free Software Foundation, Inc.

IBM®, OS/2™, PowerPC™, POWER8™, LinuxONE™, and S/390™ are trademarks of International Business Machines Corporation in the United States and other countries.

Intel®, Core™, and Pentium™ are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.

Mac™ and macOS™ are trademarks of Apple Inc., registered in the United States and other countries.

OpenGL® and OpenGL® ES are trademarks or registered trademarks of Hewlett Packard Enterprise in the United States and/or other countries worldwide.

Windows®, Windows XP®, DirectDraw®, and Visual Studio® are registered trademarks of Microsoft Corporation in the United States and other countries.

Vulkan® and WebGL™ are a registered trademarks of the Khronos Group Inc.

Creative Commons License Creative Commons License Creative Commons License
Content on this site is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
dosbox-staging is licensed under a GNU GPL version 2 or later.