New layouts manual. Minified some images and updated toolbar image for GUI doc.

docs/en/manuals/gui-layouts.md

@@ -5,62 +5,74 @@ brief: Defold supports GUIs that automatically adapt to screen orientation chang
 
 # Layouts
 
-Defold supports GUIs that automatically adapt to screen orientation changes on mobile devices. Using this feature allows you to design GUIs that adapt to the orientation and aspect ratio of the screen. It is also possible to create layouts that match certain device models.
+Defold supports GUIs that automatically adapt to screen orientation changes on mobile devices. By using this feature you can design GUIs that adapt to the orientation and aspect ratio of a range of screen sizes. It is also possible to create layouts that match particular device models.
 
-## Display profiles
+## Creating display profiles
 
-Each project contains a `builtins/render/default.display_profiles` with two profiles:
+By default, the "game.project" settings specify that a built in display profiles settings file ("builtins/render/default.display_profiles") is used. The default profiles are "Landscape" (1280 pixels wide and 720 pixels high) and "Portrait" (720 pixels wide and 1280 pixels high). No device models are set on the profiles so they will match on any device.
 
-![Default display profiles](images/layouts/layouts_display_profiles.png)
+To create a new profiles settings file, either copy the one from the "builtins" folder or <kbd>right click</kbd> a suitable location in the *Assets* view and select <kbd>New... ▸ Display Profiles</kbd>. Give the new file a suitable name and click <kbd>Ok</kbd>.
 
-Landscape
-: 1280 pixels wide and 720 pixels high
+The editor now opens the new file for editing. Add new profiles by clicking the <kbd>+</kbd> in the *Profiles* list. For each profile, add a set of *qualifiers* for the profile:
 
-Portrait
-: 720 pixels wide and 1280 pixels high
+Width
+: The pixel width of the qualifier.
 
-Device models
-: None
+Height
+: The pixel height of the qualifier.
 
-The dynamic layout of GUIs works by matching display profiles qualifiers to the current width and height of the display that the game is running on and any device models specified as reported by `sys.get_sys_info()`.
+Device Models
+: A comma separated list of device models. The device model matches the start of the device model name, e.g. "iPhone10" will match "iPhone10,3". Note that the only platforms reporting a device model when calling `sys.get_sys_info()` is Android and iOS. Other platforms return an empty string and will therefore never pick a display profile that has a device model qualifier.
+
+![New display profiles](images/gui-layouts/new_profiles.png){srcset="images/gui-layouts/[email protected] 2x"}
+
+You also need to specify that the engine should use your new profiles. Open "game.project" and select the display profiles file in the *Display Profiles* setting under *display*:
+
+![Settings](images/gui-layouts/settings.png){srcset="images/gui-layouts/[email protected] 2x"}
 
 ::: sidenote
-The only platforms reporting a device model when calling `sys.get_sys_info()` is Android and iOS. Other platforms return an empty string.
+The current development app for iOS does not respect the *Dynamic Orientation* setting but will always change orientation dynamically.
 :::
 
-For devices with an aspect ratio of 16:9 these profiles are probably enough. Even if the actual physical dimensions of the screen are higher or lower, the engine will automatically select the a profile that is closest.
+If you want the engine to automatically switch between portrait and landscape layouts on device rotation, check the *Dynamic Orientation* box. The engine will dynamically select a matching layout and also change the selection if the device changes orientation.
 
-The device models qualifier is a comma separated string where a display profile can be targeted against one or more specific device models. Adding for example `"iPhone10"` to the device model qualifier means that the profile will only be eligible for selection for devices **starting with** that same string, for example `iPhone10,3` and `iPhone10,6`.
+## GUI layouts
 
-If you need to alter the default profiles, simply copy the built in file to a new place within your project or create a new file, then change the setting in `project.settings` so the engine knows which profiles-file to use:
+The current set of display profiled can be used to create layout variants of your GUI node setup. To add a new layout to a GUI scene, right-click the *Layouts* icon in the *Outline* view and select <kbd>Add ▸ Layout ▸ ...</kbd>:
 
