Documentation update.

CHANGELOG.md

@@ -156,6 +156,7 @@ v1.2 maintenance release.
 * Added support for launching .app directories and alias files to the desktop, epic, kodi, ports and steam systems on macOS
 * Changed the ps3 system to use shortcuts and created an alternative emulator entry for backward compatibility with symlinks
 * Added the .lnk file extension to the epic system on Windows
+* Added support for the Capcom Play System (cps) game system
 * Added support for asterisks/wildcards for emulator name matching, usable both in es_find_rules.xml and es_systems.xml
 * (Linux) Changed to find rule wildcard matching for the AppImages for Dolphin, mGBA, Play!, RPCS3, Xemu and Yuzu
 * Changed the sorting in the Alternative emulators interface to use short system names instead of full system names
@@ -831,6 +832,8 @@ Many bugs have been fixed, and numerous features that were only partially implem
 
 **The issues below are relevant for ES-DE v1.2.4**
 
+* When using Windows on some handheld devices with AMD GPUs, ES-DE will only display a black screen on startup. This can be seen on for instance the Steam Deck, AYA NEO and ONEXPLAYER 8.4. The issue seems to be caused by buggy GPU drivers, and can be worked around by specifying a window size for ES-DE that is a single pixel larger than the actual screen resolution. So for example for a 1280x800 screen, the resolution can be set to 1281x800 and it should then work correctly. This is applied using the --resolution command line option, for instance `EmulationStation.exe --resolution 1281 800`
+
 * On Windows when using high DPI displays, if not running ES-DE on the primary monitor and the display where it runs does not have the same scaling percentage as the primary monitor, then the ES-DE resolution will not be properly set. The application will still work and if running in fullscreen mode it may not even be noticeable. This issue is probably caused by a bug in SDL where the primary display scaling is always used for calculating the display bounds. If using the same scaling percentage across all monitors, or if not using high DPI monitors at all, then this issue is not relevant.
 
 * On Windows installing DS4Windows will break controller input in ES-DE for unknown reasons. Uninstalling this software should resolve the issue. On Windows 11 both DualShock 4 (PS4) and DualSense (PS5) controllers have been tested wired and via Bluetooth and both work fine in both ES-DE and RetroArch without any special drivers or configuration.

CONTRIBUTING.md

@@ -85,7 +85,7 @@ The roadmap is under constant review so expect it to change from time to time. S
 
 * Simple file browsing component
 * Scrollbar component for the gamelist view which can be used by the themes
-* Background music (theme controlled or custom playlist)
+* Background music
 * Proper audio mixer
 * Checksum support for the scraper for exact searches and for determining when to overwrite files
 * Support for portrait orientation, e.g. for Tate Mode arcade cabinets

THEMES-DEV.md

@@ -802,6 +802,7 @@ Properties:
     - `cover` - This will look for a box front cover image.
     - `backcover` - This will look for a box back cover image.
     - `3dbox` - This will look for a 3D box image.
+    - `physicalmedia` - This will look for a physical media image.
     - `fanart` - This will look for a fan art image.
 * `gameselector` - type: STRING
     - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element. This property is only needed for the `system` view and only if the `imageType` property is utilized.
@@ -877,6 +878,7 @@ Properties:
     - `cover` - This will look for a box front cover image.
     - `backcover` - This will look for a box back cover image.
     - `3dbox` - This will look for a 3D box image.
+    - `physicalmedia` - This will look for a physical media image.
     - `fanart` - This will look for a fan art image.
 * `gameselector` - type: STRING
     - If more than one gameselector element has been defined, this property makes it possible to state which one to use. If multiple gameselector elements have been defined and this property is missing then the first entry will be chosen and a warning message will be logged. If only a single gameselector has been defined, this property is ignored. The value of this property must match the `name` attribute value of the gameselector element.
@@ -1421,6 +1423,7 @@ Properties:
     - `cover` - This will look for a box front cover image.
     - `backcover` - This will look for a box back cover image.
     - `3dbox` - This will look for a 3D box image.
+    - `physicalmedia` - This will look for a physical media image.
     - `screenshot` - This will look for a screenshot image.
     - `titlescreen` - This will look for a title screen image.
     - `miximage` - This will look for a miximage.

USERGUIDE-DEV.md

@@ -253,7 +253,14 @@ In general it should be straightforward to run ES-DE on Windows. Almost all emul
 
 Just make sure to not place games or other resources on network shares using the Microsoft SMB protocol as that will lead to unacceptable performance degradations and extremely long startup times if you have a large collection. See the point above on how to setup an NFS share if you insist on placing files or other resources on network drives.
 
