Documentation update

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 [[_TOC_]]
 
+## Version 2.1.0 (in development)
+
+**Release date:** TBD
+
+### Detailed list of changes
+
+* Added the SameBoy RetroArch core as an alternative emulator for the sgb system
+* (Linux) Added support for the official Citra AppImage release
+* Changed the default OpenGL version from 4.6 to 3.3 when building for RetroDECK
+
+### Bug fixes
+
 ## Version 2.0.1
 
 **Release date:** 2023-04-23

INSTALL-DEV.md

@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) v2.0 (development version) - Building and advanced configuration
+# EmulationStation Desktop Edition (ES-DE) v2.1 (development version) - Building and advanced configuration
 
 This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [INSTALL.md](INSTALL.md) instead.
 

ROADMAP.md

@@ -36,7 +36,7 @@ A more detailed breakdown can be found on the [Kanban](https://gitlab.com/es-de/
 * _Add GLM library dependency for matrix and vector operations, decommission the built-in functions_
 * _AppImage and AUR releases on Linux_
 
-#### v2.0
+#### _v2.0_
 
 * _New theme engine with generalized views (only System and Gamelist) and theme variants support_
 * _Multiple new components (carousel support for the Gamelist view, grid component etc.)_

THEMES-DEV.md

@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) v2.0 (development version) - Themes
+# EmulationStation Desktop Edition (ES-DE) v2.1 (development version) - Themes
 
 **Note:** This document is only relevant for the current ES-DE development version, if you would like to see the documentation for the latest stable release, refer to [THEMES.md](THEMES.md) instead.
 
@@ -133,6 +133,14 @@ Note that the legacy theme engine had quite inaccurate text sizing and font rend
 * The defined line spacing was not always applied for automatically sized text elements
 * Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly)
 
+## System metadata repository
+
+There is a very useful system metadata repository available that you can use for populating information like descriptions, release dates, per-system color palettes etc. It can be found here:
+
+https://gitlab.com/es-de/themes/system-metadata
+
+By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done regularly. Also check the README.md file in that repository for more details on how to actually use the variables.
+
 ## Simple example
 
 Here is a very simple theme that changes the color of the game name text:
@@ -1372,7 +1380,7 @@ Properties:
     - Minimum value is `0` (pure black) and maximum value is `1` (no adjustment)
     - Default is `1`
 * `fastScrolling` - type: BOOLEAN
-    - Normally the carousel scrolls at a constant and somehow slow pace, but via this property it's possible to introduce faster scrolling with an additional higher scrolling tier similar to the gamelist textlist (although slightly slower than that). This requires that the carousel has three or more entries, otherwise the highest scrolling tier will never be triggered. Be aware of possible performance implications when enabling this property, for gamelist views it's probably mostly useful for text-based carousels as streaming carousel images at the higher scrolling speed is likely to lead to stuttering on slower machines. Similarly, using this property in the system view together with gameselector configuration may lead to quite a lot of lag on weaker machines.
+    - Normally the carousel scrolls at a constant and somehow slow pace, but via this property it's possible to introduce faster scrolling with an additional higher scrolling tier similar to the gamelist textlist (although slightly slower than that). This requires that the carousel has three or more entries, otherwise the highest scrolling tier will never be triggered. Be aware of possible performance implications when enabling this property as images have to be streamed at a higher speed which may introduce stuttering on slower machines.
     - Default is `false`
 * `color` - type: COLOR
     - Color of the carousel background panel. Setting a value of `00000000` makes the background panel transparent.

THEMES.md

@@ -131,6 +131,14 @@ Note that the legacy theme engine had quite inaccurate text sizing and font rend
 * The defined line spacing was not always applied for automatically sized text elements
 * Font sizes were rounded to integers, leading to imprecise text sizing across different resolutions (the rounding was also done incorrectly)
 
+## System metadata repository
+
+There is a very useful system metadata repository available that you can use for populating information like descriptions, release dates, per-system color palettes etc. It can be found here:
+
+https://gitlab.com/es-de/themes/system-metadata
+
+By adding this to your theme, either via manually downloading and including it, or by adding it as a Git subtree, you'll be able to access its defined variables. Make sure to regularly check for updates as corrections and additions of new systems are done regularly. Also check the README.md file in that repository for more details on how to actually use the variables.
+
 ## Simple example
 
 Here is a very simple theme that changes the color of the game name text:
@@ -1370,7 +1378,7 @@ Properties:
     - Minimum value is `0` (pure black) and maximum value is `1` (no adjustment)
     - Default is `1`
 * `fastScrolling` - type: BOOLEAN
-    - Normally the carousel scrolls at a constant and somehow slow pace, but via this property it's possible to introduce faster scrolling with an additional higher scrolling tier similar to the gamelist textlist (although slightly slower than that). This requires that the carousel has three or more entries, otherwise the highest scrolling tier will never be triggered. Be aware of possible performance implications when enabling this property, for gamelist views it's probably mostly useful for text-based carousels as streaming carousel images at the higher scrolling speed is likely to lead to stuttering on slower machines. Similarly, using this property in the system view together with gameselector configuration may lead to quite a lot of lag on weaker machines.
+    - Normally the carousel scrolls at a constant and somehow slow pace, but via this property it's possible to introduce faster scrolling with an additional higher scrolling tier similar to the gamelist textlist (although slightly slower than that). This requires that the carousel has three or more entries, otherwise the highest scrolling tier will never be triggered. Be aware of possible performance implications when enabling this property as images have to be streamed at a higher speed which may introduce stuttering on slower machines.
     - Default is `false`
 * `color` - type: COLOR
     - Color of the carousel background panel. Setting a value of `00000000` makes the background panel transparent.

USERGUIDE-DEV.md

