Release Notes for openMSX 20.0 (2024-09-22)
===========================================

This is a major release, in which we introduce the new Graphical User
Interface, replacing the OSD menu. A faster and more powerful debugger is now
included in openMSX itself. Configuration for MSX joystick/JoyMega has been
improved drastically using the new GUI.
As of now, a system with OpenGL 2 support is required to run openMSX.


The GUI
^^^^^^^
We already had two separate GUI applications:
- openMSX Catapult, a tool to control common functionality of openMSX, in a
  limited way.
- openMSX Debugger, a great and helpful tool, but never officially released and
  packaged.
Keeping the GUI separate from the emulation core seemed like a good idea at
first. Keeping the state of both applications in sync turned out to be a hard
problem, however. Functions that seemed easy, were in fact very hard to
implement in this structure.
In this release we integrated the GUI directly in openMSX itself. All
information is now guaranteed in sync and updated real-time (which would have
been very hard in the old structure).
As this is the first release with the new GUI, not everything will be perfect
straight away. Feedback or help to improve things further will be highly
appreciated. The Catapult and openMSX Debugger applications remain available
for the time being. We will (try to) keep them working, but they won't receive
any new development anymore - from us anyway. When keeping them working becomes
too much of a burden, we will abandon these applications altogether.

Joystick emulation
^^^^^^^^^^^^^^^^^^
Another big change is the joystick emulation. There are now fixed joystick and
JoyMega (MegaDrive controller) pluggables (2 for each), which can also be
configured via the GUI and also support keyboard inputs, so they also replace
the old keyjoystick devices. This gives optimal flexibility for configuring how
you want to control MSX controllers.
On top of that, it is now possible to plug and unplug host controllers at
run-time.

Rendering
^^^^^^^^^
Rendering has also undergone a big change. We removed the "SDL" renderer, as
the GUI requires an accelerated backend, for which we use OpenGL 2, which was
already required for the (already default and now only) SDLGL-PP renderer.
We also removed 1x scaling, so the minimum is now 2x. Video recording and
screenshots on the 320x240 resolution are still possible, though. All of this
allowed us to simplify the code a lot, making it easier to add new features and
maintain the code.

Other important changes
^^^^^^^^^^^^^^^^^^^^^^^
As for any custom key bindings you might have: we renamed some keys to match the SDL
library names instead of inventing our own. Old names are still recognized, but
be careful if you also run older openMSX versions, as openMSX will use the new
names and the old openMSX will not recognize them. Examples are: PRINT ->
PrintScreen, META -> GUI.

Special thanks to all the contributors of this release who are not in the core
team! Keep these pull requests coming!

Here's the list with all highlights and details:

MSX device support:
- OPL4: fixed detail in YMF262 register mirroring
- turboR PCM:
  - fixed sample frequency to 15700Hz (not 15750Hz as found in some
    documentation)
  - implement sample buffer (bit 0 on port 0xA5) to improve sound quality
- flash ROMs: added a lot of accuracy to its emulation
- WD2793 and TC8566AF FDC's: fixed several details
- Konami mapper: added missing mirroring
- improvements on I8254 mode 3 used in some RS-232C interfaces
- added support for the concept 16-bit NEO mappers, which may be used by
  someone in the future. If this doesn't happen, support will be dropped again
- added support for the ASCII16-X mapper which will be used by some upcoming
  games
- fixed mapper of Mitsubishi ML-TS2 modem software
- added support for Circuit Designer RD dongle (thanks Sandy Pleyte!)
- added new machines/extensions, thanks to:
  - Peter Hanraets and Arjen Zeilemaker: Hitachi MPF-310H
  - Peter Hanraets: Hitachi MB-H70
  - bsittler: USA version of Yamaha CX5M
  - Takamichi Suzukawa: National CF-SM003
  - Tristan Zondag: German Spectravideo SVI-738
  - Oliver Klink: French Canon V-20
  - Patrick: Yeno DPC-64
  - DamnedAngel: Hitachi MB-H21
  - Peter Hanraets, Takamichi Suzukawa, Arjen Zeilemaker and Benoit Delvaux:
    Sony HB-T600
  - Others: Philips VU-0040, General Paxon PCT-55, Sanyo MPC-64, OPL3 Cartridge
    with Moonsound compatible port mapping

