Documentation update.

CHANGELOG.md

@@ -102,6 +102,7 @@ Apart from all the above, a huge amount of work has gone into fixing bugs, refac
 * Fixed a lot of compiler warnings introduced by the -Wall and -Wpedantic flags
 * Changed the language standard from C++14 to C++17
 * Increased the minimal required compiler version to 5.0.0 for Clang/LLVM and 7.1 for GCC
+* Added a CMake option to build with AddressSanitizer
 * Changed two clang-format rules related to braced lists and reformatted the codebase
 * Bundled the October 2021 release of the Mozilla TLS/SSL certificates
 * Updated the MAME index files to include ROMs up to MAME version 0.237

INSTALL-DEV.md

@@ -187,6 +187,14 @@ cmake -DCMAKE_BUILD_TYPE=Profiling .
 make
 ```
 
+To enable AddressSanitizer which helps with identifying memory issues like corruption bugs and buffer overflows, build with the ASAN option:
+```
+cmake -DCMAKE_BUILD_TYPE=Debug -DASAN=on .
+make
+```
+
+This tool isn't very useful without debug symbols so only include it for a Debug or Profiling build. Both Clang and GCC support this tool.
+
 As for more advanced debugging, Valgrind is a very powerful and useful tool which can analyze many aspects of the application. Be aware that some of the Valgrind tools should be run with an optimized build, and some with optimizations turned off. Refer to the Valgrind documentation for more information.
 
 The most common tool is Memcheck to check for memory leaks, which you run like this:
@@ -519,6 +527,19 @@ make
 ```
 Keep in mind that the debug version will be much slower due to all compiler optimizations being disabled.
 
+To enable AddressSanitizer which helps with identifying memory issues like corruption bugs and buffer overflows, build with the ASAN option:
+```
+cmake -DCMAKE_BUILD_TYPE=Debug -DASAN=on .
+make
+```
+
+This tool isn't very useful without debug symbols so only include it for a Debug or Profiling build. Both Clang and GCC support this tool.
+
+Specifically on macOS it seems as if AddressSanitizer generates a lot of false positives regarding container overflows, so it may be necessary to ignore these:
+```
+export ASAN_OPTIONS=detect_container_overflow=0
+```
+
 Running `make -j6` (or whatever number of parallel jobs you prefer) speeds up the compilation time if you have cores to spare.
 
 After building ES-DE and trying to execute the application, there could be issues with finding the dynamic link libraries for VLC (assuming VLC was enabled for the build) as these are not installed into a standard location but rather into the /Applications folder. As such, you may need to set the DYLD_LIBRARY_PATH environmental variable to find the VLC libraries. Note that this is not intended or required for the release build that will be shipped in a DMG installer or if you manually install ES-DE using _make install_. It's only needed to be able to run the binary from the build directory. You should add this to your shell profile file to avoid having to set it each time you open a new terminal window:
@@ -749,20 +770,29 @@ Download the Visual Studio Build Tools (choose Visual Studio Community edition):
 
 It seems as if Microsoft has dropped support for installing the Build Tools without the Visual Studio IDE, at least I've been unable to find a way to exclude it. But I just pretend it's not installed and use VSCode instead which works perfectly fine.
 
-During installation, choose the Desktop development with C++ workload with the following options (version details excluded):
+During installation, choose the Desktop development with C++ workload with the following options (version details may differ):
 
 ```
-MSVC and x64/x86 build tools
+MSVC v143 - VS 2022 C++ x64/x86 build tools (Latest)
 Windows 10 SDK
 Just-In-Time debugger
+C++ AddressSanitizer
+```
+
+If you will only use MSVC and not MinGW, then also add this option:
+```
 C++ CMake tools for Windows
 ```
 
-If you intend to use both MinGW and MSVC on the same machine, it's probably better to exclude CMake and install it manually as described in the MinGW setup instructions below.
+If not installing the CMake version supplied by Microsoft, you need to make sure that you have a recent version on your machine or CMake will not be able to detect MSVC correctly.
 
-The way the MSVC environment works is that a specific developer shell is provided where the build environment is properly configured. You open this from the Start menu via `Visual Studio 2019` -> `Visual Studio tools` -> `VC` -> `x64 Native Tools Command Prompt for VS 2019`.
+As well you may need to install the latest version of Microsoft Visual C++ Redistributable which can be downloaded here:\
+https://docs.microsoft.com/en-us/cpp/windows/latest-supported-vc-redis
 
