Documentation update.

This commit is contained in:
Leon Styhre 2022-01-02 13:28:24 +01:00
parent 6431804ee7
commit f74a8afbd7
4 changed files with 28 additions and 164 deletions

View file

@ -10,6 +10,18 @@
### Detailed list of changes ### Detailed list of changes
* Removed the deprecated VideoVlcComponent
### Bug fixes
## Version 1.2.1 (in development)
**Release date:** TBD
### Release overview
### Detailed list of changes
### Bug fixes ### Bug fixes
## Version 1.2.0 ## Version 1.2.0

View file

@ -30,11 +30,6 @@ All of the required packages can be installed with apt-get:
sudo apt-get install build-essential clang-format git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev libasound2-dev libgl1-mesa-dev sudo apt-get install build-essential clang-format git cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev libasound2-dev libgl1-mesa-dev
``` ```
If building with the optional VLC video player, the following packages are also needed:
```
sudo apt-get install vlc libvlc-dev
```
**Fedora** **Fedora**
On Fedora you first need to install the RPM Fusion repository: On Fedora you first need to install the RPM Fusion repository:
@ -49,12 +44,6 @@ Then you can use dnf to install all the required packages:
``` ```
sudo dnf install gcc-c++ clang-tools-extra cmake rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel sudo dnf install gcc-c++ clang-tools-extra cmake rpm-build SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel alsa-lib-devel mesa-libGL-devel
``` ```
If building with the optional VLC video player, the following packages are also needed:
```
sudo dnf install vlc vlc-devel
```
**Manjaro** **Manjaro**
@ -64,11 +53,6 @@ Use pacman to install all the required packages:
sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml sudo pacman -S gcc clang make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml
``` ```
If building with the optional VLC video player, the following package is also needed:
```
sudo pacman -S vlc
```
**Raspberry Pi OS (Raspian)** **Raspberry Pi OS (Raspian)**
All of the required packages can be installed with apt-get: All of the required packages can be installed with apt-get:
@ -76,11 +60,6 @@ All of the required packages can be installed with apt-get:
sudo apt-get install clang-format cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libcurl4-gnutls-dev libpugixml-dev sudo apt-get install clang-format cmake libsdl2-dev libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev libfreeimage-dev libcurl4-gnutls-dev libpugixml-dev
``` ```
If building with the optional VLC video player, the following packages are also needed:
```
sudo apt-get install vlc libvlc-dev
```
To build with CEC support you also need to install these packages: To build with CEC support you also need to install these packages:
``` ```
sudo apt-get install libcec-dev libp8-platform-dev sudo apt-get install libcec-dev libp8-platform-dev
@ -97,11 +76,6 @@ Use pkg to install the dependencies:
pkg install llvm-devel git pkgconf cmake sdl2 ffmpeg freeimage pugixml pkg install llvm-devel git pkgconf cmake sdl2 ffmpeg freeimage pugixml
``` ```
If building with the optional VLC video player, the following package is also needed:
```
pkg install vlc
```
Clang/LLVM and cURL should already be included in the base OS installation. Clang/LLVM and cURL should already be included in the base OS installation.
**NetBSD** **NetBSD**
@ -111,11 +85,6 @@ Use pkgin to install the dependencies:
pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml pkgin install clang git cmake pkgconf SDL2 ffmpeg4 freeimage pugixml
``` ```
If building with the optional VLC video player, the following package is also needed:
```
pkgin vlc
```
NetBSD ships with GCC by default, and although you should be able to use Clang/LLVM, it's probably easier to just stick to the default compiler environment. The reason why the clang package needs to be installed is to get clang-format onto the system. NetBSD ships with GCC by default, and although you should be able to use Clang/LLVM, it's probably easier to just stick to the default compiler environment. The reason why the clang package needs to be installed is to get clang-format onto the system.
**OpenBSD** **OpenBSD**
@ -125,11 +94,6 @@ Use pkg_add to install the dependencies:
pkg_add clang-tools-extra cmake pkgconf sdl2 ffmpeg freeimage pkg_add clang-tools-extra cmake pkgconf sdl2 ffmpeg freeimage
``` ```
If building with the optional VLC video player, the following package is also needed:
```
pkg_add vlc
```
In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default. In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default.
Pugixml does exist in the package collection but somehow this version is not properly detected by CMake, so you need to compile this manually as well: Pugixml does exist in the package collection but somehow this version is not properly detected by CMake, so you need to compile this manually as well:
@ -168,12 +132,6 @@ cmake .
make make
``` ```
To build ES-DE with the VLC video player in addition to the default FFmpeg player, enable the VLC_PLAYER option, for example:
```
cmake -DVLC_PLAYER=on .
make
```
To create a debug build, run this: To create a debug build, run this:
``` ```
cmake -DCMAKE_BUILD_TYPE=Debug . cmake -DCMAKE_BUILD_TYPE=Debug .
@ -486,12 +444,6 @@ Install the required tools:
brew install clang-format cmake pkg-config nasm yasm brew install clang-format cmake pkg-config nasm yasm
``` ```
If building with the optional VLC video player, then run this as well:
```
brew install --cask vlc
```
**Some additional/optional steps** **Some additional/optional steps**
Enable developer mode to avoid annoying password requests when attaching the debugger to a process: Enable developer mode to avoid annoying password requests when attaching the debugger to a process:
@ -555,12 +507,6 @@ cmake .
make make
``` ```
To build ES-DE with the VLC video player in addition to the default FFmpeg player, enable the VLC_PLAYER option:
```
cmake -DVLC_PLAYER=on .
make
```
To generate a debug build, run this: To generate a debug build, run this:
``` ```
cmake -DCMAKE_BUILD_TYPE=Debug . cmake -DCMAKE_BUILD_TYPE=Debug .
@ -600,11 +546,6 @@ 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. 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:
```
export DYLD_LIBRARY_PATH=/Applications/VLC.app/Contents/MacOS/lib
```
Running ES-DE from the build directory may be a bit flaky as there is no Info.plist file available which is required for setting the proper window mode and such. It's therefore recommended to run the application from the installation directory for any more in-depth testing. But normal debugging can of course be done from the build directory. Running ES-DE from the build directory may be a bit flaky as there is no Info.plist file available which is required for setting the proper window mode and such. It's therefore recommended to run the application from the installation directory for any more in-depth testing. But normal debugging can of course be done from the build directory.
**Building for the M1 (ARM) processor** **Building for the M1 (ARM) processor**
@ -634,40 +575,13 @@ You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the
As macOS does not have any package manager which would have handled the library dependencies, we need to bundle the required shared libraries with the application. This is almost completely automated by the build scripts. As macOS does not have any package manager which would have handled the library dependencies, we need to bundle the required shared libraries with the application. This is almost completely automated by the build scripts.
The only exceptions are these libraries for the optional VLC video player: You can install the application as a normal user, i.e. no root privileges are required. Simply run the following:
```
libvlc.dylib
libvlccore.dylib
```
If building the VLC video player, copy these files from the /Applications/VLC.app/Contents/MacOS/lib/ directory to the emulationstation-de build folder.
In addition to these you need to create a `plugins` directory and copy over the following libraries, which are located in /Applications/VLC.app/Contents/MacOS/plugins/:
```
libadummy_plugin.dylib
libamem_plugin.dylib
libaudio_format_plugin.dylib
libauhal_plugin.dylib
libavcodec_plugin.dylib
libconsole_logger_plugin.dylib
libfilesystem_plugin.dylib
libfreetype_plugin.dylib
libswscale_plugin.dylib
libtrivial_channel_mixer_plugin.dylib
libvmem_plugin.dylib
libwave_plugin.dylib
libx264_plugin.dylib
libx265_plugin.dylib
```
On macOS you can install the application as a normal user, i.e. no root privileges are required. Simply run the following:
``` ```
make install make install
``` ```
This will be the directory structure for the installation (the VLC-related files are optional): This will be the directory structure for the installation:
``` ```
/Applications/EmulationStation Desktop Edition.app/Contents/Info.plist /Applications/EmulationStation Desktop Edition.app/Contents/Info.plist
@ -682,8 +596,6 @@ This will be the directory structure for the installation (the VLC-related files
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.55.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpostproc.55.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.3.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.3.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.5.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.5.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlc.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlccore.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbis.0.4.9.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbis.0.4.9.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbisenc.2.0.12.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvorbisenc.2.0.12.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/plugins/* /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/plugins/*
@ -815,13 +727,8 @@ cURL (Windows 64 bit binary, select the MinGW version even if using MSVC) \
SDL2 (development libraries, MinGW or VC/MSVC) \ SDL2 (development libraries, MinGW or VC/MSVC) \
[https://www.libsdl.org/download-2.0.php](https://www.libsdl.org/download-2.0.php) [https://www.libsdl.org/download-2.0.php](https://www.libsdl.org/download-2.0.php)
libVLC (both win64 binary and source distributions) - optional, if building with the VLC video player\
[https://ftp.lysator.liu.se/pub/videolan/vlc](https://ftp.lysator.liu.se/pub/videolan/vlc)
Uncompress the files from the above packages to a suitable directory, for example `C:\Programming\Dependencies` Uncompress the files from the above packages to a suitable directory, for example `C:\Programming\Dependencies`
Append `_src` or something appropriate to the VLC source distribution directory as it has the same name as the binary distribution.
GLEW\ GLEW\
[http://glew.sourceforge.net](http://glew.sourceforge.net) [http://glew.sourceforge.net](http://glew.sourceforge.net)
@ -902,7 +809,7 @@ As there is no standardized include directory structure in Windows, you need to
Make a directory in your build environment tree, for instance under `C:\Programming\include` Make a directory in your build environment tree, for instance under `C:\Programming\include`
Copy the include files for cURL, FFmpeg, FreeImage, FreeType, GLEW, pugixml, SDL2 and optionally VLC to this directory. Copy the include files for cURL, FFmpeg, FreeImage, FreeType, GLEW, pugixml and SDL2 to this directory.
You may need to create the SDL2 directory manually and copy the header files there. You may need to create the SDL2 directory manually and copy the header files there.
@ -924,7 +831,6 @@ libavutil/
pugiconfig.hpp pugiconfig.hpp
pugixml.hpp pugixml.hpp
SDL2/ SDL2/
vlc/ (only if building with the VLC video player)
``` ```
**Copy the required library files to the ES-DE build directory** **Copy the required library files to the ES-DE build directory**
@ -957,8 +863,6 @@ glew32.lib
libcurl-x64.dll libcurl-x64.dll
libcrypto-1_1-x64.dll (from the OpenSSL package, located in Git MinGW/MSYS2 under \mingw64\bin) libcrypto-1_1-x64.dll (from the OpenSSL package, located in Git MinGW/MSYS2 under \mingw64\bin)
libssl-1_1-x64.dll (from the OpenSSL package, located in Git MinGW under \mingw64\bin) libssl-1_1-x64.dll (from the OpenSSL package, located in Git MinGW under \mingw64\bin)
libvlc.dll (only if building with the VLC video player)
libvlccore.dll (only if building with the VLC video player)
pugixml.dll pugixml.dll
pugixml.lib pugixml.lib
SDL2.dll SDL2.dll
@ -970,9 +874,8 @@ VCRUNTIME140.dll (from Windows\System32)
VCRUNTIME140_1.dll (from Windows\System32) VCRUNTIME140_1.dll (from Windows\System32)
``` ```
In addition to these files, you need libcurl-x64.lib and libvlc.lib (if building with the VLC video player), but these are not available for download so you need to generate them yourself from their corresponding DLL files. Do this inside the respective library directory and not within the emulationstation-de folder. In addition to these files, you need libcurl-x64.lib, but this file is not available for download so you need to generate it yourself from its corresponding DLL file. Do this inside the library directory and not within the emulationstation-de folder:
libcurl-x64.lib:
``` ```
dumpbin /exports libcurl-x64.dll > exports.txt dumpbin /exports libcurl-x64.dll > exports.txt
echo LIBRARY libcurl-x64 > libcurl-x64.def echo LIBRARY libcurl-x64 > libcurl-x64.def
@ -981,15 +884,6 @@ for /f "skip=19 tokens=4" %A in (exports.txt) do echo %A >> libcurl-x64.def
lib /def:libcurl-x64.def /out:libcurl-x64.lib /machine:x64 lib /def:libcurl-x64.def /out:libcurl-x64.lib /machine:x64
``` ```
libvlc.lib:
```
dumpbin /exports libvlc.dll > exports.txt
echo LIBRARY libvlc > libvlc.def
echo EXPORTS >> libvlc.def
for /f "skip=19 tokens=4" %A in (exports.txt) do echo %A >> libvlc.def
lib /def:libvlc.def /out:libvlc.lib /machine:x64
```
**Required files for MinGW:** **Required files for MinGW:**
``` ```
@ -1008,46 +902,12 @@ libfreetype.dll
libpugixml.dll libpugixml.dll
libSDL2main.a libSDL2main.a
libssl-1_1-x64.dll (from the OpenSSL package, located in Git MinGW under \mingw64\bin) libssl-1_1-x64.dll (from the OpenSSL package, located in Git MinGW under \mingw64\bin)
libvlc.dll (only if building with the VLC video player)
libvlccore.dll (only if building with the VLC video player)
SDL2.dll SDL2.dll
vcomp140.dll (From Visual C++ Redistributable for Visual Studio 2015, 32-bit version) vcomp140.dll (From Visual C++ Redistributable for Visual Studio 2015, 32-bit version)
``` ```
**Additional files for both MSVC and MinGW if building with the VLC video player**
In addition to the files above, you need to copy some libraries from the VLC `plugins` folder. This contains a subdirectory structure but there is no requirement to retain this as libVLC apparently looks recursively for the .dll files.
The following libraries seem to be required to play most video and audio formats:
```
access\libfilesystem_plugin.dll
audio_filter\libaudio_format_plugin.dll
audio_filter\libtrivial_channel_mixer_plugin.dll
audio_output\libadummy_plugin.dll
audio_output\libamem_plugin.dll
audio_output\libdirectsound_plugin.dll
audio_output\libmmdevice_plugin.dll
audio_output\libwasapi_plugin.dll
audio_output\libwaveout_plugin.dll
codec\libavcodec_plugin.dll
codec\libx264_plugin.dll
codec\libx265_plugin.dll
logger\libconsole_logger_plugin.dll
video_chroma\libswscale_plugin.dll
video_output\libvmem_plugin.dll
```
The reason to not simply copy all plugins is that the combined size of these is around 120 MB (as of VLC version 3.0.11) and the size of the selected files listed above is around 22 MB, which is more reasonable.
Place the files in the `emulationstation-de\plugins\` directory.
**Building ES-DE using MSVC** **Building ES-DE using MSVC**
There is a bug in libVLC when building using MSVC, so three lines need to be commented out from `libvlc_media.h`. The compiler error messages will provide you with the line numbers, but they involve the callback `libvlc_media_read_cb`.
After doing this, ES-DE should build correctly.
For a release build: For a release build:
``` ```
@ -1075,12 +935,6 @@ Unfortunately nmake does not support parallel compiles so it's very slow. There
Be aware that MSVC links against different VC++ libraries for debug and release builds (e.g. MSVCP140.dll or MSVCP140d.dll), so any NSIS package made from a debug build will not work on computers without the MSVC development environment installed. Be aware that MSVC links against different VC++ libraries for debug and release builds (e.g. MSVCP140.dll or MSVCP140d.dll), so any NSIS package made from a debug build will not work on computers without the MSVC development environment installed.
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 .
nmake
```
**Building ES-DE using MinGW** **Building ES-DE using MinGW**
For a release build: For a release build:
@ -1103,12 +957,6 @@ For some reason defining the `../include` path doesn't work when running CMake f
The make command works fine directly in PowerShell though so it can be run from the VSCode terminal. The make command works fine directly in PowerShell though so it can be run from the VSCode terminal.
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 "MinGW Makefiles" -DWIN32_INCLUDE_DIR=../include -DVLC_PLAYER=on .
make
```
You run a parallel build using multiple CPU cores with the `-j` flag, for example, `make -j6`. You run a parallel build using multiple CPU cores with the `-j` flag, for example, `make -j6`.
Note that compilation time is much longer than on Unix or macOS, and linking time is unendurable for a debug build (around 10 times longer compared to Linux). The debug binary is also much larger than on Unix. Note that compilation time is much longer than on Unix or macOS, and linking time is unendurable for a debug build (around 10 times longer compared to Linux). The debug binary is also much larger than on Unix.

View file

@ -190,16 +190,18 @@ Dec 30 Error: Required OpenGL extensions missing.
The log file is located in the ES-DE home directory and would be something like `C:\Users\myusername\.emulationstation\es_log.txt` The log file is located in the ES-DE home directory and would be something like `C:\Users\myusername\.emulationstation\es_log.txt`
An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after doing this, but following this the emulator should be found when launching a game. Another possibility is that OpenGL drivers are actually installed but the GPU doesn't support the extensions listed above. That would be quite surprising though as these extensions have existed for many years. But for ancient graphics cards there's the possibility that ES-DE won't run.
An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game.
## Specific notes for macOS ## Specific notes for macOS
The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers. The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers.
As Apple refuses to support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for macOS in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, then go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button in the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions. As macOS does not support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for this operating system in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions.
Lack of controller support is another issue, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot. Lack of controller support is another problem, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot.
ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures. ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures.
@ -1527,7 +1529,7 @@ If enabled, only ROMs that have metadata saved to the gamelist.xml files will be
**Disable desktop composition (requires restart)** _(Unix only)_ **Disable desktop composition (requires restart)** _(Unix only)_
The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphic cards and when running at higher resolution. As such the desktop compositor is disabled by default, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that this setting can cause problems with some graphics drivers (notably the Nvidia proprietary drivers) so if you see strange flickering and similar after quitting ES-DE, then disable the setting. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option). The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphics cards and when running at higher resolution. As such the desktop compositor is disabled by default, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that this setting can cause problems with some graphics drivers (notably the Nvidia proprietary drivers) so if you see strange flickering and similar after quitting ES-DE, then disable the setting. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option).
**Display GPU statistics overlay** **Display GPU statistics overlay**

View file

@ -188,16 +188,18 @@ Dec 30 Error: Required OpenGL extensions missing.
The log file is located in the ES-DE home directory and would be something like `C:\Users\myusername\.emulationstation\es_log.txt` The log file is located in the ES-DE home directory and would be something like `C:\Users\myusername\.emulationstation\es_log.txt`
An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment Variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after doing this, but following this the emulator should be found when launching a game. Another possibility is that OpenGL drivers are actually installed but the GPU doesn't support the extensions listed above. That would be quite surprising though as these extensions have existed for many years. But for ancient graphics cards there's the possibility that ES-DE won't run.
An issue on Windows is that some emulators are not shipped with proper installers that implement any mechanism to inform ES-DE where they have been installed (like adding a Registry key with the installation path). This is the case for instance for RPCS3, xemu and xenia. Such emulators are marked accordingly in the _Supported game systems_ table at the bottom of this guide. These type of emulators are simply shipped as a ZIP file that can be unpacked anywhere on the filesystem. So in order for ES-DE to find them, the directories need to be manually added to the operating system's Path environment variable. This is very easy to do, just open the _Settings_ application and then search for _path_ in the _Find a setting_ search box. Select the _Edit the system environment variables_ entry and then click the _Environment variables..._ button and add the emulator directory to the _Path_ variable. You need to restart ES-DE after changing the variable, but following this the emulator should be found when launching a game.
## Specific notes for macOS ## Specific notes for macOS
The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers. The main issue with macOS is lack of emulator support and missing (or buggy) controller drivers.
As Apple refuses to support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for macOS in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, then go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button in the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions. As macOS does not support Vulkan some emulators are simply not available, and other emulators exist but have not been updated for this operating system in recent years. As well many emulators are available for download but are not codesigned or notarized which require you to override the operating system's security settings to be able to use them. If you see an error popup stating the application couldn't be checked for malicious software or that the developer couldn't be verified, go to _System Preferences_, then _Security & Privacy_ and click the _Open Anyway_ button under the _General_ tab. Just note that doing so comes with some potential risks of virus infections and similar. Additionally some emulators are available via the Homebrew package manager, and these do not have the security issues just mentioned so they should be fine to use. Most RetroArch cores are also available on macOS so overall this operating system is still fine for retrogaming albeit with some restrictions.
Lack of controller support is another issue, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot. Lack of controller support is another problem, and in some instances controller drivers are available but quite buggy. In general it seems as if Sony PlayStation controllers are better supported than Microsoft Xbox controllers. For third party controllers you need to investgate the macOS support as it seems to differ quite a lot.
ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures. ES-DE currently ships only as an x86/Intel binary so if you run it on an M1 Mac, you need to also install x86 versions of all emulators including RetroArch. That's also the case for any emulators installed via Homebrew. The reason this is needed is that the Rosetta 2 translation environment does not support mixing of ARM and x86 architectures.
@ -1525,7 +1527,7 @@ If enabled, only ROMs that have metadata saved to the gamelist.xml files will be
**Disable desktop composition (requires restart)** _(Unix only)_ **Disable desktop composition (requires restart)** _(Unix only)_
The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphic cards and when running at higher resolution. As such the desktop compositor is disabled by default, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that this setting can cause problems with some graphics drivers (notably the Nvidia proprietary drivers) so if you see strange flickering and similar after quitting ES-DE, then disable the setting. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option). The window manager desktop composition can adversely affect the framerate of ES-DE, especially on weaker graphics cards and when running at higher resolution. As such the desktop compositor is disabled by default, although the window manager has to be configured to allow applications to do this for the option to have any effect. Note that this setting can cause problems with some graphics drivers (notably the Nvidia proprietary drivers) so if you see strange flickering and similar after quitting ES-DE, then disable the setting. In case of such issues, make sure that the emulator is also not blocking the composition (e.g. RetroArch has a corresponding option).
**Display GPU statistics overlay** **Display GPU statistics overlay**