dosbox-staging 0.75.0 Release Notes

2020-05-06

Installation instructions:

• Linux (or Steam on Linux)
• Windows
• macOS

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:

• feature changes, including those added and removed,
• known issues, and
• workflow changes visible to contributors.

Table of Contents

• 1. Introduction
• 2. New Features in Detail
  • 2.1. Upgrade to SDL 2.0
  • 2.2. Support FLAC, Opus, Vorbis, and MP3 CD-DA tracks
  • 2.3. Pixel-perfect scaling mode
  • 2.4. AUTOTYPE command
  • 2.5. Changed rendering defaults
  • 2.6. Expand mouse control methods
  • 2.7. Nuked OPL v1.8
  • 2.8. Resizable window
  • 2.9. Reload key bindings in runtime
  • 2.10. Configuration file locations
  • 2.11. Modem phonebook
  • 2.12. 64-bit dynarec (SVN)
  • 2.13. CGA emulation improvements (SVN)
  • 2.14. GLSL shader support (SVN)
  • 2.15. DATE and TIME commands (SVN)
  • 2.16. Mount overlay support (SVN)
• 3. Overview of Changes
  • 3.1. Removed Features
  • 3.2. Development Changes
  • 3.3. Known issues
  • 3.4. Contributors
  • 3.5. Community patches and libraries
• 4. Legal notes

§ 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:

• dropped 3,211 lines of SDL 1.2 code in place of 1,664 lines, for just under a 50% reduction in code-size.
• eliminated several OS-specific branches and all SDL1-specific kludges.
• eased support for modern graphic APIs, and opened the field for new features and improvements.

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:

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

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 (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:

• onclick - The mouse will be captured with a click inside the window.
• onstart - The mouse is captured immediately on start (similar to real DOS).
• seamless - The mouse will move seamlessly in and out of the window and cannot be captured.
• nomouse - The mouse is disabled and hidden without any input sent to the game.

The second value defines how middle-clicks are handled:

• middlegame - Middle-clicks are sent to the game (not used to uncapture the mouse).
• middlerelease- Middle-click will uncapture the mouse when windowed (not sent to the game).

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

Maniac Mansion (1987), with forced CGA mode

• top-left: CGA, default palette
• top-right: CGA/mono, green tint selected
• bottom-left: CGA Composite, early model, default hue
• bottom-right: CGA Composite, late model, default hue

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

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:\> date
Current date: Fri 05/01/2020
Type ´date MM-DD-YYYY´ to change.

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

Note that while the date can be changed, the time cannot.

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

• dosbox-staging does not run on Operating System/2 (OS/2) or derivatives.
• dosbox-staging does not run on Windows older than XP.
• Removed support for old DirectDraw (ddraw) output.
  Use output = texture, texture_renderer = directx11 instead.
• Removed support for old overlay output. Use any other output.
• Removed support for relative window size (windowresolution = X%).
• Removed support for 64-bit Zip Motion Blocks Video (ZMBV) codec (old 32-bit codec still works).
• Removed support for CD-DA playback from physical disks. It is still possible to install games distributed on CDs by mounting them as directories. See #260.
• Removed CD-DA playback support for tracks using the Audio Interchange File Format AIFF audio codec.

§ Development Changes

• Migrated the DOSBox source from Apache's Subversion (SVN) software versioning and revision control system to the Git distributed version-control system using GitHub, while preserving all publicly available project history.
  • Active SVN branch paths were imported as Git branches (namedsvn/<name>).
  • SVN tag paths were imported as Git lightweight tags (named svn/<tag-name>).
• Ongoing upstream SVN development work is being imported in a timely manner to the Git branch named svn/trunk.
• C++11 language constructs are now allowed.
• Implemented a Continuous Integration (CI) system that builds on every code push to provide immediate feedback to developers regarding build-success and warning-counts on:
  • Windows x86_64 using GCC 32 and 64-bit, Clang 32 and 64-bit, and VisualStudio 64-bit compilers
  • macOS x86_64 using GCC and Clang compilers
  • Linux x86_64, ARMv6, ARMv7, IBM LinuxONE, and IBM POWER8 platforms using various versions of GCC and Clang
• Added static analysis checks performed by LLVM's Clang, Synopsys's Coverity, and VIVA64's Program Verification Systems (PVS) Studio.
• Added dynamic analysis checks performed by Clang's undefined-behavior (UB) sanitizer and GCC's UB and Address sanitizers.
• The CI system includes gated checks that allow maintainers to focus on code functionality and correctness. These automated checks guarantee that new code:
  • builds cleanly on all supported platforms and compilers,
  • adds no new compiler warnings, and
  • adds no new static or dynamic analysis issues.
• Notable progress has been made in reducing the number of warnings and analysis issues flagged by these tools.
• Windows: the build-system was adjusted to allow easy compilation, without manual download or patching of dependencies. We use vcpkg to manage dependencies. The solution file was fixed to work with Visual Studio 2019.
• Linux and macOS: implemented a number of small build-system improvements.
• Automated the compilation of release-style builds against the latest main and feature branches. These not only save time for testers wanting to verify new features and bugfixes, but also ensures they're running builds compiled using would-be release settings.
• macOS: release binaries are compiled with optimizations supporting Intel Nehalem-based instructions (and newer), as this matches the minimum processor requirements set by macOS Catalina.
• Release packages are scanned using up-to-date Antivirus software: ClamAV for Linux and macOS, and Windows Defender for Windows.
• The project has published a Code of Conduct along with clear Contributor Guidelines.

§ Known issues

• Inconsistent minimum window size with windowresolution = resizable when leaving fullscreen.
• Windows, macOS: Window content is not refreshed when resizing.
• Windows, macOS: Emulation stops when moving or resizing window.
• Linux: Wayland crashes (Wayland support is "experimental" at the moment)
• Linux: Splash screen is sometimes transparent or corrupted on KDE

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:

• 11 dosbox-staging contributors submitted 208 pull requests comprised of 780 commits written by 18 authors.
• 69 dosbox-staging issues were reported and addressed.
• 54 dosbox-staging wiki updates were made.
• Three DOSBox (SVN) maintainers committed 76 changes written by 5 authors. These changes have been incorporated into dosbox-staging.

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:

• Add built-in xxHash (v0.7.3) (author: Yann Collet)
• Add built-in Vorbis codec: (v1.17) (author: Sean Barrett)
• Add built-in SDL_sound r599 (LGPL) (author: Ryan C. Gordon)
• Add built-in C++ object serializer (author: Arthur Cuellet)
• Add built-in FLAC codec: dr_flac v0.12.11 (author: David Reid)
• Add built-in MP3 codec: dr_mp3 v0.6.4 (author: David Reid)
• Add built-in WAV codec: dr_wav v0.12.1 (author: David Reid)

Patryk Obara:

• Replace SDL 1.2 with SDL 2.0 (based on work of: NY00123)
• Add Nuked OPL3 emulator v1.8 (author: Alexey Khokholov)

Peter Veenstra:

Changes merged-in to SVN:

• Add OpenGL shader support. (author: ny00123 and refined by jmarsh)
• Add several builtin shaders that mimic the scalers and some extra (author: jmarsh)
• Fix xcmpchg in dyn_x86 core. Allows Quickview to work in that core (author: jmarsh)
• Additional refinements and speed ups (author: jmarsh)
• Fix some issues with commit 4282 (authors: Patryk Obara and jmarsh)
• Switch to a different way to calculate the table offsets (author: jmarsh)
• Fix boundary checks for word/dword memory access. Speeds up dynamic 32 bit core a bit (author: jmarsh)
• Add 64-bit support to dynamic_x86 core from vogons topic 67673 (author: jmarsh)

Michael Zijlstra:

• Add cga_mono machine (author: VileRancour)

§ Legal notes