Documentation update.

CHANGELOG.md

@@ -15,15 +15,20 @@
 * Made gamelist theming much more flexible by allowing any number of elements of any types to be defined
 * Deprecated multiple older theming concepts like features, extras and hardcoded metadata attributes
 * Reorganized the UI Settings menu a bit and added entries to set the variant and aspect ratio for newer theme sets
+* Removed the "Play videos immediately (override theme)" setting
+* Renamed the sound menu option "Play audio for videos in the gamelist view" to "Play audio for gamelist and system view videos"
 * Added support for defining which types of game media to use for all image elements (and also for the video component static image)
 * Added a legacy (backward compatibility) mode for still supporting older RetroPie EmulationStation themes
 * Added theme support for Lottie animations (vector graphics)
 * Added a GameSelectorComponent for displaying game media and metadata in the system view
+* Added support for displaying videos, Lottie animations and date/time elements to the system view
 * Replaced the forceUppercase theme property with a more versatile letterCase property (forceUppercase is retained for legacy theme compatibility)
 * Made it possible to set any text element as a scrollable container using either metadata values or literal strings
 * Added support for defining the scrollable container speed, start delay and reset delay from the theme configuration
 * Added theme support for defining the opacity for most element types
+* Added theme support for defining the video fade-in time
 * Added theme support for enabling and disabling video pillarboxes and scanline rendering
+* Added theme support for enabling or disabling audio playback for videos
 * Disabled the pillarboxes and scanline rendering menu options when using a non-legacy theme set
 * Improved theme element placement by replacing the "alignment" and "logoAlignment" properties with specific horizontal and vertical properties
 * Made it possible to use almost all game metadata field when theming text elements
@@ -36,6 +41,7 @@
 * Set the option "Play audio for screensaver videos" as enabled by default
 * Added the ability to set a manual sortname specifically for custom collections using the metadata editor
 * When scraping in semi-automatic mode, horizontal scrolling of long game names are no longer reset when automatically selecting the result
+* Added support for using the tilde (~) symbol in the es_systems.xml path entries to expand to the user home directory
 * Reduced CPU usage significantly when a menu is open by not rendering the bottom of the stack
 * Reduced CPU usage significantly by only rendering the necessary systems in SystemView
 * Added an OpenGL ES 2.0 renderer (borrowed from the RetroPie fork of EmulationStation)
@@ -45,7 +51,7 @@
 * Changed the warning log level for missing theme files to debug level if the paths are set using variables
 * Added new theme system variables for differentiating between collections and non-collection systems
 * 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 opacity support to the scanline shader
 * 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
 * Updated the build scripts to support native M1/ARM builds on macOS
@@ -65,6 +71,7 @@
 * Moved UIModeController.cpp from the es-app/views directory to es-app
 * Set the clang-format option SpaceBeforeCpp11BracedList to true and reformatted the codebase
 * Removed some unnecessary typedefs and replaced the remaining ones with the more modern "using" keyword
+* Greatly simplified the video controls code (play/stop/pause etc.)
 * Removed the deprecated VideoVlcComponent
 * Lots of general code cleanup and refactoring
 * Updated and improved the theming documentation
@@ -76,9 +83,11 @@
 * Changing the setting "Group unthemed custom collections" could lead to incorrect custom collections sorting under some circumstances
 * When multi-scraping in semi-automatic mode and a long game name was scrolling, the start position was not reset when scraping the next game
 * Slide and fade transitions would sometimes stop working after changing theme sets
+* Using fade transitions, when holding a direction button to scroll the system view carousel, the key repeat would cause an unwanted background rendering
 * Horizontal and vertical gradients were mixed up (showing the opposite gradient type if set in a theme)
-* The VideoComponent static images were not fading out smoothly on gamelist fast-scrolling (only fixed for non-legacy themes)
+* The VideoComponent static images were not fading out smoothly on gamelist fast-scrolling
 * Rating icon outlines would not fade out correctly when fast-scrolling in a gamelist
