Documentation update adding details for running on 4K displays.

INSTALL.md

@@ -1441,15 +1441,19 @@ For folders, most of the fields are identical although some are removed. In the
 
 There are numerous locations throughout ES-DE where custom scripts will be executed if the option to do so has been enabled in the settings. You'll find the option on the Main menu under `Other settings`. By default it's deactivated so be sure to enable it to use this feature.
 
-The approach is quite straightforward, ES-DE will look for any files inside a script directory that correspond to the event that is triggered and execute all files located there.
+The approach is quite straightforward, ES-DE will look for any files inside a script directory that corresponds to the event that is triggered and will then execute all these files.
 
-As an example, let's create a log that will record the start and end time for each game we play, letting us see how much time we spend on retro-gaming.
+We'll go through two examples:
+* Create a log file that will record the start and end time for each game we play, letting us see how much time we spend on retro-gaming
+* Change the system resolution when launching and returning from a game in order to run the emulator at a lower resolution than ES-DE
 
-**Note:** The following example is for Unix systems, but it works the same way in macOS (which is also Unix after all), and on Windows (although .bat batch files are then used instead of shell scripts and any spaces in the parameters are not escaped as is the case on Unix).
+**Note:** The following examples are for Unix systems, but it works the same way in macOS (which is also Unix after all), and on Windows (although .bat batch files are then used instead of shell scripts and any spaces in the parameters are not escaped as is the case on Unix).
 
-The events when the game starts and ends are called `game-start` and `game-end` respectively. Finding these event names is easily achieved by starting ES-DE with the `--debug` flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names.
+The events executed when a game starts and ends are called `game-start` and `game-end` respectively. Finding these event names is easily achieved by starting ES-DE with the `--debug` flag. If this is done, all attempts to execute custom event scripts will be logged to es_log.txt, including the event names.
 
-So let's create the folders for these events in the scripts directory. The location of this directory is `~/.emulationstation/scripts`.
+So let's create the folders for these events in the scripts directory. The location is `~/.emulationstation/scripts`
+
+**Game log:**
 
 After creating the directories, we need to create the scripts to log the actual game launch and game ending. The parameters that are passed to the scripts varies depending on the type of event, but for these events the two parameters are the absolute path to the game file, and the game name as shown in the gamelist view.
 
@@ -1499,4 +1503,35 @@ Starting game "Quake" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") a
 Ending game   "Quake" ("/home/myusername/ROMs/ports/Quakespasm/quakespasm.sh") at 2020-08-05 15:13:58
 Starting game "Pirates!" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:15:24
 Ending game   "Pirates!" ("/home/myusername/ROMs/c64/Multidisk/Pirates/Pirates!.m3u") at 2020-08-05 15:17:11
-```
+```
+
+**Resolution changes:**
+
+The same directories are used as for the above example with the game log.
+
+First create the game start script, let's name it `set_resolution_1080p.sh` with the following contents:
+
+```
+#!/bin/sh
+xrandr -s 1920x1080
+```
+
+Then create the end script, which we'll name `set_resolution_4K.sh`:
+
+```
+#!/bin/sh
+xrandr -s 3840x2160
+xdotool search --class emulationstation windowactivate
+xdotool search --class emulationstation windowactivate
+```
+
+The last two lines are optional, they're used to set the focus back to ES-DE in case you're running attention-seeking applications such as Kodi which seems to love to steal focus after resolution changes. Not sure why you need to run the command twice though, probably it's due to some kind of timing or race condition issue.
+
+After creating the two scripts, you should have something like this on the filesystem:
+
+```
+~/.emulationstation/scripts/game-start/set_resolution_1080p.sh
+~/.emulationstation/scripts/game-end/set_resolution_4K.sh
+```
+
+Don't forget to make the scripts executable (e.g. 'chmod 755 ./set_resolution_1080p.sh').

USERGUIDE.md

@@ -108,17 +108,9 @@ It's probably also a good idea to rename or move `es_settings.cfg` elsewhere as
 
 ## Running on 4K displays
 
-ES-DE fully supports 4K displays, but some emulators such as RetroArch will start with the same resolution as the calling program, meaning the emulation will also run in 4K. On slower computers and when resource intensive shaders are in use, the performance may be quite bad. A workaround for this is to start ES-DE with the `--resolution` option. For example, to set the resolution to 1920x1080 run the following:
+ES-DE fully supports 4K displays (as well as 1440p and other higher resolutions) but some emulators such as RetroArch will always run using the active screen resolution, meaning the emulation will also run in 4K. On slower computers and when resource intensive shaders are in use, the performance may be quite bad. Although it's possible to start ES-DE with the `--resolution` option (which also applies to any launched emulators), this is not really recommended. Full screen mode only works on Unix with this option and even then it's highly dependent on well-written graphics drivers for proper behavior. ES-DE uses the SDL library which insists on setting xrandr to panning mode when doing resolution changes, which is incredibly annoying especially when using Nvidia drivers.
 
-```
+A better approach is to use the custom event scripts functionality in ES-DE to set a temporary resolution upon launching a game that will be reverted when returning from the emulator. This is detailed as an example for Unix in [INSTALL.md](USERGUIDEmd#custom-event-scripts) but should be possible to implement similarly on other operating systems such as macOS and Windows.
-emulationstation --resolution 1920 1080
-```
-
-This can of course be set in the ES-DE launcher entry for the desktop environment so that the normal menu entry can be used.
-
-A drawback with this approach is that the complete system resolution will be switced temporarily, meaning alt-tab switching between application will display them also in this lower resolution. Upon exiting ES-DE the previous 4K resolution should however be restored. This seems to be somehow driver-dependent though as for example the proprietary Nvidia Linux drivers (as always) do not seem to behave properly but the AMD open source drivers apparently work fine. So testing is required to see if this approach of running the application at a lower resolution than the screen resolution is possible.
-
-This only works well for Unix/Linux at the moment as Windows and macOS will run in windowed mode due to technical limitations in these operating systems. There may be workarounds for the actual emulator as well that I'm not aware of, making it possible to force a specific resolution while still running ES-DE in 4K.
 
 
 ## Input device configuration
@@ -602,7 +594,7 @@ It's possible to change the game media directory from within ES-DE, for this see
 
 ## Main menu
 
-This menu can be accessed from both the system view and gamelist views. It contains the scraper, the input configuration tool and the application settings. Settings are saved when navigating back from any settings screen, assuming at least one setting was changed. Pressing F4 to quit the application will mean any settings changed on the current screen will NOT be saved to the configuration file.
+This menu can be accessed from both the system view and gamelist views. It contains the scraper, the input configuration tool and the application settings. Settings are saved when navigating back from any menu screen, assuming at least one setting was changed. Pressing F4 to quit the application will also save any pending changes.
 
 ![alt text](images/current/es-de_main_menu.png "ES-DE Main Menu")
 _The ES-DE main menu._