docs(ui): add scallers documentation to sample

CHANGELOG.md

@@ -25,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Console plugin (#875, **@Scarface1809**).
 - Friction calculation for penetration constraint (#1244, **@fallenatlas**).
 - Bounciness calculation for penetration constraint (#1275, **@fallenatlas**).
+- UI scalling modes. (#1284, **@DiogoMendonc-a**)
 
 ### Changed
 

engine/samples/ui/assets/input.bind

@@ -0,0 +1,21 @@
+{
+    "actions": {
+        "set_stretch": [
+            {"keys": ["Num1"]}
+        ],
+        "set_keep_pixel_size": [
+            {"keys": ["Num2"]}
+        ],
+        "set_match_width": [
+            {"keys": ["Num3"]}
+        ],
+        "set_match_height": [
+            {"keys": ["Num4"]}
+        ],
+        "set_expand": [
+            {"keys": ["Num5"]}
+        ]
+    },
+    "axes": {
+    }
+}

engine/samples/ui/assets/input.bind.meta

@@ -0,0 +1,3 @@
+{
+    "id": "fd242bc2-ebb4-4287-b015-56876b355810"
+}

engine/samples/ui/main.cpp

@@ -1,5 +1,6 @@
 #include <cubos/engine/assets/plugin.hpp>
 #include <cubos/engine/image/plugin.hpp>
+#include <cubos/engine/input/plugin.hpp>
 #include <cubos/engine/prelude.hpp>
 #include <cubos/engine/render/shader/plugin.hpp>
 #include <cubos/engine/render/target/plugin.hpp>
@@ -9,7 +10,11 @@
 #include <cubos/engine/transform/plugin.hpp>
 #include <cubos/engine/ui/canvas/canvas.hpp>
 #include <cubos/engine/ui/canvas/element.hpp>
+#include <cubos/engine/ui/canvas/expand.hpp>
 #include <cubos/engine/ui/canvas/horizontal_stretch.hpp>
+#include <cubos/engine/ui/canvas/keep_pixel_size.hpp>
+#include <cubos/engine/ui/canvas/match_height.hpp>
+#include <cubos/engine/ui/canvas/match_width.hpp>
 #include <cubos/engine/ui/canvas/native_aspect_ratio.hpp>
 #include <cubos/engine/ui/canvas/plugin.hpp>
 #include <cubos/engine/ui/canvas/vertical_stretch.hpp>
@@ -21,13 +26,16 @@
 
 using namespace cubos::engine;
 
+static const Asset<InputBindings> BindingsAsset = AnyAsset("fd242bc2-ebb4-4287-b015-56876b355810");
+
 int main(int argc, char** argv)
 {
     Cubos cubos{argc, argv};
 
     cubos.plugin(settingsPlugin);
     cubos.plugin(windowPlugin);
     cubos.plugin(assetsPlugin);
+    cubos.plugin(inputPlugin);
     cubos.plugin(renderTargetPlugin);
     cubos.plugin(shaderPlugin);
     cubos.plugin(transformPlugin);
@@ -36,6 +44,13 @@ int main(int argc, char** argv)
     cubos.plugin(uiImagePlugin);
     cubos.plugin(colorRectPlugin);
 
+    cubos.startupSystem("load and set the Input Bindings")
+        .tagged(assetsTag)
+        .call([](const Assets& assets, Input& input) {
+            auto bindings = assets.read<InputBindings>(BindingsAsset);
+            input.bind(*bindings);
+        });
+
     cubos.startupSystem("configure Assets").tagged(settingsTag).call([](Settings& settings) {
         settings.setString("assets.io.path", SAMPLE_ASSETS_FOLDER);
     });
@@ -81,5 +96,58 @@ int main(int argc, char** argv)
         /// [Set up Long Logo]
     });
 
+    cubos.system("change scale mode").call([](Commands cmds, const Input& input, Query<Entity, UICanvas&> query) {
+        if (input.pressed("set_stretch"))
+        {
+            for (auto [entity, _] : query)
+            {
+                cmds.remove<UIKeepPixelSize>(entity);
+                cmds.remove<UIMatchHeight>(entity);
+                cmds.remove<UIMatchWidth>(entity);
+                cmds.remove<UIExpand>(entity);
+            }
+        }
+        if (input.pressed("set_keep_pixel_size"))
+        {
+            for (auto [entity, _] : query)
+            {
+                cmds.add(entity, UIKeepPixelSize{});
+                cmds.remove<UIMatchHeight>(entity);
+                cmds.remove<UIMatchWidth>(entity);
+                cmds.remove<UIExpand>(entity);
+            }
+        }
+        if (input.pressed("set_match_width"))
+        {
+            for (auto [entity, _] : query)
+            {
+                cmds.add(entity, UIMatchWidth{});
+                cmds.remove<UIKeepPixelSize>(entity);
+                cmds.remove<UIMatchHeight>(entity);
+                cmds.remove<UIExpand>(entity);
+            }
+        }
+        if (input.pressed("set_match_height"))
+        {
+            for (auto [entity, _] : query)
+            {
+                cmds.add(entity, UIMatchHeight{});
+                cmds.remove<UIKeepPixelSize>(entity);
+                cmds.remove<UIMatchWidth>(entity);
+                cmds.remove<UIExpand>(entity);
+            }
+        }
+        if (input.pressed("set_expand"))
+        {
+            for (auto [entity, _] : query)
+            {
+                cmds.add(entity, UIExpand{});
+                cmds.remove<UIKeepPixelSize>(entity);
+                cmds.remove<UIMatchHeight>(entity);
+                cmds.remove<UIMatchWidth>(entity);
+            }
+        }
+    });
+
     cubos.run();
 }

engine/samples/ui/page.md

@@ -43,5 +43,16 @@ For this we will the use the extended version of our logo, which is rectangular.
 
 @note The @ref cubos::engine::UINativeAspectRatio is transformative. If you desire to keep the original size of the element information for other uses, it might be best to have the image instead be on a child entity of that element, and use both @ref cubos::engine::UIHorizontalStretch and @ref cubos::engine::UIVerticalStretch to achieve the same effect.
 
+![](ui_output.png)
 
-![](ui_output.png)
+Another important thing to keep in mind while building the UI is how it is going to adapt to different resolutions and aspect ratios.
+
+You can do this by using a set of components that when added to an entity with a UICanvas will change how it handles these differences. In this sample, you can change which is being used by pressing the shortcut numbers in the first collumn. All these components are meant to be used exclusively, meaning that no more than one should be present in one entity.
+
+| Shortcut | Mode            | Component                                                         | Description                                                                                                       |
+|----------|-----------------|-------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|
+| 1        | Stretch         | None - Canvas defaults to this when no other component is present | Canvas is stretch to fit the window. Will warp elements.                                                          |
+| 2        | Keep Pixel Size | @ref cubos::engine::UIKeepPixelSize "UIKeepPixelSize"                                   | Distances to anchors are constant. Might cause overlap between elements with different anchors.                   |
+| 3        | Match Height    | @ref cubos::engine::UIMatchHeight "UIMatchHeight"                                     | Vertical proportions are kept. Width is adjusted to keep each element's aspect ratio.                             |
+| 4        | Match Width     | @ref cubos::engine::UIMatchWidth "UIMatchWidth"                                      | Horizontal proportions are kept. Height is adjusted to keep each element's aspect ratio.                          |
+| 5        | Expand          | @ref cubos::engine::UIExpand "UIExpand"                                          | Switches between matching height or matching width, depending on which will cause the elements to reduce in size. |