-In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start. For really old graphics cards the available drivers may not provide an OpenGL version that is modern enough for ES-DE to work, and in this case a last resort solution would be to install the _Mesa3D for Windows_ library which provides software-based OpenGL rendering. The library can be downloaded from [https://fdossena.com/?p=mesa/index.frag](https://fdossena.com/?p=mesa/index.frag) and you simply extract the opengl32.dll file into the ES-DE installation directory. Just be aware that the performance may be quite bad.
+In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start. For really old graphics cards the available drivers may not provide an OpenGL version that is modern enough for ES-DE to work, and in this case a last resort solution would be to install the _Mesa3D for Windows_ library which provides software-based OpenGL rendering. The 64-bit version of this library can be downloaded from [https://fdossena.com/?p=mesa/index.frag](https://fdossena.com/?p=mesa/index.frag) and you simply extract the opengl32.dll file into the ES-DE installation directory. Just be aware that the performance may be quite bad.
+
+On some handheld devices with AMD GPUs, ES-DE will only display a black screen on startup. This can be seen on for instance the Steam Deck (although not if using SteamOS), AYA NEO and ONEXPLAYER 8.4. The issue seems to be caused by buggy GPU drivers, and can be worked around by specifying a window size for ES-DE that is a single pixel larger than the actual screen resolution. So for example for a 1280x800 screen, the resolution can be set to 1281x800 and it should work correctly. This is applied using the --resolution command line option, for example:
+```
+EmulationStation.exe --resolution 1281 800
+```
+
+Some older games and emulators may not work properly when run via ES-DE unless you set their compatibility mode to an older Windows release. This is done by right clicking on the .exe file or .lnk shortcut for the game or emulator, selecting _Properties_ and then the _Compatibility_ tab, then checking the box named _Run this program in compatibility mode for:_ and finally selecting an appropriate Windows release. Some experimentation with different Windows versions may be required. Don't attempt to change the compatibility mode for ES-DE itself though as that may cause any types of unforeseen issues.
 
 Installing DS4Windows will break controller input in ES-DE for unknown reasons. Uninstalling this software should resolve the issue. On Windows 11 both DualShock 4 (PS4) and DualSense (PS5) controllers have been tested wired and via Bluetooth and both work fine in both ES-DE and RetroArch without any special drivers or configuration.
 
@@ -2487,6 +2494,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
 | channelf              | Fairchild Channel F                            | FreeChaF                          |                                   |              |                                      |
 | coco                  | Tandy Color Computer                           | _Placeholder_                     |                                   |              |                                      |
 | colecovision          | ColecoVision                                   | blueMSX                           | Gearcoleco                        |              |                                      |
+| cps                   | Capcom Play System                             | MAME - Current                    | MAME 2010,<br>MAME 2003-Plus,<br>MAME 2000,<br>MAME **(Standalone)** [UMW*],<br>FinalBurn Neo,<br>FB Alpha 2012,<br>FB Alpha 2012 CPS-1,<br>FB Alpha 2012 CPS-2,<br>FB Alpha 2012 CPS-3 | Depends      | Single archive file following MAME name standard in root folder |
 | daphne                | Daphne Arcade LaserDisc Emulator               | Hypseus [Daphne] **(Standalone)** [UW*] | Hypseus [Singe] **(Standalone)** [UW*] | Yes (Daphne games) | See the specific _Hypseus Singe (Daphne)_ section elsewhere in this guide |
 | desktop               | Desktop Applications                           | N/A                               |                                   | No           | Shortcut in root folder              |
 | doom                  | Doom                                           | PrBoom                            |                                   |              |                                      |

USERGUIDE.md

@@ -244,7 +244,14 @@ In general it should be straightforward to run ES-DE on Windows. Almost all emul
 
 Just make sure to not place games or other resources on network shares using the Microsoft SMB protocol as that will lead to unacceptable performance degradations and extremely long startup times if you have a large collection. See the point above on how to setup an NFS share if you insist on placing files or other resources on network drives.
 
-In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start. For really old graphics cards the available drivers may not provide an OpenGL version that is modern enough for ES-DE to work, and in this case a last resort solution would be to install the _Mesa3D for Windows_ library which provides software-based OpenGL rendering. The library can be downloaded from [https://fdossena.com/?p=mesa/index.frag](https://fdossena.com/?p=mesa/index.frag) and you simply extract the opengl32.dll file into the ES-DE installation directory. Just be aware that the performance may be quite bad.
+In order for ES-DE to run, graphics drivers with OpenGL support have to be installed. If not, the application simply won't start. For really old graphics cards the available drivers may not provide an OpenGL version that is modern enough for ES-DE to work, and in this case a last resort solution would be to install the _Mesa3D for Windows_ library which provides software-based OpenGL rendering. The 64-bit version of this library can be downloaded from [https://fdossena.com/?p=mesa/index.frag](https://fdossena.com/?p=mesa/index.frag) and you simply extract the opengl32.dll file into the ES-DE installation directory. Just be aware that the performance may be quite bad.
+
+On some handheld devices with AMD GPUs, ES-DE will only display a black screen on startup. This can be seen on for instance the Steam Deck (although not if using SteamOS), AYA NEO and ONEXPLAYER 8.4. The issue seems to be caused by buggy GPU drivers, and can be worked around by specifying a window size for ES-DE that is a single pixel larger than the actual screen resolution. So for example for a 1280x800 screen, the resolution can be set to 1281x800 and it should work correctly. This is applied using the --resolution command line option, for example:
+```
+EmulationStation.exe --resolution 1281 800
+```
+
+Some older games and emulators may not work properly when run via ES-DE unless you set their compatibility mode to an older Windows release. This is done by right clicking on the .exe file or .lnk shortcut for the game or emulator, selecting _Properties_ and then the _Compatibility_ tab, then checking the box named _Run this program in compatibility mode for:_ and finally selecting an appropriate Windows release. Some experimentation with different Windows versions may be required. Don't attempt to change the compatibility mode for ES-DE itself though as that may cause any types of unforeseen issues.
 
 Installing DS4Windows will break controller input in ES-DE for unknown reasons. Uninstalling this software should resolve the issue. On Windows 11 both DualShock 4 (PS4) and DualSense (PS5) controllers have been tested wired and via Bluetooth and both work fine in both ES-DE and RetroArch without any special drivers or configuration.