+* If setting an origin other than 0.5 for a video with pillarboxes enabled, the video would not get centered on the black rectangle
 * 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

THEMES-DEV.md

@@ -78,6 +78,7 @@ The following are the most important changes compared to the legacy theme struct
 * The `video` element properties `showSnapshotNoVideo` and `showSnapshotDelay` have been removed
 * The ambiguous `alignment` property has been replaced with the `horizontalAlignment` and `verticalAlignment` properties (the same is true for `logoAlignment` for the `carousel` component)
 * The `forceUppercase` property has been replaced with the more versatile `letterCase` property
+* The carousel text element hacks `systemInfo` and `logoText` have been removed and replaced with proper carousel properties
 * Correct theme structure is enforced more strictly than before, and deviations will generate error log messages and make the theme loading fail
 * Many additional elements and properties have been added, refer to the [Reference](THEMES-DEV.md#reference) section for more information
 
@@ -761,6 +762,7 @@ Properties:
     - The image will be resized as large as possible so that it fits within this size and maintains its aspect ratio.  Use this instead of `size` when you don't know what kind of image you're using so it doesn't get grossly oversized on one axis (e.g. with a game's image metadata).
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
     - Default is `0.5 0.5`
 * `rotation` - type: FLOAT
     - Angle in degrees that the image should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
@@ -816,9 +818,10 @@ Properties:
 
 #### video
 
-Plays a video and provides support for displaying a static image for a defined time period before starting the video player. Although an unlimited number of videos could in theory be defined per view it's strongly recommended to keep it at a single instance. Playing multiple videos simultaneously takes a lot of CPU resources and ES-DE currently has no audio mixing capabilities so the audio would not play correctly.
+Plays a video and provides support for displaying a static image for a defined time period before starting the video player. Although an unlimited number of videos could in theory be defined per view it's recommended to keep it at a single instance as playing videos takes a lot of CPU resources. But if still going for multiple videos, make sure to use the `audio` property to disable audio on all but one video as ES-DE currently has no audio mixing capabilities so the sound would not play correctly. To use videos in the `system` view, you either need to set a static video using the `path` property, or you need to create a `gameselector` element so game videos can be used.
 
 Supported views:
+* `system `
 * `gamelist`
 
 Instances per view:
@@ -832,15 +835,10 @@ Properties:
     - The video will be resized as large as possible so that it fits within this size and maintains its aspect ratio.  Use this instead of `size` when you don't know what kind of video you're using so it doesn't get grossly oversized on one axis (e.g. with a game's video metadata).
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
-    - Default is `0.5 0.5`
+    - Minimum value per axis is `0` and maximum value per axis is `1`
-* `rotation` - type: FLOAT
-    - Angle in degrees that the text should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
-    - Default is `0`
-* `rotationOrigin` - type: NORMALIZED_PAIR
-    - Point around which the text will be rotated.
     - Default is `0.5 0.5`
 * `path` - type: PATH
-    - Path to a video file. Setting a value for this property will make the video static, i.e. it will only play this video regardless of whether there is a game video available or not. If the `default` property has also been set, it will be overridden as the `path` property takes precedence.
+    - Path to a video file. Setting a value for this property will make the video static, i.e. it will only play this video regardless of whether there is a game video available or not (this also applies to the `system` view if you have a `gameselector` element defined). If the `default` property has also been set, it will be overridden as the `path` property takes precedence.
 * `default` - type: PATH
     - Path to a default video file. The default video will be played when the selected game does not have a video. This property is also applied to any custom collection that does not contain any games when browsing the grouped custom collections system.
 * `defaultImage` - type: PATH
@@ -857,6 +855,11 @@ Properties:
     - `backcover` - This will look for a box back cover image.
     - `3dbox` - This will look for a 3D box image.
     - `fanart` - This will look for a fan art image.
