dosbox-x

NOTICE: Use the 32-bit toolchain from the main MinGW project, not the MinGW64 project.
Binaries compiled with MinGW64 have extra dependencies not provided by the HX DOS extender.

Visual Studio 2017 compile for 32/64-bit Windows Vista or higher
Use the ./vs2015/dosbox-x.sln "solution" file and compile.
You will need the DirectX 2010 SDK for Direct3D9 support.
See the README.Windows for extra information about this platform.

As of 2018/06/06, VS2017 builds (32-bit and 64-bit) explicitly require
a processor that supports the SSE instruction set.

XCode (on Mac OS X, from the Terminal) to target Mac OS X
./build-debug

Open source development
-----------------------

Ideas and patches are always welcome, though not necessarily accepted.

If you really need that feature or change, and your changes are not
accepted into this main project (or you just want to mess around with
the code), feel free to fork this project and make your changes in
your fork.

As joncampbell123 only has limited time to work on DOSBox-X, help is
greatly appreciated:

- Testing
- Features
- Hardware accuracy
- Software accuracy
- Games, applications, demoscene executables
- Windows 1.x through Millenium guest OS support
- Retro development
- Bug fixes, patches, improvements, refinements
- Suggestions, ideas, general conversation
- Platform support (primarily Linux and Windows, but others are welcome)
- Documentation
- Notes regarding games, applications, hacks, weird MS-DOS tricks, etc.

If you want to tweak or write some code and you don't know what to work
on, feel free to visit the issue tracker to get some ideas.

Warnings regarding C integer types
----------------------------------

Contrary to initial assumptions, never assume that int and long have specific
sizes. Even long long.

The general assumption is that int is 32 bit and long is 32 bit.
That is not always true, and that can get you in trouble when
working on this or other projects.

Another common problem is the use of integers for pointer manipulation.
Storing pointers or computing differences between pointers may happen
to work on 32-bit, where ints and pointers are the same size, but the
same code may break on 64-bit.

Therefore, for manipulating pointers, use uintptr_t instead of int or
long.

For quick reference, here is a breakdown of the development
targets and their sizes:

Windows (Microsoft C++) 32-bit:
sizeof(int) == 32-bit
sizeof(long) == 32-bit
sizeof(long long) == 64-bit
sizeof(uintptr_t) == 32-bit

Windows (Microsoft C++) 64-bit:
sizeof(int) == 32-bit
sizeof(long) == 32-bit
sizeof(long long) == 64-bit
sizeof(uintptr_t) == 64-bit

NOTE: If you ever intend to compile against older versions of Microsoft C++/Visual Studio,
the "long long" type will need to be replaced by __int64.

Linux 32-bit:
sizeof(int) == 32-bit
sizeof(long) == 32-bit
sizeof(long long) == 64-bit
sizeof(uintptr_t) == 32-bit

Linux 64-bit:
sizeof(int) == 32-bit
sizeof(long) == 64-bit
sizeof(long long) == 64-bit
sizeof(uintptr_t) == 64-bit

This code is written to assume that sizeof(int) >= 32-bit.
However know that there are platforms where sizeof(int) is
even smaller. In real-mode MS-DOS and 16-bit Windows for
example, sizeof(int) == 16 bits (2 bytes). DOSBox-X will
not target 16-bit DOS and Windows, so this is not a problem
so far.

For obvious reasons, far pointers are not supported. The
memory map of the runtime environment is assumed to be
flat with possible virtual memory and paging.

When working on this code, please understand the limits of
the integer type in the code you are writing to avoid
problems. Pick a data type that is large enough for the
expected range of input.

It is suggested to use C header constants if possible
for min and max integer values, like UINT_MAX.

If the code needs to operate with specific widths of
integer, please use data types like uint16_t, uint32_t,
int16_t and int32_t provided by modern C libraries, and
do not assume the width of int and long.

If compiling with older versions of Visual Studio, you will
need to include a header file to provide the uintptr_t and
uint32_t datatypes to fill in what is lacking in the C library.

When multiplying integers, overflow cases can be avoided
with a * b by rejecting the operation if b > (UINT_MAX / a)
or by multiplying a * b with a and b typecast to the next
largest datatype.