New or improved emulator features:
- removed SDL renderer
- added new GUI:
  - main menu bar with these menu items:
    - Machine
      - Select MSX machine
      - Firmware switch
      - Pause emulator
      - Reset MSX
      - Power on/off
      - Test MSX hardware (much faster than in Catapult)
    - Media
      - Cartridge slots with ROM cartridges or extensions
      - Disk drives
      - Tape deck
      - Hard disk
      - CD-ROM
      - Laserdisc
    - Connectors
      - joystick ports, printer ports, MIDI ports, etc.
    - Save state
      - Load/Save state
      - Load/Save replay
      - Reverse/replay settings
    - Tools
      - Virtual keyboard
      - Copy/paste
      - Capture audio/video/screenshot
      - Disk Manipulator
      - Trainer
      - Cheat Finder
      - SCC viewer
      - Audio channel viewer
      - OSD Toys
    - Settings
      - Video
      - Sound
      - Speed
      - Input
        - Configure MSX joysticks
      - GUI
        - Configure GUI shortcuts
      - Misc
        - Configure OSD icons, show status bar, ...
    - Debugger
      - Toolbar
      - Disassembly view
      - CPU registers
      - CPU flags
      - Slots
      - Stack
      - Breakpoints
      - Symbol Manager
      - Watch expressions
      - Bitmap viewer
      - Tile viewer
      - Sprite viewer
      - VDP register viewer
      - Palette
      - Hex editor
    - Help
      - Links to manuals
      - About
  - Reverse bar
  - OSD icons
  - Status bar
  - Console
  - Messages
  - Drag and drop
  - Shortcuts
  - Separate pop-out windows
  - Windows can be docked on other windows or in a tab widget
  - 3 styles: Dark (default), Light, Classic
  - configurable font and font size. Default: DejaVu
- OSD menu:
  - removed in favour of new GUI
- only warn once for unsupported size in Konami mappers
- suppress warning messages during reversing
- fully configurable MSX controller mapping for joysticks (msxjoystick1/2
  pluggables) and JoyMega devices (joymega1/2 pluggables) - see above
- low level debugger (scripting):
  - added support for symbol management
- allow to set a breakpoint (or any Tcl callback) when the VDP dot clock
  direction is written "wrongly"
- added VGM recording for OPL3
- added minimal support for unplugging and replugging host controllers
- added support for RS232Net: connect MSX RS-232C interfaces to the local
  network
- removed several OSD scripts which have been replaced by the GUI, sometimes
  almost 1 to 1:
  - reverse bar
  - tile viewer
  - sprite viewer
  - palette editor
  - VDP register viewer
  - tabbed machine view
  - display_message
  - quit menu
  - OSD keyboard
  - load_icons
- removed support for savestates with .xml.gz extension
- do not save SRAM to file if unmodified
- added support to run openMSX fully in headless mode
- allow to specify the device name of IDE devices in their config XML file
- base the Boosted MSX2 EN on the Philips NMS 8245 instead of 8250
- fixed crash when multiple debug-devices were used at once
- fixed possible crash on specific combination of watchpoints and replay
- fixed possible crash on no longer supported savestates:
  - we try to keep old savestates working. Nevertheless occasionally we do
    remove stuff. Loading an old savestate which contains such stuff used to
    crash, now we give a clean error message.
- fixes for load_settings command

Build system, packaging, documentation:
- added support for loongarch
- required GNU compiler is now at least g++-11
- required clang compiler is at least clang++-16
- required Visual Studio Compiler is at least 2022
- on macOS, at least Xcode 15.4 is required
- Android build is totally broken, and will require a lot of effort and help to
  get back up, which is not planned by us.
- 3rd party updates of SDL (2.30.1), SDL2_ttf (2.22.0), GLEW (2.2.0)
- added patch to add aarch64 support to libtheora 3rdparty build
- fixed link error in libvorbis for Xcode 15 on macOS
- avoid pkg-config build error with Clang 15 on macOS
- quite a large update of the manual (mostly to include the new GUI)

...and of course the usual various bug fixes and performance improvements.

In "doc/manual/index.html" you can find a set of HTML manuals for openMSX.
Make sure you read this if you haven't used openMSX before, but also to learn
more about the new and changed features.

CPU and graphics performance varies a lot, depending on the openMSX settings
and the MSX hardware and software you're emulating. Some things run fine on a
200 MHz machine, others are slow on a 2 GHz machine. For performance tuning
tips, see the Setup Guide.

openMSX is confirmed to run on the following operating systems: Linux, Windows,
macOS, FreeBSD, OpenBSD and NetBSD; on x86, x86-64, PPC, ARM, MIPS and Sparc
CPUs. Running on other operating systems (wherever SDL and OpenGL 2 runs) or
CPUs should be possible, but may require some modifications to the build
system. If you are compiling on a new platform, please share your experiences
(see below for contact info), so we can make openMSX more portable.

openMSX Home Page:
  https://openmsx.org/
Project page on GitHub:
  https://github.com/openMSX
Contact options:
- Talk to us on #openmsx on libera.chat.
- Use the forum on https://www.msx.org/forum/semi-msx-talk/openmsx
- File a ticket on https://github.com/openMSX/openMSX/issues

Thanks to all contributors for their feedback, support, bug reports, testing,
coding and other help!

Have fun with your emulated MSX!
                                        the openMSX developers
