From 5df9e722a5092661bd19dcb822e248e64e01d91c Mon Sep 17 00:00:00 2001 From: Leon Styhre Date: Sat, 15 Jan 2022 16:24:20 +0100 Subject: [PATCH] Documentation update. --- CHANGELOG.md | 14 +++++++++++++- CONTRIBUTING.md | 31 +++++++++++++++++-------------- INSTALL-DEV.md | 5 +++-- INSTALL.md | 4 ++-- THEMES-DEV.md | 8 ++++---- USERGUIDE-DEV.md | 20 +++++++++++++++----- USERGUIDE.md | 2 +- 7 files changed, 55 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 51b7a8a08..b0167836b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,17 +12,29 @@ * Added support for Lottie animations (vector graphics), fully configurable as a theme extra * Added scraper support for displaying the returned platform if it does not match the game platform, or if multiple platforms are defined for the system +* Added scraping of fan art and updated the media viewer to display these images +* Added scraping of box back covers when using TheGamesDB * Set the option "Scrape actual folders" as enabled by default and moved it higher up in the scraper options menu +* Added the ability to set a manual sortname specifically for custom collections using the metadata editor +* Added an OpenGL ES 2.0 renderer (borrowed from the RetroPie fork of EmulationStation) +* Added logging of the display refresh rate on startup * Added a color model conversion shader for converting from BGRA to RGBA * Added renderer support for supplying a separate format than internalFormat when creating textures (although not really supported by the OpenGL standard) * Added the rlottie library as a Git subtree * On Windows all dependencies were moved in-tree to the "external" directory to greatly simplify the build environment * Large refactoring to improve thread safety and improve singleton pattern usage +* Moved all Platform functions to the utility namespace instead of using the global namespace +* Renamed GameList to Gamelist throughout the codebase +* Renamed Gamelist.cpp and Gamelist.h to GamelistFileParser.cpp and GamelistFileParser.h and moved it to its own namespace instead of the global namespace +* Removed some unnecessary typedefs and replaced the remaining ones with the more modern "using" keyword * Removed the deprecated VideoVlcComponent ### Bug fixes -* During some menu operations that reloaded the gamelist view, the cached background would sometimes miss some elements as they were not rendered in time +* During some menu operations that reloaded the gamelist view, the cached background could miss some elements as they were not rendered in time +* Changing some values using the metadata editor could lead to an incorrect sort order if the changes were done from within a grouped custom collection +* Changing the setting "Group unthemed custom collections" could lead to incorrect custom collections sorting under some circumstances +* Clearing a game in the metadata editor would sometimes not remove all media files (if there were both a .jpg and a .png for a certain file type) * The ScummVM platform entry was missing for TheGamesDB which resulted in very inaccurate scraper searches * During multi-scraping the busy indicator was not displayed after a result was acquired but before the thumbnail was completely downloaded diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bbcd51d94..9f1847ce6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,13 +4,15 @@ Contributions are very much appreciated as there are many things that need to be implemented and improved. -Code commits is only one part of it, as work is also needed on the rbsimple-DE theme set as well as thorough application testing. It's impossible for me to test every game system as ES-DE has support for well over a 100 different platforms. +There are basically three areas where help is needed: -And a thorough review of [unix/es_systems.xml](resources/systems/unix/es_systems.xml), [macos/es_systems.xml](resources/systems/macos/es_systems.xml) and [windows/es_systems.xml](resources/systems/windows/es_systems.xml) would be great as these templates are not fully populated yet. For some of the game systems there are only placeholder entries, mostly for platforms that RetroArch does not support and where discrete emulators are required. +* Programming: If you are experienced with developing cross-platform client applications in C++ then ES-DE could be an interesting project! Although the application does not have a huge codebase, it is still fairly complex as it covers many different areas like OpenGL rendering, audio playback, video playback, controller input, network access, XML and JSON parsing etc. To work on the project you need to be able to test your code on Linux, macOS and Windows, but apart from that it should hopefully be fairly straightforward. -As for rbsimple-DE there are quite some missing graphic files and other customizations for a number of game systems. Check out [MISSING.md](themes/rbsimple-DE/MISSING.md) for more details on what needs to be added or updated. Note that although rbsimple-DE is based on Recalbox Multi, it's only possible to use assets from this theme set created before its change to a more restrictive license, which happened in 2018. As such it's unfortunately necessary to recreate all the system graphics from scratch that have since been released by the Recalbox community. +* Graphics: There are a few different areas where help is needed, but primarily it would be to create game systems vector graphics for the default rbsimple-DE theme as it's missing a lot of assets today. Check out [MISSING.md](themes/rbsimple-DE/MISSING.md) for more details about this. -Another area where help is really needed is for creation of installation instruction videos and similar. There are some rudimentary videos available at the ES-DE [YouTube channel](https://www.youtube.com/channel/UCosLuC9yIMQPKFBJXgDpvVQ), but proper videos with voice-over and similar are needed to help especially new ES-DE users. However the videos don't need to be located at this YouTube channel. I have zero interest in creating videos or maintaining a channel of my own, there's simply a need to have video instructions available somewhere. So if you can create good videos and prefer to use your own YouTube channel, I will link to them from this repository and from https://es-de.org. +* Emulator configuration and testing: As one of the main goals of ES-DE is easy setup, the application needs to ship with all game systems preconfigured. This means that the es_systems.xml files have to be populated with both primary and alternative emulators for all supported operating systems. There could also be a need to add additional platforms that ES-DE does not support today. Please refer to [USERGUIDE-DEV.md](USERGUIDE-DEV.md#supported-game-systems) for the current game systems status. You can also review the es_systems.xml files directly: [unix/es_systems.xml](resources/systems/unix/es_systems.xml), [macos/es_systems.xml](resources/systems/macos/es_systems.xml) and [windows/es_systems.xml](resources/systems/windows/es_systems.xml). + +Another specific area where help is needed is to research and potentially develop a usable web version of ES-DE. A proof of concept compilation to WebAssembly (using Emscripten) has been done and the application actually runs somehow correctly in a browser. But it needs to be investigated whether games/emulators can actually be launched when running in this environment and there are many improvements to be completed before the WebAssembly build is usable. The ES-DE development is tracked using a Kanban board which is publicly visible at the GitLab project site: @@ -58,20 +60,19 @@ The roadmap is under constant review so expect it to change from time to time. S * _Add GLM library dependency for matrix and vector operations, decommission the built-in functions_ * _AppImage and AUR releases on Linux_ -#### v1.3 +#### v1.3 (in progress) * New theme engine with generalized views (only System and Gamelist) and theme variants support * Multiple new gamelist components (wheels, wall/grid etc.) +* Lottie animation (vector graphics) support * Checksum support for the scraper for exact searches and for determining when to overwrite files -* Improved text and font functions, e.g. faster and cleaner line wrapping and more exact sizing #### v1.4 -* Bulk metadata editor * Animated menu elements like switches, tick boxes, smooth scrolling etc. -* Authoring tools to clean up orphaned gamelist entries, media files etc. * Add scraping of game manuals and maps and create a viewer for these (with PDF, GIF, JPG and PNG support) * Scrollbar component for the gamelist view which can be used by the themes +* Support for additional scraper services (if feasible?) * Web proxy support for the scraper * RetroAchievements.org integration * Add "time played" counter per game, similar to how it works in Steam @@ -82,23 +83,25 @@ The roadmap is under constant review so expect it to change from time to time. S * Localization/multi-language support * Simple file browsing component * New texture/cache manager with support for SVG images and Lottie animations -* Improve the performance of the GLSL shader code -* Support for additional scraper services (if feasible?) * Support for portrait orientation, e.g. for Tate Mode arcade cabinets -* Replacements for the abandoned NanoSVG and FreeImage libraries +* Improved text and font functions, e.g. faster and cleaner line wrapping and more exact sizing -#### v2.0 +#### v1.6 * Vulkan renderer for all supported operating systems * Dependency on MoltenVK to get Metal support on macOS * Decommission of the OpenGL 2.1 and OpenGL ES renderers (or keep as legacy mode/legacy build?) * Better and more accurate GPU and memory usage statistics overlay +* Improve the performance of the GLSL shader code +* Bulk metadata editor * Improve multi-threading -#### v2.1 +#### v1.7 * Migration tools for importing game metadata and media from other frontend applications +* Audit tools to clean up orphaned gamelist entries, media files etc. * Auto-import tools for Steam, Lutris etc. +* Replacements for the abandoned NanoSVG and FreeImage libraries To see which features have been implemented in previous versions, please refer to [CHANGELOG.md](CHANGELOG.md). @@ -123,4 +126,4 @@ But as clang-format won't change the actual code content or fix all code style c ### Building and configuring -Please refer to [INSTALL.md](INSTALL.md) for details on everything related to building ES-DE. +Please refer to [INSTALL.md](INSTALL.md) and [INSTALL-DEV.md](INSTALL-DEV.md) for details on everything related to building ES-DE. diff --git a/INSTALL-DEV.md b/INSTALL-DEV.md index 36515c7d0..7f0523062 100644 --- a/INSTALL-DEV.md +++ b/INSTALL-DEV.md @@ -99,7 +99,7 @@ In the same manner as for FreeBSD, Clang/LLVM and cURL should already be install 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: ``` -git clone git://github.com/zeux/pugixml.git +git clone https://github.com/zeux/pugixml.git cd pugixml git checkout v1.10 cmake . @@ -1607,7 +1607,8 @@ There are two basic categories of metadata, `game` and `folders` and the metdata **\** * `path` - string, the path to the game file, either relative to the %ROMPATH% variable or as an absolute path on the filesystem * `name` - string, the displayed name for the game -* `sortname` - string, used in sorting the gamelist in a system, instead of `name` +* `sortname` - string, used for sorting the system gamelist, instead of using `name` +* `collectionsortname` - string, used for sorting the gamelist for custom collections, instead of using `name` or `sortname` * `desc` - string, a description of the game, longer descriptions will automatically scroll, so don't worry about the size * `rating` - float, the rating for the game, expressed as a floating point number between 0 and 1. Fractional values will be rounded to 0.1 increments (half-stars) during processing * `releasedate` - datetime, the date the game was released, displayed as date only, time is ignored diff --git a/INSTALL.md b/INSTALL.md index 4a8caca10..df6cf30b8 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -133,7 +133,7 @@ In the same manner as for FreeBSD, Clang/LLVM and cURL should already be install 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: ``` -git clone git://github.com/zeux/pugixml.git +git clone https://github.com/zeux/pugixml.git cd pugixml git checkout v1.10 cmake . @@ -861,7 +861,7 @@ make [pugixml](https://pugixml.org) ``` -git clone git://github.com/zeux/pugixml.git +git clone https://github.com/zeux/pugixml.git cd pugixml git checkout v1.10 ``` diff --git a/THEMES-DEV.md b/THEMES-DEV.md index 6bfc9d4e8..87fbb3a6e 100644 --- a/THEMES-DEV.md +++ b/THEMES-DEV.md @@ -660,13 +660,13 @@ Can be created as an extra. #### animation -Lottie (vector graphics) animation. Can be created as an extra. +Lottie animation (vector graphics). Can be created as an extra. * `pos` - type: NORMALIZED_PAIR. * `size` - type: NORMALIZED_PAIR. - If only one axis is specified (and the other is zero), the other will be automatically calculated in accordance with the animation's aspect ratio. Note that this is sometimes not entirely accurate as some animations contain invalid size information. * `origin` - type: NORMALIZED_PAIR. - - Where on the animation `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the animation exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. + - Where on the animation `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the animation exactly in the middle of the screen. If the "POSITION" and "SIZE" attributes are themeable, "ORIGIN" is implied. Default is `0.5 0.5`. * `rotation` - type: FLOAT. - angle in degrees that the animation should be rotated. Positive values will rotate clockwise, negative values will rotate counterclockwise. Default is `0`. * `rotationOrigin` - type: NORMALIZED_PAIR. @@ -676,9 +676,9 @@ Lottie (vector graphics) animation. Can be created as an extra. * `speed` - type: FLOAT. - The relative speed at which to play the animation. Minimum value is `0.2`, maximum value is `3.0`. Default is `1.0`. * `direction` - type: STRING. - - The direction that the animation should be played. Valid values are `normal` (forwards), `reverse` (backwards), `alternate` (bouncing forwards/backwards) and `alternateReverse` (bouncing forwards/backwards but starting with playing backwards). Default is `normal`. + - The direction that the animation should be played. Valid values are `normal` (forwards), `reverse` (backwards), `alternate` (bouncing forwards/backwards) and `alternateReverse` (bouncing backwards/forwards, i.e. starting with playing backwards). Default is `normal`. * `keepAspectRatio` - type: BOOLEAN. - - If true, aspect ratio will be preserved. If false, animation will stretch to the defined size. Note that this is incompatible with only defining one of the axes for the `size` element. Default is `true`. + - If true, aspect ratio will be preserved. If false, animation will stretch to the defined size. Note that setting to `false` is incompatible with only defining one of the axes for the `size` element. Default is `true`. * `visible` - type: BOOLEAN. - If true, component will be rendered, otherwise rendering will be skipped. Can be used to hide elements from a particular view. Default is `true`. * `zIndex` - type: FLOAT. diff --git a/USERGUIDE-DEV.md b/USERGUIDE-DEV.md index 5b8bb1fc7..4a7cf8cc3 100644 --- a/USERGUIDE-DEV.md +++ b/USERGUIDE-DEV.md @@ -875,9 +875,10 @@ Here's an overview of what's supported when using these scrapers: | Screenshots | Yes | Yes | | Title screens | Yes | Yes | | Box covers | Yes | Yes | -| Box back covers | Yes | No | +| Box back covers | Yes | Yes | | Marquees/wheels | Yes | Yes | | 3D boxes | Yes | No | +| Fan art | Yes | Yes | | Physical media | Yes | No | The category **Other game metadata** includes Description, Release date, Developer, Publisher, Genre and Players. @@ -947,6 +948,7 @@ The media directories per game system are: * 3dboxes * backcovers * covers +* fanart * marquees * miximages * physicalmedia @@ -1056,10 +1058,14 @@ Screenshot images of the title screen. Cover art, front of box/case. -**Box back cover images** _(ScreenScraper only)_ +**Box back cover images** Back of box/case. +**Fan art images** + +Fan art, i.e. not official media from the game developer. + **Marquee (wheel) images** Logotype for the game. @@ -1690,7 +1696,11 @@ This is the name that will be shown when browsing the gamelist. If no sortname h **Sortname** _(files only)_ -This entry makes it possible to change the sorting of a game without having to change its name. For instance it can be used to sort _Mille Miglia_ as _1000 Miglia_ or _The Punisher_ as _Punisher, The_. Note that the _Jump to..._ quick selector on the game options menu will base its index on the first character of the sortname if it exists for a game, which could be slightly confusing in some instances when quick jumping in the gamelist. +This entry makes it possible to change the sorting of a game without having to change its name. For instance it can be used to sort _Mille Miglia_ as _1000 Miglia_ or _The Punisher_ as _Punisher, The_. Note that the _Jump to..._ quick selector on the game options menu will base its index on the first character of the sortname if it exists for a game, which could be slightly confusing in some instances when quick jumping in the gamelist. The _sortname_ entry also affects custom collections, although for these it's possible to override the value as described below. + +**Custom collections sortname** _(only visible when editing a game from within a custom collection)_ + +This entry works exactly like _sortname_ but will only affect the sorting for custom collections, meaning the normal system gamelists and the automatic collections (_All games, Favorites_ and _Last played_) will not be affected by this value. If there is both a _sortname_ and a _custom collections sortname_ defined, the latter will take precedence. This also means that the _Jump to..._ quick selector will use the custom collections sortname for its letter index even if there is a different value defined for the regular sortname field. Note that _custom collections sortname_ is completely optional and is only intended for overriding the regular _sortname_ field. Also note that it will affect all custom collections where the game is present; it's not possible to set a different value per collection. **Description** @@ -1794,7 +1804,7 @@ The game media viewer displays videos and images in fullscreen mode and is launc If a game video is available, this will be played automatically when launching the viewer. The _left_ and _right_ buttons are used to navigate betweeen the game media files. By default the video will continue to play when browsing the images, but this can be changed with a setting as described earlier in this document. -The media viewer can display the _video, box cover, box back cover, title screen, screenshot_ and _miximage_. +The media viewer can display the following media: _video, box cover, box back cover, title screen, screenshot_, _fan art_ and _miximage_. The other settings for the media viewer are similar to what is available for the screensavers; the audio can be enabled or disabled, the video can be stretched to fill the entire screen and scanlines and blur can be rendered on top of it. For screenshots and title screens, scanlines can be rendered. All these options are configurable via the _UI Settings_ menu. @@ -1833,7 +1843,7 @@ These automatic collections can be individually enabled or disabled by going to These are collections that you create yourself. Examples could be grouping in genres like _Shoot em up_, _Fighting games_ etc. or perhaps a time period like _1980s_, _1990s_ and so on. -If the theme set supports it, you can create a custom collection directly from a theme. However, rbsimple-DE does not provide such themes as it's believed that grouping them together in a dedicated _Collections_ system is a more elegant solution. Especially since the theme set would need to ship with an almost endless amount of collection themes for whatever categories the users would like to use for their game collections. +If the theme set supports it, you can create a custom collection directly from a theme. However, rbsimple-DE and modern-DE do not provide such themes as it's believed that grouping them together in a dedicated _Collections_ system is a more elegant solution. Especially since the theme set would need to ship with an almost endless amount of collection themes for whatever categories the users would like to use for their game collections. So if you have enabled the option _Group unthemed custom collections_ (it's enabled by default), any collections you add will show up in the special _Collections_ system. Here you can access them just as you would access folders inside a regular gamelist. The amount of games per collection is shown in the description, and a random game is displayed each time you browse through the list. You can also quick jump to this random game by pressing the _Y_ button. diff --git a/USERGUIDE.md b/USERGUIDE.md index 196f0ca6d..42231eb88 100644 --- a/USERGUIDE.md +++ b/USERGUIDE.md @@ -1829,7 +1829,7 @@ These automatic collections can be individually enabled or disabled by going to These are collections that you create yourself. Examples could be grouping in genres like _Shoot em up_, _Fighting games_ etc. or perhaps a time period like _1980s_, _1990s_ and so on. -If the theme set supports it, you can create a custom collection directly from a theme. However, rbsimple-DE does not provide such themes as it's believed that grouping them together in a dedicated _Collections_ system is a more elegant solution. Especially since the theme set would need to ship with an almost endless amount of collection themes for whatever categories the users would like to use for their game collections. +If the theme set supports it, you can create a custom collection directly from a theme. However, rbsimple-DE and modern-DE do not provide such themes as it's believed that grouping them together in a dedicated _Collections_ system is a more elegant solution. Especially since the theme set would need to ship with an almost endless amount of collection themes for whatever categories the users would like to use for their game collections. So if you have enabled the option _Group unthemed custom collections_ (it's enabled by default), any collections you add will show up in the special _Collections_ system. Here you can access them just as you would access folders inside a regular gamelist. The amount of games per collection is shown in the description, and a random game is displayed each time you browse through the list. You can also quick jump to this random game by pressing the _Y_ button.