Remember that signed and unsigned integers have the same
width but the MSB changes the interpretation. This code
is written for processors (such as x86) where signed integers
are 2's complement. It will not work correctly with any
other type of signed integer.

2's complement means that the MSB bit of an integer indicates
the number is negative. When it is negative, the value could
be thought of as N - (2^sizeof_in_bits(int)). For a 16-bit
signed integer:

2^16 = 0x10000 = 65536

hex int unsigned int equiv
0x7FFE 32766 32766 32766 - 0
0x7FFF 32767 32767 32767 - 0
0x8000 -32768 32768 32768 - 65536
0x8001 -32767 32769 32769 - 65536
...
0xFFFE -2 65534 65534 - 65536
0xFFFF -1 65535 65535 - 65536
(carry, overflow all 16-bits, roll back to 0)
0x0000 0 0 0 - 0
0x0001 1 1 1 - 0

Another possible problem may lie in using negation (-) or
inverting all bits (~) of an integer for masking. The
result may be treated by the compiler as an integer. Make
sure to typecast it to clarify.

Another possible incompatiblity lies with printf() and
long long integers.

Always typecast the printf() parameters to the data type
intended to avoid problems and warnings.

While Mac OS X and Linux have runtimes that can take %llu
or %llx, Microsoft's runtime in Windows cannot. Either
avoid printing long long integers or add conditional code
to use %llx or %llx on Linux and %I64u or %I64d on Windows.

Note that MinGW compilation on Windows suffers from the
same limitation due to use of Microsoft C runtime.

When dealing with sizes, including file I/O and byte counts,
use size_t (unsigned value) and ssize_t (signed value) instead.
This will help with using the C++ standard template library
and the C file I/O library. If compiling for a target where
read and write use int for a return value instead, then
use typecasting.

When handling file offsets, use off_t instead of long.
Modern C runtime versions of lseek and tell will use that
datatype. For older runtimes that use "long", make a typecast
in a header file for your target to declare off_t. Remember
that off_t is a signed value and that it can be negative.

Make sure to use the 64-bit version of lseek (often named
lseek64 or _lseeki64) in order to support files 4GB or
larger if allowed by the runtime environment.

Remember that lseek() can return -1 to indicate an error.
lseek() however will permit seeking past the end of a file.

writing at that point will extend the file to allow the
file write to occur at that offset. Depending on the platform,
that will either cause a sparse file (Linux + ext) or will
cause a loop within the filesystem driver to extend the file
and zero clusters to make it happen (Windows XP through 10).

Use of the FILE* file I/O layer is OK, but not recommended
unless there is a need to use text parsing with functions
like fgets() or fprintf(). For other uses, please use C
functions open, close, read, write, lseek and learn to use
file handles.

Understand that when fgets() returns with the buffer filled
with the line of text, the end of the string will always include
the newline (\n) that fgets() stopped reading at.

If fopen() was called with the "b" flag on DOS and Windows
formatted text files, the end of the string will probably
contain \r\n (CR LF). On platforms other than DOS and Windows,
\r\n will always appear if it is in the file.

C file handles are signed integers. They can be negative.
File handles returned by the C runtime however are never
negative except to indicate an error.

A good way to track whether an int holds an open file therefore,
is to initialize at startup that integer to -1, and then when
open succeeds, assign that value the file handle. When closing
the file, assign -1 to the integer to record that the handle was
closed.

Other parts of the code can also check if the file handle is
non-negative before operating on the file as a safety measure
against calling that function when the file was never opened.

On Windows, the HANDLE value at the Win32 API level can be obtained
from an integer file handle using _get_osfhandle() for use with
the Win32 API functions directly.

When using open(), make sure to use O_BINARY to avoid
CR/LF translation on DOS and Windows systems. Make sure
there is a header that defines O_BINARY as (0) if the
platform does not provide O_BINARY to avoid #ifdef's
around each open() call.

When using arithmetic with C pointers and integers,
understand that the pointer is adjusted by the value of the
integer times the size of the pointer type. If you intend
to adjust by bytes, then typecast the pointer to char* or
unsigned char* first, or typecast to uintptr_t to operate
on the pointer value as if an integer, then add the integer
value to the pointer.