-![Project settings](images/layouts/layouts_project_settings.png)
+![Add layout to scene](images/gui-layouts/add_layout.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-The project settings also allow you to enable *dynamic_orientation* which means that the engine will dynamically select a matching layout and also change the selection if the device changes orientation.
+When editing a GUI scene, all nodes are edited on a particular layout. The currently selected layout is indicated in the GUI scene layout dropdown in the toolbar. If no layout is chosen, the nodes are edited in the *Default* layout.
 
-::: sidenote
-The current development app for iOS does not respect the *dynamic_orientation* setting but will always change orientation dynamically.
-:::
+![Layouts toolbar](images/gui-layouts/toolbar.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-## GUI layouts
+![portrait edit](images/gui-layouts/portrait.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-The defined display profiles can then be used to create layouts in the GUI editor. When working in the editor, a *Default* layout is used by default. If you have not added any additional layout(s), the default layout will be used. To add a new layout, right-click the *Layouts* icon in the *Outline* view and select the <kbd>Layout ▸ ...</kbd> menu item:
+Each change to a node property that you do with a layout selected _overrides_ the property in respect to the *Default* layout. Properties that are overridden are marked in blue. Nodes with overridden properties are also marked in blue. You can click on the reset button next to any overridden property to reset it to the original value.
 
-![Add layout to scene](images/layouts/layouts_add.png)
+![landscape edit](images/gui-layouts/landscape.png){srcset="images/gui-layouts/[email protected] 2x"}
 
-::: sidenote
-The *Default* layout is only used if there are no other layouts added to the GUI scene. So, if you add a "Landscape" layout, that will be the best match for all orientations until you also add a "Portrait" layout.
-:::
+A layout cannot delete or create new nodes, only override properties. If you need to remove a node from a layout you can either move the node off-screen or delete it with script logic. You should also pay attention to the currently selected layout. If you add a layout to your project, the new layout will be set up according to the currently selected layout. Also, copying and pasting nodes considers the currently selected layout, when copying *and* when pasting.
 
-When editing a GUI scene, all nodes are edited on a particular layout. The currently selected layout is indicated in the gui scene layout dropdown.
+## Dynamic profile selection
 
-![Editing default layout](images/layouts/layouts_default.png)
+The dynamic layout matcher scores each display profile qualifier according to the following rules:
 
-You also get visual feedback on whether a node overrides a property on the currently selected layout (other than *Default*) or not. Each change to a node property that you do with a layout selected _overrides_ the property in respect to the *Default* layout. Properties that are overridden are marked in blue. You can click on the reset button next to the property to reset the property to the default value.
+1. If there is no device model set, or the device model matches, a score $S$ is calculated for the qualifier.
 
-![Editing with layouts](images/layouts/layouts_modified.png)
+2. The score ($S$) is calculated with the area of the display ($A$), the area from the qualifier ($A_Q$), the aspect ratio of the display ($R$) and the aspect ratio of the qualifier ($R_Q$):
 
-Note that layouts only override properties. A layout cannot delete or create new nodes. If you need to remove a node from a layout you can either move the node off-screen or delete it with script logic. You should also pay attention to the currently selected layout. If you add a layout to your project, the new layout will be set up according to the currently selected layout. Also, copying and pasting nodes considers the currently selected layout, when copying *and* when pasting.
+   $$
+   S=\left|1 - \frac{A}{A_Q}\right| + \left|1 - \frac{R}{R_Q}\right|
+   $$
+
+3. The profile with the lowest scoring qualifier is selected, if the orientation (landscape or portrait) of the qualifier matches the display.
+
+4. If no profile with a qualifier of the same orientation is found, the profile with the best scoring qualifier of the other orientation is selected.
+
+5. If no profile can be selected, the *Default* fallback profile is used.
+
+Since the *Default* layout is used as fallback in runtime if there are no better matching layout it means that if you add a "Landscape" layout, it will be the best match for *all* orientations until you also add a "Portrait" layout.
 
 ## Layout change messages
 
@@ -68,13 +80,11 @@ When the engine switches layout as a result of device rotation, a `layout_change
 
 ```lua
 function on_message(self, message_id, message, sender)
-    if message_id == hash("layout_changed") and message.id == hash("Landscape") then
-        -- switching layout to landscape
-    ...
-    elseif message_id == hash("layout_changed") and message.id == hash("Portrait") then
+  if message_id == hash("layout_changed") and message.id == hash("My Landscape") then
+    -- switching layout to landscape
+  elseif message_id == hash("layout_changed") and message.id == hash("My Portrait") then
     -- switching layout to portrait
-    ...
-    end
+  end
 end
 ```
 
@@ -82,19 +92,11 @@ In addition, the current render script receives a message whenever the window (g
 
 ```lua
 function on_message(self, message_id, message)
-    if message_id == hash("window_resized") then
-      -- The window was resized. message.width and message.height contain the
-      -- new dimensions of the window.
-    end
+  if message_id == hash("window_resized") then
+    -- The window was resized. message.width and message.height contain the
+    -- new dimensions of the window.
+  end
 end
 ```
 
-## In game content
-
-Note that when orientation is switched, the GUI layout manager will automatically rescale and reposition GUI nodes according to your layout and node properties. For in-game content, the view is rendered as is, by default stretch-fit into the current window.
-
-![Orientation rendering](images/layouts/layouts_orientation.png)
-
-If your game design puts specific contraints on how the game view should be rendered, you can change the render script and implement precisely the behavior you need, taking camera, viewport and whatnot into consideration.
-
-(Some of the graphic assets used are made by Kenney: http://kenney.nl/assets)
+When orientation is switched, the GUI layout manager will automatically rescale and reposition GUI nodes according to your layout and node properties. In-game content, however, is rendered in a separate pass (by default) with a stretch-fit projection into the current window. To change this behavior, either supply your own modified render script, or use a camera [library](/community/assets/).