0.75.0 Release Notes
2020-05-06Installation 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
- 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 imgmount
ed
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.
Useoutput = 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 (named
svn/<name>
). - SVN tag paths were imported as Git lightweight tags (named
svn/<tag-name>
).
- Active SVN branch paths were imported as Git branches (named
- 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
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.