At the lowest level, a pointer could be thought of as an
integer that is interepreted by the CPU as a memory address
to operate on, rather than an integer value directly.

Therefore, when adding an integer to a pointer value, the
result could be thought of as:

(new pointer value in bytes) = (current pointer value in bytes) + integer value * sizeof(pointer data type)

If the pointer is char, then adding 4 will advance by 4 bytes.
If the pointer is int, then adding 4 will advance by 4 * sizeof(int) bytes, or, 4 memory locations of type int.

Keep this in mind when manipulating pointers while working
on this code.

Software security comments
--------------------------

DOSBox-X cannot claim to be a "secure" application. It contains a lot of
code designed for performance, not security. There may be vulnerabilities,
bugs, and flaws in the emulation that could permit malicious DOS executables
within to cause problems or exploit bugs in the emulator to cause harm.
There is no guarantee of complete containment by DOSBox-X of the guest
operating system or application.

If security is a priority, then:

Do not use DOSBox-X on a secure system.

Do not run DOSBox-X as root or Administrator.

If you need to use DOSBox-X, run it under a lesser privileged user, or in
a chroot jail or sandbox.

If your Linux distribution has it enabled, consider using the auditing
system to limit what the DOSBox-X executable is allowed to do.

Comments on DOSBox-X development
--------------------------------

The four major operating systems and platforms of DOSBox-X are (in this order):

1. Linux (with X11) 32-bit and 64-bit x86.

2. Windows 10 (followed by Windows 8, and Windows 7) for 32-bit and 64-bit x86.

3. Linux (with X11) on a Raspberry Pi 3 (arm 7).

4. Mac OS X Sierra 10.12 or higher 64-bit.

Linux and MinGW Windows builds are expected to compile with the GNU autotools.

A preliminary CMake build system is available, see README.cmake.md for details.

Stright Windows builds are expected to compile using the free community edition
of Visual Studio 2015 or Visual Studio 2017 and the DirectX 2010 SDK.

Mac OS X builds are expected to compile on the terminal using GNU autotools
and the LLVM/Clang compiler provided by XCode.

In all cases, the code requires a C++ compiler that can support the C++11
standard.

Note that DOSBox-X is written to compile against the in-tree copy of the
SDL 1.x (Simple Directmedia Libary), or against the SDL 2.x library provided
by your Linux distribution.

For Visual Studio and MinGW compilation, the in-tree copy of SDL is always
used.

The in-tree SDL 1.x library has been HEAVILY MODIFIED from the original
SDL 1.x source code and is somewhat incompatible with the stock library.

The modifications provide additional functions needed to improve DOSBox-X
and fix many issues with keyboard input, window mangement, and display
management that previously required terrible kludges within the DOSBox
and DOSBox-X source code.

In Windows, the modifications also permit the emulation to run independent
of the main window so that moving, resizing, or using menus does not cause
emulation to pause.

In Mac OS X, the modifications provide an interface to allow DOSBox-X to
replace and manage the OS X menu bar.

Comments on what DOSBox-X is lacking
------------------------------------

DOSBox-X aims for accuracy in emulation however there are some things the
design as implemented now cannot accomodate.

* Cycle-accurate timing of x86 instructions and execution.

Instructions generally run one per cycle in DOSBox-X, except for I/O
and memory access.

If accurate emulation of cycles per instruction is needed, please
consider using PCem or PCem-X instead.

* Full precision floating point emulation.

Unless using the dynamic core, DOSBox and DOSBox-X emulate the FPU
registers using the "double" 64-bit floating point data type.

The Intel FPU registers are 80-bit "extended precision" floating
point values, not 64-bit double precision, so this is effectively
12 bits of precision loss and 5 bits of range loss (64 to 53 mantissa
bits and 16 to 11 exponent bits).

This slight loss of precision is perfectly fine considering DOSBox's
original goal in supporting DOS games, but may cause problems in
other cases that need the full precision.