-It's very important to choose the x64-specific shell and not the x86 variant, as ES-DE will only compile as a 64-bit application.
+
+The way the MSVC environment works is that a specific developer shell is provided where the build environment is properly configured. You open this from the Start menu via `Visual Studio 2022` -> `Visual Studio tools` -> `VC` -> `x64 Native Tools Command Prompt for VS 2022 Current`.
+
+It's important to choose the x64-specific shell and not the x86 variant, as ES-DE will only compile as a 64-bit application.
 
 **MinGW (GCC) setup:**
 
@@ -772,10 +802,13 @@ Download the following packages and install them:
 
 [https://cmake.org/download](https://cmake.org/download)
 
+Download the _MinGW-w64 based_ version of GCC: \
 [https://jmeubank.github.io/tdm-gcc](https://jmeubank.github.io/tdm-gcc)
 
 After installation, make a copy of `TDM-GCC-64\bin\mingw32-make` to `make` just for convenience.
 
+Version 9.2.0 of MinGW has been confirmed to work fine, but 10.3.0 appears broken as it causes huge performance problems for the FFmpeg function avfilter_graph_free() with execution times going from milliseconds to hundreds of milliseconds or even seconds.
+
 Note that most GDB builds for Windows have broken Python support so that pretty printing won't work. The recommended MinGW distribution should work fine though.
 
 **Other preparations:**
@@ -1054,6 +1087,12 @@ cmake -G "NMake Makefiles" -DWIN32_INCLUDE_DIR=../include .
 nmake
 ```
 
+To enable AddressSanitizer which helps with identifying memory issues like corruption bugs and buffer overflows, build with the ASAN option:
+```
+cmake -G "NMake Makefiles" -DWIN32_INCLUDE_DIR=../include -DASAN=on .
+nmake
+```
+
 For some annoying reason MSVC is the only compiler that creates a debug build by default and where you need to explicitly set the build type to Release.
 
 Unfortunately nmake does not support parallel compiles so it's very slow. There are third party solutions to get multi-core building working with MSVC, but I've not investigated this in depth.
@@ -1063,7 +1102,7 @@ Be aware that MSVC links against different VC++ libraries for debug and release
 To build ES-DE with the VLC video player in addition to the default FFmpeg player, enable the VLC_PLAYER option, for example:
 ```
 cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release -DWIN32_INCLUDE_DIR=../include -DVLC_PLAYER=on .
-make
+nmake
 ```
 
 **Building ES-DE using MinGW:**
@@ -1082,6 +1121,8 @@ cmake -G "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include -DCMAKE_BUILD_TYPE=Deb
 make
 ```
 
+Unfortunately AddressSanitizer does not seem to be supported with MinGW.
+
 For some reason defining the `../include` path doesn't work when running CMake from PowerShell (and no, changing to backslash doesn't help). Instead use Bash, by running from a Git Bash shell.
 
 The make command works fine directly in PowerShell though so it can be run from the VSCode terminal.

USERGUIDE-DEV.md

@@ -41,12 +41,14 @@ The following operating systems have been tested (all for the x86 architecture u
 * FreeBSD 13.0
 * NetBSD 9.1
 * OpenBSD 6.8
-* macOS 10.14 "Mojave" to 11 "Big Sur" (M1 via Rosetta 2 is supported)
+* macOS 10.14 "Mojave" to 12 "Monterey" (the M1 processor via Rosetta 2 is supported)
 * macOS 10.11 "El Capitan" (v1.0 release only)
 * Windows 10
 * Windows 8.1
 
-**Note:** If using a Mac with an M1 CPU you need to install the x86 version of RetroArch and any other emulators, or you won't be able to launch any games. This will be fixed whenever a native macOS ARM build of ES-DE is released.
+If using a Mac with an M1 processor you need to install the x86 version of RetroArch and any other emulators, or you won't be able to launch any games. This will be fixed whenever a native macOS ARM build of ES-DE is released.
+
+If using macOS Monterey, there has been a quite serious OpenGL bug introduced by Apple which causes problems for ES-DE. A workaround for this issue is discussed [below](USERGUIDE-DEV.md#specific-notes-for-macos).
 
 As for display resolutions, the minimum pixel value is 224 and the maximum is 7680. This means that you can run ES-DE at for instance 320x224 all the way up to 7680x4320 (8K UHD). Vertical screen orientation is also supported, as well as ultra-wide resolutions like 3840x1440. Note that there could be some minor visual glitches when running in vertical orientation (this will be fixed in future ES-DE releases) and for the best experience you will probably need to use a customized theme set when running at extreme or unusual resolutions.
 
@@ -153,6 +155,8 @@ If you accidentally refused ES-DE the folder access, you can fix this by opening
 
 Another issue on macOS 11 Big Sur (and possibly other OS versions) is that when connecting a Sony DualShock 4 controller either via Bluetooth or using a USB cable, two separate controller devices are registered in parallel. This is a bug in either macOS or the DualShock driver and it makes it seem as if ES-DE is registering double button presses when actually two separate controller devices are generating identical input. A workaround if using Bluetooth mode is to plug in the USB cable just after connecting the controller, wait a second or two and then remove the cable again. This will remove the cabled device, leaving only the Bluetooth device active. Another workaround is to enable the setting _Only accept input from first controller_ in the ES-DE input device settings. The reason why this bug may not be visible in some other games and applications is that ES-DE enables and auto-configures all connected controllers.
 
+In macOS 12 Monterey there has been a quite serious OpenGL driver bug introduced by Apple which disables VSync, making the operating system always try to render as many frames as it can. This slows down ES-DE quite a lot and consumes lots of machine resources. The issue is discussed [here](https://github.com/libsdl-org/SDL/issues/4918). There is a temporary workaround available which can be enabled via the _macOS Monterey VSync bug workaround_ setting in the _Other settings_ menu. This will add a short 10 millisecond delay after each frame if the last frame was swapped in less than 3 milliseconds. It's not a proper fix but it should at least make ES-DE usable on Monterey until Apple releases a patch for the bug.
+
 
 ## Specific notes for Raspberry Pi
 
@@ -1180,7 +1184,7 @@ Options specific to the video screensaver.
 
 **Swap videos after (seconds)**
 
-For how long to play videos before changing to the next game. Allowed range is between 0 and 120 seconds in 2-second increments. If set to 0 (which is the default value), the next game will be selected after the entire video has finished playing.
+For how long to play videos before changing to the next game. Allowed range is between 0 and 120 seconds in 2-second increments. If set to 0 (which is the default value), the next game will be selected after the entire video has finished playing. If set to a higher value than the length of a game video, it will loop until reaching the swap time.
 
 **Stretch videos to screen resolution**
 
@@ -1332,6 +1336,10 @@ The metadata for a game is updated by scraping or by manual editing using the me
 
 With this setting enabled, the taskbar will be hidden when launching ES-DE, and it will be restored when the application exits. This can make for a more seamless experience as the taskbar could otherwise flash by briefly when launching and when returning from games. But it can potentially cause issues on some Windows installations so it's disabled by default.
 
+**macOS Monterey VSync bug workaround** _(macOS only and hopefully only temporary)_
+
+In macOS 12 Monterey an OpenGL driver bug was introduced that causes VSync to always be disabled. This makes the operating system try to render as many frames as it can which slows down ES-DE quite a lot as well as consuming lots of machine resources. By enabling this setting, a small 10 millisecond delay will be introduced after each frame if it took less than 3 milliseconds to swap the last one. This is not a proper solution, and it's not an accurate solution but it's at least something until Apple (hopefully) fixes the bug via an OS update. Earlier macOS versions are unaffected by this issue. To check if you have this problem, enable the _Display GPU statistics overlay_ setting and if your FPS counter shows really high numbers (like in the hundreds of frames per second) then enable this option and the FPS counter should decrease significantly.
+
 **Run in background (while game is launched)**
 
 Enabling this option makes ES-DE continue to run while a game is launched. This is normally not recommended as it leads to a slightly strange application behavior and also removes the ability to capture return codes and log output from the emulators. But with some graphics drivers on Windows this may be a suitable workaround if there are problems launching games (also see the next option below). Note that launching Steam games on all supported operating systems always makes ES-DE continue to run in the background for technical reasons.