+* `gameselector` - type: STRING
+    - If more than one gameselector elements have 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.
+* `audio` - type: BOOLEAN
+    - Whether to enable or disable audio playback for the video.
+    - Default is `true`
 * `interpolation` - type: STRING
     - Interpolation method to use when scaling raster images. Nearest neighbor (`nearest`) preserves sharp pixels and linear filtering (`linear`) makes the image smoother. Note that this property only affects the static image, not the video scaling. This property also has no effect on scalable vector graphics (SVG) images.
     - Valid values are `nearest` or `linear`
@@ -865,12 +868,16 @@ Properties:
     - Whether to render black pillarboxes (and to a lesses extent letterboxes) for videos with aspect ratios where this is applicable. This is for instance useful for arcade game videos in vertical orientation.
     - Default is `true`
 * `scanlines` - type: BOOLEAN
-    - Whether to use a shader to render scanlines. This property is not compatible with `opacity` so enabling it will set the opacity to `1` (unless it was set to `0` in which case the entire video element is hidden).
+    - Whether to use a shader to render scanlines.
     - Default is `false`
 * `delay` - type: FLOAT
     - Delay in seconds before video will start playing. During the delay period the game image defined via the `imageType` property will be displayed. If that property is not set, then the `delay` property will be ignored.
     - Minimum value is `0` and maximum value is `15`
     - Default is `1.5`
+* `fadeInTime` - type: FLOAT
+    - Time in seconds to fade in the video from pure black. This is completely unrelated to the `scrollFadeIn` property. Note that if this is set to zero it may seem as if the property doesn't work correctly as many ScreenScraper videos have a fade-in baked into the actual video stream. Setting this property to lower than 0.3 seconds or so is generally a bad idea for videos that don't have a fade-in baked in as transitions from the static image will then look like a bad jump cut.
+    - Minimum value is `0` and maximum value is `8`
+    - Default is `1`
 * `scrollFadeIn` - type: BOOLEAN
     - If enabled, a short fade-in animation will be applied when scrolling through games in the gamelist view. This animation is only applied to images and not to actual videos, so if no image metadata has been defined then this property has no effect. For this to work correctly the `delay` property also needs to be set.
     - Default is `false`
@@ -890,6 +897,7 @@ Properties:
 Lottie (vector graphics) animation. Note that these animations take a lot of memory and CPU resources if scaled up to large sizes so it's adviced to not add too many of them to the same view and to not make them too large.
 
 Supported views:
+* `system `
 * `gamelist`
 
 Instances per view:
@@ -901,6 +909,7 @@ Properties:
     - 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 element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
     - 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.
@@ -950,6 +959,7 @@ Properties:
     - Default is `0.15 0.20`
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
     - Default is `0.5 0.5`
 * `rotation` - type: FLOAT
     - Angle in degrees that the badges should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
@@ -1056,6 +1066,7 @@ Properties:
     - `w h` - works like a "text box."  If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
     - Default is `0 0`
 * `rotation` - type: FLOAT
     - Angle in degrees that the text should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise. Rotation is not possible if the `container` property has been set to true.
@@ -1143,6 +1154,7 @@ Properties:
 Displays a date and time as a text string. The format is ISO 8601 (YYYY-MM-DD) by default, but this can be changed using the `format` property. The text _unknown_ will be shown by default if there is no time stamp available. If the property `displayRelative` has been set, the text will be shown as _never_ in case of no time stamp.
 
 Supported views:
+* `system`
 * `gamelist`
 
 Instances per view:
@@ -1157,6 +1169,7 @@ Properties:
     - `w h` - works like a "text box."  If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
     - Default is `0 0`
 * `rotation` - type: FLOAT
     - Angle in degrees that the text should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
@@ -1165,10 +1178,12 @@ Properties:
     - Point around which the text will be rotated.
     - Default is `0.5 0.5`.
 * `metadata` - type: STRING
-    - This displays the metadata values that are available for the game. If an invalid metadata field is defined, the text "unknown" will be printed.
+    - This displays the metadata values that are available for the game. If an invalid metadata field is defined, the text "unknown" will be printed. To use this property from the `system` view, you will first need to add a `gameselector` element.
     - Valid values:
     - `releasedate` - The release date of the game.
     - `lastplayed` - The time the game was last played. This will be displayed as a value relative to the current date and time by default, but can be overridden using the `displayRelative` property.