It is known at this time that this lack of precision is enough to
cause otherwise straightforward comparisons against integers to
fail in DOS applications originally written in QBasic or Turbo Basic.
There are such DOS games written that check their file size using
a floating point compare that will fail in this manner. To run these
games, you will need to disable FPU emulation (fpu=false) to force
the QBasic/TurboBasic runtime to use software emulation instead.

* Pentium II or higher CPU level emulation.

DOSBox-X contains code only to emulate the 8088 through the Pentium Pro.

If Pentium II or higher emulation is desired, consider using Bochs
or QEMU instead. DOSBox-X may eventually develop Pentium II emulation,
if wanted by the DOSBox-X community in general.

* Emulation of PC hardware 2001 or later.

The official cutoff for DOSBox-X is 2001, when updated "PC 2001"
specifications from Microsoft mandated the removal of the ISA slots
from motherboards.

The focus is on implementing hardware emulation for hardware made
before that point.

Contributers are free to focus on emulating hardware within the
1980-2001 timeframe of their choice.

* Windows guest emulation, Windows XP or later.

DOSBox-X emulation, in terms of running Windows in DOSBox-X, will
focus primarily on Windows 1.0 through Windows Millenium Edition,
and then on Windows NT through Windows 2000. Windows XP and later
versions are not a priority and will not be considered at this time.

If you need to run Windows XP and later, please consider using
QEMU, Bochs, or VirtualBox.

* Any MS-DOS system other than IBM PC/XT/AT, Tandy, PCjr, and NEC PC-98.

Only the above listed systems will be considered for development
in DOSBox-X. This restriction prevents stretching of the codebase
to an unmanageable level and helps keep the code base organized.

However, if adding emulation of the system requires only small
minimal changes, then the new system in question may be considered.

You are strongly encouraged to fork this project and implement
your own variation if you need to develop MS-DOS emulation for
any other system or console. In doing that, you gain the complete
freedom to focus on implementing the particular MS-DOS based
system of interest, and if desired, the ability to strip away
conflicting IBM PC/XT/AT emulation and unnecessary code to keep
your branch's code manageable and maintainable.

It would be easier on myself and the open source community if
developers could focus on emulating their platform of interest in
parallel instead of putting everything into one project that,
most likely, will do a worse job overall emulating all platforms.

If you are starting a fork, feel free to let me know where your
fork is and what system it is emulating, so I can list it in
this README file for others seeking emulation of that system.

To help, I have added machine and video mode enumerations as
"stubs" to provide a starting point for your branch's implementation
of the platform.

Stubs implemented so far:
- FM Towns emulation (machine=fm_towns)

Origins, and crediting of source code
-------------------------------------

by Jonathan Campbell.

As the developer of DOSBox-X, I cannot legitimately claim to have
written all of the code in this project.

DOSBox-X started as a fork of the main DOSBox project sometime
mid 2011. It was started out of a desire to improve the emulator
without having to fight with or worry about submitting patches
upstream.

As the forums make it clear, DOSBox's main focus is on DOS games.
This is evident by the fact that much of the code is somewhat
accurate code with kludges to make DOS games run, instead of
focusing on what hardware actually does.

Many of the changes I wanted to make were non-game related, and
therefore were unlikely to be accepted by the developers.

Since then, I have been modifying the source code over time to
improve emulation, fix bugs, and resolve incompatibilities with
Windows 95 through ME. I have added options so that DOSBox-X
by default can emulate a wider variety of configurations more
accurately, while allowing the user to enable hacks if needed
to run their favorite DOS game. I have also been cleaning up
and organizing the code to improve stability and portability
where possible.

It's more accurate to say then, that I wrote *some* of the code,
that I rewrote other parts of the code, and the rest is the DOSBox
SVN code as it existed since mid 2011.

The purpose of this section, is to try and build a comprehensive
list of source code in this repository that was borrowed from
other projects.

Some of the code is DOSBox SVN code in which some of the SVN
commits made since 2011 were incorporated into DOSBox-X.

The main DOSBox project was not written by one programmer. It has
been under development since late 2000 with patches, fixes, and
improvements from members all over the Vogons forums. Despite
not having an official release since DOSBox 0.74 over 10 years
ago, the project is still in active development today. Some of
the changes themselves incorporated code from other projects,
which are also credited in the list below.