@@ -1,4 +1,4 @@
-# EmulationStation Desktop Edition (ES-DE) v2.0 (development version) - User guide
+# EmulationStation Desktop Edition (ES-DE) v2.1 (development version) - User guide
 
 This version of the user guide is only relevant for the current ES-DE development version, if you are using the latest stable release, refer to [USERGUIDE.md](USERGUIDE.md) instead.
 
@@ -233,6 +233,8 @@ In general it should be straightforward to run ES-DE on Windows. Almost all emul
 
 Just make sure to never 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.
 
+Also make sure that you don't use the exFAT filesystem as its very poor disk I/O performance will make ES-DE run really slowly. Using this filesystem will make the theme downloader fail as well.
+
 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 GPUs with buggy drivers, ES-DE may only display a black screen on startup or when launching a game. The problem can be worked around by specifying a window size for ES-DE that is a single pixel wider than the actual screen resolution. So for example for a 1280x800 display, the resolution can be set to 1281x800 and then rendering should work correctly. This is applied using the --resolution command line option, for example:
@@ -547,8 +549,10 @@ If you have customized a theme by for instance modifying any of its XML files, t
 
 In worst case there could be a situation where a repository is corrupted and the theme downloader can't properly identify or handle the corruption. In this case you will have to rename or delete that directory. This could also apply to the actual themes list repository. The latter is named _themes-list_ so by just deleting this directory (i.e. `~/.emulationstation/themes/themes-list`) you'll reset the theme downloader to its initial state.
 
+Note that the exFAT filesystem can't be used as it makes the theme downloader fail. But using this filesystem is strongly discouraged anyway as it offers very poor disk I/O performance which makes ES-DE run really slowly.
+
 ![alt text](images/es-de_theme_downloader.png "ES-DE Theme Downloader")
-_This shows the theme downloader with a number of installed themes._
+_The theme downloader with a number of installed themes._
 
 ## RetroArch setup
 
@@ -633,6 +637,7 @@ The following emulators are supported in AppImage format when using the bundled
 | gc           | Triforce    | dolphin-emu-triforce*.AppImage  |
 | macintosh    | Basilisk II | BasiliskII*.AppImage            |
 | macintosh    | SheepShaver | SheepShaver*.AppImage           |
+| n3ds         | Citra       | citra-linux-*.AppImage          |
 | n64          | RMG         | RMG*.AppImage                   |
 | n64dd        | RMG         | RMG*.AppImage                   |
 | ps2          | PCSX2       | pcsx2*-Qt.AppImage              |
@@ -3172,7 +3177,7 @@ The **@** symbol indicates that the emulator is _deprecated_ and will be removed
 | segacd                | Sega CD                                        | Genesis Plus GX                   | Genesis Plus GX Wide,<br>PicoDrive,<br>ares **(Standalone)** | Yes          |                                      |
 | sfc                   | Nintendo SFC (Super Famicom)                   | Snes9x - Current                  | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No           | Single archive or ROM file |
 | sg-1000               | Sega SG-1000                                   | Genesis Plus GX                   | Genesis Plus GX Wide,<br>Gearsystem,<br>blueMSX,<br>ares **(Standalone)** | No           |                                      |
-| sgb                   | Nintendo Super Game Boy                        | Mesen-S                           | mGBA,<br>mGBA **(Standalone)**    |              |  Single archive or ROM file |
+| sgb                   | Nintendo Super Game Boy                        | Mesen-S                           | SameBoy,<br>mGBA,<br>mGBA **(Standalone)**    |              |  Single archive or ROM file |
 | snes                  | Nintendo SNES (Super Nintendo)                 | Snes9x - Current                  | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No           | Single archive or ROM file |
 | snesna                | Nintendo SNES (Super Nintendo) [North America] | Snes9x - Current                  | Snes9x 2010,<br>Snes9x **(Standalone)**,<br>bsnes,<br>bsnes-hd,<br>bsnes-mercury Accuracy,<br>bsnes **(Standalone)** [UW],<br>Beetle Supafaust [UW],<br>Mesen-S,<br>Mednafen **(Standalone)**,<br>ares **(Standalone)** | No           | Single archive or ROM file |
 | solarus               | Solarus Game Engine                            | Solarus **(Standalone)**          |                                   | No           | Single .solarus game file |

USERGUIDE.md

@@ -231,6 +231,8 @@ In general it should be straightforward to run ES-DE on Windows. Almost all emul
 
 Just make sure to never 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.
 
+Also make sure that you don't use the exFAT filesystem as its very poor disk I/O performance will make ES-DE run really slowly. Using this filesystem will make the theme downloader fail as well.
+
 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 GPUs with buggy drivers, ES-DE may only display a black screen on startup or when launching a game. The problem can be worked around by specifying a window size for ES-DE that is a single pixel wider than the actual screen resolution. So for example for a 1280x800 display, the resolution can be set to 1281x800 and then rendering should work correctly. This is applied using the --resolution command line option, for example:
@@ -545,8 +547,10 @@ If you have customized a theme by for instance modifying any of its XML files, t
 
 In worst case there could be a situation where a repository is corrupted and the theme downloader can't properly identify or handle the corruption. In this case you will have to rename or delete that directory. This could also apply to the actual themes list repository. The latter is named _themes-list_ so by just deleting this directory (i.e. `~/.emulationstation/themes/themes-list`) you'll reset the theme downloader to its initial state.
 
+Note that the exFAT filesystem can't be used as it makes the theme downloader fail. But using this filesystem is strongly discouraged anyway as it offers very poor disk I/O performance which makes ES-DE run really slowly.
+
 ![alt text](images/es-de_theme_downloader.png "ES-DE Theme Downloader")
-_This shows the theme downloader with a number of installed themes._
+_The theme downloader with a number of installed themes._
 
 ## RetroArch setup