Several changes related to VRAM usage and GPU statistics.

INSTALL.md

@@ -15,7 +15,7 @@ There are much more details regarding compilers later in this document, so read
 Any code editor can be used of course, but I recommend [VSCodium](https://vscodium.com) or [VSCode](https://code.visualstudio.com).
 
 
-## Building on Unix:
+## Building on Unix
 
 The code has a few dependencies. For building, you'll need CMake and development packages for cURL, FreeImage, FreeType, libVLC, pugixml, SDL2 and RapidJSON.
 
@@ -198,7 +198,7 @@ sudo apt-get install rpm
 ```
 
 
-## Building on Windows:
+## Building on Windows
 
 This is a strange legacy operating system. However it's still popular, so we need to support it.
 
@@ -484,7 +484,7 @@ You now have a fully functional portable emulator installation!
 The portable installation works exactly as a normal installation, i.e. you can use the built-in scraper, edit metadata etc.
 
 
-## Configuring EmulationStation-DE
+## Configuration
 
 **~/.emulationstation/es_systems.cfg:**
 
@@ -552,7 +552,7 @@ The new configuration will be added to the `~/.emulationstation/es_input.cfg` fi
 
 You can use `--help` or `-h` to view a list of command line options, as shown here.
 
-### Unix:
+### Unix
 
 ```
 --resolution [width] [height]   Try to force a particular resolution
@@ -560,7 +560,6 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
 --ignore-gamelist               Ignore the gamelist files (useful for troubleshooting)
 --show-hidden-files             Show hidden files and folders
 --show-hidden-games             Show hidden games
---draw-framerate                Display the framerate
 --no-exit                       Don't show the exit option in the menu
 --no-splash                     Don't show the splash screen
 --debug                         Print debug information
@@ -568,8 +567,8 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
 --fullscreen-normal             Normal fullscreen mode
 --fullscreen-borderless         Borderless fullscreen mode (always on top)
 --vsync [1/on or 0/off]         Turn vsync on or off (default is on)
---max-vram [size]               Max VRAM to use in Mb before swapping
+--max-vram [size]               Max VRAM to use (in mebibytes) before swapping
-                                Set to at least 20 to avoid unpredictable behavior
+--gpu-statistics                Draw framerate and VRAM usage overlay
 --force-full                    Force the UI mode to Full
 --force-kid                     Force the UI mode to Kid
 --force-kiosk                   Force the UI mode to Kiosk
@@ -580,7 +579,7 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
 --help, -h                      Summon a sentient, angry tuba
 ```
 
-### Windows:
+### Windows
 
 ```
 --resolution [width] [height]   Try to force a particular resolution
@@ -588,13 +587,12 @@ You can use `--help` or `-h` to view a list of command line options, as shown he
 --ignore-gamelist               Ignore the gamelist files (useful for troubleshooting)
 --show-hidden-files             Show hidden files and folders
 --show-hidden-games             Show hidden games
---draw-framerate                Display the framerate
 --no-exit                       Don't show the exit option in the menu
 --no-splash                     Don't show the splash screen
 --debug                         Print debug information
 --vsync [1/on or 0/off]         Turn vsync on or off (default is on)
---max-vram [size]               Max VRAM to use in Mb before swapping
+--max-vram [size]               Max VRAM to use (in mebibytes) before swapping
-                                Set to at least 20 to avoid unpredictable behavior
+--gpu-statistics                Draw framerate and VRAM usage overlay
 --force-full                    Force the UI mode to Full
 --force-kid                     Force the UI mode to Kid
 --force-kiosk                   Force the UI mode to Kiosk
@@ -745,7 +743,7 @@ There are a few types of metadata:
 
 Some metadata is also marked as "statistic" - these are kept track of by ES and do not show up in the metadata editor. They are shown in certain views (for example, the detailed view and the video view both show `lastplayed`, although the label can be disabled by the theme).
 
-### `<game>`
+**\<game\>**
 
 * `name` - string, the displayed name for the game.
 * `desc` - string, a description of the game.  Longer descriptions will automatically scroll, so don't worry about size.
@@ -764,7 +762,7 @@ Some metadata is also marked as "statistic" - these are kept track of by ES and
 * `sortname` - string, used in sorting the gamelist in a system, instead of `name`.
 * `launchcommand` - optional tag that is used to override the emulator and core settings on a per-game basis.
 
-### `<folder>`
+**\<folder\>**
 * `name` - string, the displayed name for the folder.
 * `desc` - string, the description for the folder.
 * `developer` - string, developer(s).

USERGUIDE.md

@@ -190,7 +190,7 @@ Last Ninja 2 (Disk 1 of 2).d64
 Last Ninja 2 (Disk 2 of 2).d64
 ```
 
-It's of course also possible to skip this type of directory structure and put all the games in the root folder, but then there will be multiple entries for the same game which is not so tidy.
+It's of course also possible to skip this type of directory structure and put all the games in the root folder, but then there will be multiple entries for the same game which is not so tidy. Another approach would be to put all the files in the root folder and the hide the game files, showing only the .m3u playlist. But it's probably quite confusing to start a game that looks like a single-disk game and then be prompted for disk swaps by the emulator.
 
 When setting up games in this fashion, it's recommended to scrape the directory in addition to the .m3u file as it looks nicer to see images and metadata for the games also when browsing the folders. ES fully supports scraping folders, although some metadata is not included for folders for logical reasons. If you only scrape the folders and not the actual game files, it looks ok when browsing, but when a game is part of a collection, the metadata and images will be missing there. This includes the **Last played** and **All games** collections for instance. Also note that while it's possible to mark a folder as a favorite, it will never be part of a collection, such as **Favorites**.
 
@@ -662,7 +662,7 @@ These are mostly technical settings.
 
 **VRAM limit**
 
-The amount of video RAM to use for the application. Defaults to 100 MB which seems to work fine most of the time. Don't put it too low or you may see strange application behavior.
+The amount of video RAM to use for the application. Defaults to 160 MiB which seems to work fine most of the time. The allowed range is 80 to 1000 MiB. If you try to set it lower or higher than this by passing such values as command line parameters or edit the es_settings.cfg file manually, ES will log a warning and automatically adjust the value within the allowable range.
 
 **Fullscreen mode (requires restart) - Unix only**
 
@@ -704,9 +704,9 @@ If enabled, only ROMs that have metadata saved to the gamelist.xml files will be
 
 Using this option, you can locate game images in the ROM directory tree. The images are searched inside the directory "\<ROM directory\>/\<system name\>/images/" and the filenames must be the same as the ROM names, followed by a dash and the image type. For example "~/ROMs/nes/images/Contra-screenshot.jpg" and "~/ROMs/nes/images/Contra-marquee.jpg". This option is mostly intended for legacy purposes, if you have an existing game collection with this media setup that you would like to open in ES. The scraper will never save files to this directory structure and will instead use the standard media directory logic. It's recommended to keep this option disabled unless you really need it since it slows down the application somewhat.
 
-**Show framerate**
+**Draw GPU statistics overlay**
 
-Shows the framerate and some other statistics as an overlay. You normally never need to use this.
+Draws the framerate and VRAM statistics as an overlay. You normally never need to use this.
 
 **Show "reboot system" menu entry**
 
@@ -838,6 +838,10 @@ A flag to indicate whether the game should be excluded from being counted. It's
 
 Whether to exclude the file from the multi-scraper. This is quite useful in order to avoid scraping all the disks for multi-disk games for example. There is an option in the scraper settings to ignore this flag, but by default the scraper will respect it. Note that the manual single-file scraper will work regardless of whether this flag is set or not.
 
+**Hide metadata fields**
+
+This option will hide most metadata fields in the gamelist view. The intention is to be able to hide the fields for situations such as general folders (Multi-disk, Cartridges etc.) and configuration files and similar (e.g. SETUP.EXE or INSTALL.BAT for DOS games). It could also be used on the game files for multi-disk games where perhaps only the .m3u playlist should have any metadata values. The only fields shown with this option enabled are the game name and description. Using the description it's possible to write some comments regarding the file or folder, should you want to. It's still possible to display game images and videos with this setting enabled.
+
 **Launch command**
 
 Here you can override the launch command for the game, for example to use a different emulator than the default for the game system. Very useful for MAME/arcade games.
@@ -965,7 +969,6 @@ You can use **--help** or **-h** to view a list of command line options, as show
 --ignore-gamelist               Ignore the gamelist files (useful for troubleshooting)
 --show-hidden-files             Show hidden files and folders
 --show-hidden-games             Show hidden games
---draw-framerate                Display the framerate
 --no-exit                       Don't show the exit option in the menu
 --no-splash                     Don't show the splash screen
 --debug                         Print debug information
@@ -973,8 +976,8 @@ You can use **--help** or **-h** to view a list of command line options, as show
 --fullscreen-normal             Normal fullscreen mode
 --fullscreen-borderless         Borderless fullscreen mode (always on top)
 --vsync [1/on or 0/off]         Turn vsync on or off (default is on)
---max-vram [size]               Max VRAM to use in Mb before swapping
+--max-vram [size]               Max VRAM to use (in mebibytes) before swapping
-                                Set to at least 20 to avoid unpredictable behavior
+--gpu-statistics                Draw framerate and VRAM usage overlay
 --force-full                    Force the UI mode to Full
 --force-kid                     Force the UI mode to Kid
 --force-kiosk                   Force the UI mode to Kiosk
@@ -993,13 +996,12 @@ You can use **--help** or **-h** to view a list of command line options, as show
 --ignore-gamelist               Ignore the gamelist files (useful for troubleshooting)
 --show-hidden-files             Show hidden files and folders
 --show-hidden-games             Show hidden games
---draw-framerate                Display the framerate
 --no-exit                       Don't show the exit option in the menu
 --no-splash                     Don't show the splash screen
 --debug                         Print debug information
 --vsync [1/on or 0/off]         Turn vsync on or off (default is on)
---max-vram [size]               Max VRAM to use in Mb before swapping
+--max-vram [size]               Max VRAM to use (in mebibytes) before swapping
-                                Set to at least 20 to avoid unpredictable behavior
+--gpu-statistics                Draw framerate and VRAM usage overlay
 --force-full                    Force the UI mode to Full
 --force-kid                     Force the UI mode to Kid
 --force-kiosk                   Force the UI mode to Kiosk

es-app/src/guis/GuiMenu.cpp

@@ -502,7 +502,7 @@ void GuiMenu::openOtherSettings()
     auto s = new GuiSettings(mWindow, "OTHER SETTINGS");
 
     // Maximum VRAM.
-    auto max_vram = std::make_shared<SliderComponent>(mWindow, 0.f, 1000.f, 10.f, "Mb");
+    auto max_vram = std::make_shared<SliderComponent>(mWindow, 80.f, 1000.f, 10.f, "MiB");
     max_vram->setValue((float)(Settings::getInstance()->getInt("MaxVRAM")));
     s->addWithLabel("VRAM LIMIT", max_vram);
     s->addSaveFunc([max_vram] { Settings::getInstance()->setInt("MaxVRAM",
@@ -676,12 +676,12 @@ void GuiMenu::openOtherSettings()
     s->addSaveFunc([local_art] { Settings::getInstance()->
             setBool("LocalArt", local_art->getState()); });
 
-    // Framerate.
+    // GPU statistics.
-    auto framerate = std::make_shared<SwitchComponent>(mWindow);
+    auto gpu_statistics = std::make_shared<SwitchComponent>(mWindow);
-    framerate->setState(Settings::getInstance()->getBool("DrawFramerate"));
+    gpu_statistics->setState(Settings::getInstance()->getBool("DrawGPUStatistics"));
-    s->addWithLabel("SHOW FRAMERATE", framerate);
+    s->addWithLabel("DRAW GPU STATISTICS OVERLAY", gpu_statistics);
-    s->addSaveFunc([framerate] { Settings::getInstance()->setBool("DrawFramerate",
+    s->addSaveFunc([gpu_statistics] { Settings::getInstance()->setBool("DrawGPUStatistics",
-            framerate->getState()); });
+            gpu_statistics->getState()); });
 
     // Hide Reboot System option in the quit menu.
     auto show_rebootsystem = std::make_shared<SwitchComponent>(mWindow);

es-app/src/main.cpp

@@ -242,9 +242,6 @@ bool parseArgs(int argc, char* argv[])
         else if (strcmp(argv[i], "--show-hidden-games") == 0) {
             Settings::getInstance()->setBool("ShowHiddenGames", true);
         }
-        else if (strcmp(argv[i], "--draw-framerate") == 0) {
-            Settings::getInstance()->setBool("DrawFramerate", true);
-        }
         else if (strcmp(argv[i], "--no-exit") == 0) {
             Settings::getInstance()->setBool("ShowExit", false);
         }
@@ -273,6 +270,9 @@ bool parseArgs(int argc, char* argv[])
             Settings::getInstance()->setBool("VSync", vsync);
             i++; // Skip vsync value.
         }
+        else if (strcmp(argv[i], "--gpu-statistics") == 0) {
+            Settings::getInstance()->setBool("DrawGPUStatistics", "true");
+        }
         else if (strcmp(argv[i], "--force-full") == 0) {
             Settings::getInstance()->setString("UIMode", "full");
         }
@@ -303,7 +303,6 @@ bool parseArgs(int argc, char* argv[])
 "  --ignore-gamelist               Ignore the gamelist files (useful for troubleshooting)\n"
 "  --show-hidden-files             Show hidden files and folders\n"
 "  --show-hidden-games             Show hidden games\n"
-"  --draw-framerate                Display the framerate\n"
 "  --no-exit                       Don't show the exit option in the menu\n"
 "  --no-splash                     Don't show the splash screen\n"
 "  --debug                         Print debug information\n"
@@ -313,8 +312,8 @@ bool parseArgs(int argc, char* argv[])
 "  --fullscreen-borderless         Borderless fullscreen mode (always on top)\n"
 #endif
 "  --vsync [1/on or 0/off]         Turn vsync on or off (default is on)\n"
-"  --max-vram [size]               Max VRAM to use in Mb before swapping\n"
+"  --max-vram [size]               Max VRAM to use (in mebibytes) before swapping\n"
-"                                  Set to at least 20 to avoid unpredictable behavior\n"
+"  --gpu-statistics                Draw framerate and VRAM usage overlay\n"
 "  --force-full                    Force the UI mode to Full\n"
 "  --force-kid                     Force the UI mode to Kid\n"
 "  --force-kiosk                   Force the UI mode to Kiosk\n"

es-core/src/Settings.cpp

@@ -170,7 +170,7 @@ void Settings::setDefaults()
     #ifdef _RPI_
         mIntMap["MaxVRAM"] = 80;
     #else
-        mIntMap["MaxVRAM"] = 100;
+        mIntMap["MaxVRAM"] = 160;
     #endif
     #ifdef __unix__
     mStringMap["FullscreenMode"] = "normal";
@@ -204,7 +204,7 @@ void Settings::setDefaults()
     mBoolMap["LocalArt"] = false;
     mBoolMap["ShowHiddenFiles"] = true;
     mBoolMap["ShowHiddenGames"] = true;
-    mBoolMap["DrawFramerate"] = false;
+    mBoolMap["DrawGPUStatistics"] = false;
     mBoolMap["ShowRebootSystem"] = true;
     mBoolMap["ShowPoweroffSystem"] = true;
 

es-core/src/Window.cpp

@@ -207,7 +207,7 @@ void Window::update(int deltaTime)
     if (mFrameTimeElapsed > 500) {
         mAverageDeltaTime = mFrameTimeElapsed / mFrameCountElapsed;
 
-        if (Settings::getInstance()->getBool("DrawFramerate")) {
+        if (Settings::getInstance()->getBool("DrawGPUStatistics")) {
             std::stringstream ss;
 
             // FPS.
@@ -221,8 +221,8 @@ void Window::update(int deltaTime)
             float textureTotalUsageMb = TextureResource::getTotalTextureSize() / 1000.0f / 1000.0f;
             float fontVramUsageMb = Font::getTotalMemUsage() / 1000.0f / 1000.0f;
 
-            ss << "\nFont VRAM: " << fontVramUsageMb << " Tex VRAM: " << textureVramUsageMb <<
+            ss << "\nFont VRAM: " << fontVramUsageMb << "  Texture VRAM: " << textureVramUsageMb <<
-                    " Tex Max: " << textureTotalUsageMb;
+                    "  (Max Texture VRAM: " << textureTotalUsageMb << ")";
             mFrameDataText = std::unique_ptr<TextCache>
                     (mDefaultFonts.at(1)->buildTextCache(ss.str(), 50.f, 50.f, 0xFF00FFFF));
         }
@@ -262,8 +262,7 @@ void Window::render()
     if (!mRenderedHelpPrompts)
         mHelp->render(transform);
 
-    if (Settings::getInstance()->getBool("DrawFramerate") && mFrameDataText)
+    if (Settings::getInstance()->getBool("DrawGPUStatistics") && mFrameDataText) {
-    {
         Renderer::setMatrix(Transform4x4f::Identity());
         mDefaultFonts.at(1)->renderTextCache(mFrameDataText.get());
     }

es-core/src/resources/TextureDataManager.cpp

@@ -8,6 +8,7 @@
 
 #include "resources/TextureData.h"
 #include "resources/TextureResource.h"
+#include "Log.h"
 #include "Settings.h"
 
 TextureDataManager::TextureDataManager()
@@ -110,7 +111,22 @@ void TextureDataManager::load(std::shared_ptr<TextureData> tex, bool block)
         return;
     // Not loaded. Make sure there is room.
     size_t size = TextureResource::getTotalMemUsage();
-    size_t max_texture = (size_t)Settings::getInstance()->getInt("MaxVRAM") * 1024 * 1024;
+    size_t settingVRAM = (size_t)Settings::getInstance()->getInt("MaxVRAM");
+
+    if (settingVRAM < 80) {
+        LOG(LogWarning) << "MaxVRAM set too low at " << settingVRAM << " MiB, setting it to the "
+                "minimum value of 80 MiB.";
+        Settings::getInstance()->setInt("MaxVRAM", 80);
+        settingVRAM = 80;
+    }
+    else if (settingVRAM > 1000) {
+        LOG(LogWarning) << "MaxVRAM set too high at " << settingVRAM << " MiB, setting it to the "
+                "maximum value of 1000 MiB.";
+        Settings::getInstance()->setInt("MaxVRAM", 1000);
+        settingVRAM = 1000;
+    }
+
+    size_t max_texture = settingVRAM * 1024 * 1024;
 
     for (auto it = mTextures.crbegin(); it != mTextures.crend(); ++it) {
         if (size < max_texture)

es-core/src/resources/TextureResource.cpp

@@ -12,7 +12,7 @@
 TextureDataManager TextureResource::sTextureDataManager;
 std::map< TextureResource::TextureKeyType,
         std::weak_ptr<TextureResource>> TextureResource::sTextureMap;
-std::set<TextureResource*> 	TextureResource::sAllTextures;
+std::set<TextureResource*> TextureResource::sAllTextures;
 
 TextureResource::TextureResource(
         const std::string& path,
@@ -45,8 +45,10 @@ TextureResource::TextureResource(
     }
     else {
         // Create a texture managed by this class because it cannot be dynamically
-        // loaded and unloaded.
+        // loaded and unloaded. This would normally be a video texture, where the player
+        // reserves a texture to later be used for the video rendering.
         mTextureData = std::shared_ptr<TextureData>(new TextureData(tile));
+        mSize = Vector2i(0, 0);
     }
     sAllTextures.insert(this);
 }