+* `gameselector` - type: STRING
+    - If more than one gameselector elements have 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 `metadata` property is utilized.
 * `fontPath` - type: PATH
     - Path to a TrueType font (.ttf).
 * `fontSize` - type: FLOAT
@@ -1230,6 +1245,7 @@ Properties:
     - `w h` - works like a "text box."  If `h` is non-zero and `h` <= `fontSize` (implying it should be a single line of text), text that goes beyond `w` will be truncated with an elipses (...).
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
     - Default is `0 0`
 * `rotation` - type: FLOAT
     - Angle in degrees that the text should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
@@ -1278,6 +1294,7 @@ Properties:
     - Only one value is actually used. The other value should be zero.  (e.g. specify width OR height, but not both.  This is done to maintain the aspect ratio.)
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
     - Default is `0 0`
 * `rotation` - type: FLOAT
     - Angle in degrees that the rating should be rotated.  Positive values will rotate clockwise, negative values will rotate counterclockwise.
@@ -1323,6 +1340,7 @@ Properties:
     - Default is `0 0.38375`
 * `origin` - type: NORMALIZED_PAIR
     - Where on the carousel `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the carousel exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
 * `color` - type: COLOR
     - Color of the carousel background panel. Setting a value of `00000000` makes the background panel transparent.
     - Default is `FFFFFFD8`
@@ -1401,6 +1419,7 @@ Properties:
 * `size` - type: NORMALIZED_PAIR
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to.  For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place the element exactly in the middle of the screen.  If the position and size attributes are themeable, origin is implied.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
 * `selectorHeight` - type: FLOAT
     - Height of the "selector bar".
 * `selectorOffsetY` - type: FLOAT
@@ -1446,7 +1465,7 @@ Properties:
 
 #### gameselector
 
-Selects games from the gamelists when navigating the `system` view. This makes it possible to display game media and game metadata directly from this view. It's possible to make separate gameselector configurations per game system, so that for instance a random game could be displayed for one system and the most recently played game could be displayed for another system. It's also possible to define multiple gameselector elements with different selection criterias per game system which makes it possible to for example set a random fan art background image and at the same time display a box cover image of the most recently played game. The gameselector logic can be used for the `image` and `text` elements.
+Selects games from the gamelists when navigating the `system` view. This makes it possible to display game media and game metadata directly from this view. It's possible to make separate gameselector configurations per game system, so that for instance a random game could be displayed for one system and the most recently played game could be displayed for another system. It's also possible to define multiple gameselector elements with different selection criterias per game system which makes it possible to for example set a random fan art background image and at the same time display a box cover image of the most recently played game. The gameselector logic can be used for the `image`, `video`, `text` and `datetime` elements.
 
 Supported views:
 * `system`
@@ -1481,6 +1500,7 @@ Properties:
 * `origin` - type: NORMALIZED_PAIR
     - Where on the element `pos` refers to. For example, an origin of `0.5 0.5` and a `pos` of `0.5 0.5` would place
       the element exactly in the middle of the screen.
+    - Minimum value per axis is `0` and maximum value per axis is `1`
 * `textColor` - type: COLOR
     - Default is `777777FF`
 * `textColorDimmed` - type: COLOR

USERGUIDE-DEV.md

@@ -150,6 +150,29 @@ There will be a lot of directories created if using the es_systems.xml file bund
 ![alt text](images/es-de_ui_easy_setup.png "ES-DE Easy Setup")
 _This is the dialog shown if no game files were found. It lets you configure the ROM directory if you don't want to use the default one, and you can also generate the game systems directory structure. Note that the directory is the physical path, and that your operating system may present this as a localized path if you are using a language other than English._
 
+## Placing games into non-standard directories
+
+As explained above, the basic logic for how ES-DE works is that it expects game files to be placed into a standardized directory structure under the ROMs directory. The location of this directory is configurable so it could for instance be placed on an external storage device or on a file share served by a NAS. The way it's implemented is via the %ROMPATH% variable in the es_systems.xml file which will always point to this ROM directory. For example this is an entry for the Super Nintendo system:
+```
+<path>%ROMPATH%/snes</path>
+```
+
+In theory it's possible to make a custom system entry and hardcode the path to a specific directory instead of using the %ROMPATH% variable, but this is not really supported and it also makes custom collections non-portable as the path to every game will be an absolute path rather than a path relative to the %ROMPATH% variable. So if you move your games to a different directory, you would manually need to modify all your custom collections configuration files as well as your custom es_systems.xml file.
+
+If you really insist on not placing your games into the ES-DE standard directory structure, a much better solution is to symlink the game directories into the standard directory. In this way you don't need to make a custom es_systems.xml file and any additional emulators and other configuration added to future ES-DE releases will just work after upgrading.
+
+This is an example of symlinking the Super Nintendo game directory on Unix and macOS:
+```
+cd ~/ROMs
+ln -s ~/my_games/super_nintendo/ snes
+```
+
+And on Windows (you need to run this as Administrator):
+```
+cd C:\Users\Myusername\ROMs
+mklink /D snes "C:\My Games\Super Nintendo\"
+```
+
 ## Disabling game systems
 
 The way ES-DE works is that it will always try to load any system for which there are game files available, so to disable a system it needs to be hidden from ES-DE. This is easily accomplished by renaming the game directory to something that is not recognized, for example changing `~/ROMs/c64` to `~/ROMs/c64_DISABLED`. Another approach is to create a subdirectory named DISABLED (or whatever name you prefer that is not matching a supported system) in the ROMs directory and move the game folder there, such as `~/ROMs/DISABLED/c64`. This makes it easy to disable and re-enable game systems in ES-DE. Note that the gamelist.xml file and any game media files are retained while the system is disabled so this is an entirely safe thing to do.
@@ -1081,7 +1104,7 @@ Images of cartridges, diskettes, tapes, CD-ROMs etc. that were used to distribut
 
 **Fan art images**
 
-Fan art. Disabled by default as not everyone may want these images, and because they slow down the scraping.
+Fan art. These can get quite large so if you don't need them then disable this option to speed up the scraping process.
 
 #### Miximage settings
 
@@ -1303,10 +1326,6 @@ If enabled, it's possible to navigate between gamelists using the _Left_ and _Ri
 
 Activates or deactivates the built-in help system that provides contextual information regarding button usage.
 
-**Play videos immediately (override theme)**
-
-Some themes (including rbsimple-DE) display the game images briefly before playing the game videos. This setting forces the videos to be played immediately, regardless of the configuration in the theme. Note though that if there is a video available for a game, but no images, the video will always start to play immediately no matter the theme configuration or whether this settings has been enabled or not.
-
 #### Media viewer settings
 
 Settings for the media viewer that is accessible from the gamelist views.
@@ -1419,9 +1438,9 @@ Sets the volume for the navigation sounds.
 
 Sets the volume for the video player. This applies to the gamelist view, the media viewer and the video screensaver.
 
-**Play audio for videos in the gamelist view**
+**Play audio for gamelist and system view videos**
 
-With this turned off, audio won't play for videos in the gamelists.
+With this turned off, audio won't play for videos in the gamelist or system views. Note that even with this option enabled videos may be muted as the audio can be disabled per video element from the theme configuration.
 
 **Play audio for media viewer videos**
 
@@ -1473,7 +1492,7 @@ If the theme set in use provides themes for custom collections, then this entry
 
 **Create new custom collection**
 
-This lets you create a completely custom collection with a name of your choice.
+This lets you create a completely custom collection with a name of your choice. If the selected name collides with an existing name, a sequence number inside brackets will be appended to the collection name, such as _fighting (1)_ if a _fighting_ collection already existed. Note that custom collection names are always converted to lowercase.
 
 **Delete custom collection**