Some of the code in this source tree also came from another
branch of DOSBox known as DOSBox Daum (http://ykhwong.x-y.net)
which itself incorporated code from the main DOSBox project,
DOSBox-X, and many experimental patches. Although the Daum
branch seems to be dead, the code borrowed from it still
exists in DOSBox-X.

This is my attempt to properly credit the code and it's
sources below. Feel free to revise and correct this list
if there are errors.

NE2000 network card emulation (Bochs)
src/hardware/ne2000.cpp

MT32 synthesizer (MUNT)
src/mt32/*.cpp
src/mt32/*.h

AVI writer with OpenDML support (written by myself)
src/aviwriter/*.cpp
src/aviwriter/*.h

Framework-agnostic GUI toolkit (Jorg Walter)
src/libs/gui_tk/*.cpp
src/libs/gui_tk/*.h

Porttalk library, to read/write I/O ports directly (Unknown source)
src/libs/porttalk/*.cpp
src/libs/porttalk/*.h

FreeDOS utilities as binary blobs (FreeDOS)
src/builtin/*.cpp

NukedOPL OPL3 emulation (Alexey Khokholov)
src/hardware/nukedopl.cpp

OPL emulation based on Ken Silverman OPL2 emulation
src/hardware/opl.cpp

MOS6581 SID emulation
src/hardware/reSID/*.cpp
src/hardware/reSID/*.h

SN76496 emulation (MAME project)
src/hardware/sn76496.h
src/hardware/tandy_sound.cpp

PC-98 video rendering and I/O handling code (written by myself)
src/hardware/vga_pc98*.cpp

3dfx Voodoo Graphics SST-1/2 emulation (Aaron Giles)
src/hardware/voodoo_emu.cpp

PC-98 FM board emulation (Neko Project II)
src/hardware/snd_pc98/*

QCOW image support (Michael Greger)
src/ints/qcow2_disk.cpp

HQ2X and HQ3X render scaler (ScummVM, Maxim Stepin)
src/gui/render_templates_hq2x.h

Tips for hacking and modifying the source code
----------------------------------------------

As a SDL (Simple Directmedia Layer) based application,
DOSBox-X starts execution from main(), which is either
the real main() function or a redefined main() function
called from SDLmain depending on the platform.

On Linux and Mac OS X, main() is the real main function.

On Windows, main() is SDLmain() and is called from the
WinMain function defined in the SDL library.

The entry point main() is in src/gui/sdlmain.cpp,
somewhere closer to the bottom.

Configuration and control state (from dosbox.conf and
the command line) are accessible through a globally
scoped pointer named "control".

In the original DOSBox SVN project, "control" is
most often used for accessing the sections and
settings of dosbox.conf.

In DOSBox-X, "control" also holds flags and variables
gathered from the command line (such as -conf).

Most (though not all) of the sections and settings
are defined in src/dosbox.cpp. There is one function
DOSBox_SetupConfigSections() that adds sections and
settings.

Each section has a list of settings by name. Each
setting can be defined as an int, hexadecimal,
string, double, and multivalue item. Read
include/setup.h and src/misc/setup.cpp for more
information.

There is one section (the autoexec section) that
is defined as lines of text.

In the original DOSBox SVN project, each section
also has an init and destructor function. The
codebase in SVN is heavily written around emulator
setup from each section, which is why the order
of the sections is important. DOSBox-X eliminated
these init and destructor functions and encourages
initial setup from functions called in main(),
and additional setup/teardown through VM event
callbacks (see include/setup.h). A callback
mechanism is provided however (at a section level)
when settings change.

Most of the code in this codebase assumes that
it can retrieve a section by name, and a setting
by name, without checking whether the returned
referce to a setting is NULL. Therefore, removing
a setting or referring to settings before the
creation of them can cause this code to crash
until that reference is removed.

How DOSBox and DOSBox-X mix x86 and native code
-----------------------------------------------

Much of the DOS and BIOS handling in DOSBox and DOSBox-X
is done through the use of the "callback" instruction
and a callback system in src/cpu/callback.cpp.

Each BIOS interrupt is a callback, as is the DOS kernel
interrupts. INT 21h is handled as a callback to src/dos/dos.cpp
function DOS21_Handler(), for example. That native code
function can then manipulate CPU registers and memory as
needed to emulate the DOS call.

Some callback functions will also modify the stack frame
to set or clear specific CPU flags on return, using
functions CALLBACK_SCF(), CALLBACK_SZF(), and CALLBACK_SIF().

The callback instruction is 0xFE 0x38 <uint16_t>. This
is an invalid opcode on actual x86 hardware, but it is
a call into a callback function within the DOSBox
emulation. The uint16_t value specifies which callback.

Callbacks are registered through CALLBACK_Allocate(),
which then returns an integer value that is an index into
the callback table. 0 is an invalid callback value that
indicates no callback was allocated, though at this time,
CALLBACK_Allocate() is written to E_Exit() and abort
emulation in the case that none are available, instead
of returning zero.

CALLBACK_DeAllocate() can be used with the index to
free that slot so that other code can use CALLBACK_Allocate()
to take that slot if needed, though it is rare to use
CALLBACK_DeAllocate() so far.

When allocated, the emulation code can then write x86
instructions where needed that include the callback
instruction in order to work from native code at that
point in execution. Generally, most of the x86 code
generation is done within the callback framework itself
using CALLBACK_SetupExtra to write common patterns of
x86 code depending on how the native code is meant to
execute or return to the caller.

When the CPU core encounters a callback instruction,
the index of the instruction (nonzero, remember) is
returned from the execution loop with the expectation
the caller will then index the callback array with it.

If the callback instruction is called from protected
mode, memory and I/O access may cause recursion of
the emulator. Memory access functions called by the
native code may trigger an I/O port or page fault
exception within the guest. DOSBox and DOSBox-X
resolve the fault by pushing an exception frame
onto the stack and then recursing into another
emulation loop which does not break until the fault
is resolved. While this is perfectly fine for
DOS and Windows 3.1 simple fault handling, this
may cause recursion issues with more advanced
task switching and fault handling in Windows 95
and later.

The most common reason a callback handler might
get caught with a page fault is the emulation
of DOS and BIOS interrupts while running within
the virtualization environment of Windows 3.0
through Windows ME.

Another possible source of page faults may occur
with DOS extenders that enable paging of memory
to disk.

Callback functions will typically return CBRET_NONE.

General description of source code
----------------------------------

src/shell/shell.cpp SHELL init, SHELL run, fake COMMAND.COM setup,
startup messages and ANSI art, AUTOEXEC.BAT
emulation and setup, shell interface,
input, parsing, and execution

src/shell/shell_batch.cpp Batch file (*.BAT) handling

src/shell/shell_cmds.cpp Shell internal command handling, shell commands:
DIR CHDIR ATTRIB CALL CD CHOICE
CLS COPY DATE DEL DELETE ERASE
ECHO EXIT GOTO HELP IF LOADHIGH
LH MKDIR MD PATH PAUSE RMDIR
RD REM RENAME REN SET SHIFT
SUBST TIME TYPE VER ADDKEY VOL
PROMPT LABEL MORE FOR INT2FDBG
CTTY DEBUGBOX

src/shell/shell_misc.cpp PROMPT generator, command line input interface,
shell execution, and command location via PATH
interface.

src/gui/sdlmain.cpp Entry point, emulator setup, runtime execution,
cleanup. Menu management, GFX start/end handling,
GFX mode setup and management. Menu handling.
Logging of GFX state. A lot of other misc code.

src/gui/sdlmain_linux.cpp Linux-specific state tracking and handling.

src/gui/sdl_mapper.cpp Mapper interface, mapper event handling and routing,
mapper file reading and writing. Keyboard, mouse,
joystick, and shortcut handling. In DOSBox-X,
also ties mapper shortcuts to the menu system.

src/gui/sdl_gui.cpp Configuration GUI (using gui_tk), dialog boxes,
background "golden blur" behind dialog boxes,
input management and display of dialog boxes.

src/gui/menu.cpp Menu handling and management, processing,
application of menu to host OS menu framework
if applicable. In DOSBox-X, contains the menu
C++ class and menu item object system which then
maps to Windows HMENU, Mac OS X NSMenu, or the
custom drawn SDL menus if neither are available.

Which menu framework is used depends on the
assignment of the DOSBOXMENU_* constant as defined
in include/menu.h. By default:

Windows (HMENU) is used if targeting Windows
and not HX DOS and not SDL2

Mac OS X (NSMENU) is used if targeting Apple
Mac OS X and not SDL2

SDL drawn menus are used in all other cases.

A define is available via configure.ac if
SDL drawn menus should be used regardless of
the host OS and environment.

A NULL menu define is provided if a build
with no visible menus is desired.

src/gui/render.cpp RENDER_ and render scaler code. Also handles
color palette, aspect ratio, autofit options.
The selection of render scaler is defined and
chosen here.

src/gui/render_scalers.cpp Render scaler definitions and code. Note that
scalers are defined using header files and
templates and #defines to support each color
format.

src/gui/midi.cpp MIDI output framework. Header files include
additional platform-specific code.

src/gui/menu_osx.mm Mac OS X Objective C++ code to bridge Objective C
and C++ so that the menu manipulation code can
work correctly.

src/gui/direct3d.cpp Windows Direct3D9 support code. This code allows
output=direct3d to work properly. Uses DirectX 9
interfaces.

include/bitop.h Header file to provide compile-time and runtime
inline functions for bit manipulation and masking.
Additional code is in src/gui/bitop.cpp

include/ptrop.h Header file to provide compile-time and runtime
inline functions for pointer manipulation and
alignment. Additional code is in src/gui/ptrop.cpp.

src/aviwriter/* AVI writer library, written by Jonathan Campbell
sometime around 2010, and incorporated into DOSBox-X.
Unlike the initial code from DOSBox SVN, this code
can support writing OpenDML AVI files that exceed
the 2GB file size limit.

All definitions, including Windows PCM formats and
GUIDs, are provided here.

src/misc/cross.cpp Cross-platform utility functions.

src/misc/messages.cpp Message translation table functions.

src/misc/setup.cpp Configuration, section, and setting management.

src/misc/shiftjis.cpp Shift-JIS utility functions.

src/misc/support.cpp String support functions including case conversion.

DOSBox-X menu framework
-----------------------

Instead of using a specific menu system directly, DOSBox-X uses a menu
framework as defined in include/menu.h and src/gui/menu.cpp.

This menu framework allows using the same menu item and menu layout
on all supported targets.

Prior to the framework, DOSBox-X menus were exclusively for Windows only
and defined in an *.rc file.

The design of the system is that all components of the emulator define
and register their menu items during init by a specific name. Mapper
shortcuts automatically register a menu item named "mapper_" + mapper
shortcut name.

Popup menus are also menu items by name, controlled by src/gui/menu.cpp.

The final layout is controlled by src/gui/menu.cpp which refers to
menu items by name and the order that they are arranged in.

The final layout can be seen through the display list in the menu object
and the display list in each menu item that was created as a submenu.
The display list contains the exact order that menu items are arranged.

In the SDL drawn menus, each menu item also contains the screen and
relative coordinates that were decided on when the menu object was last
called to rebuild or arrange the menus.

The SDL drawn menus are the only type that requires the main DOSBox-X
event loop to process menu events on their behalf including drawing
and reacting to mouse/touchscreen input. Windows and Mac OS X menus do
not require the main event loop's attention except when the user selects
an item.

Access to the menu items is by name, as well. get_item() returns a menu
item by reference, which itself contains methods to control the state
of the menu item and to reflect the changes to the menu framework.

Menu item methods return a reference to themselves to permit chaining
the calls on one line to keep visual clutter to a minimum.

The menu framework will call E_Exit() if the menu item by name does
not exist. Another method exists in the menu object to test if an
item exists by name.

It is expected that references returned from get_item() are used
short-term and never held onto for longer than needed. References
point directly to a vector within the menu object that can become
invalid if anything is done to cause the vector to resize. Always
call get_item() for a menu item to operate on it, never cache or
store the return value. Never add items while holding a reference.

Languages

C 49.8%

C++ 36.4%

HTML 5.9%

Shell 2.1%

Assembly 1.5%

Other 3.9%