You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The *RmlUi Canvas 2D* component (`ezRmlUiCanvas2DComponent`) renders an [RmlUi](rmlui.md) document as a screen-space overlay. This is the standard choice for HUDs and menus.
4
4
5
-
The RML UI integration is in a good state, and building UIs is very much possible, however, the functionality is currently undocumented.
5
+
## Component Properties
6
+
7
+
### Base Properties
8
+
9
+
These properties are shared with the [RmlUI Canvas 3D Component](rmlui-canvas3d-component.md).
10
+
11
+
**Rml Resource:** The `.rml` document file to load and render.
12
+
13
+
**Autobind Blackboards:** When enabled, the component searches the owner object's hierarchy for a [blackboard](../misc/blackboards.md) component and binds it automatically. The blackboard's name is used as the RmlUi model name, making its entries accessible as RmlUi data model variables. You can also bind blackboards manually from C++ using `ezRmlUiCanvasComponentBase::AddBlackboardBinding()`. Both scalar values and [variant arrays](https://mikke89.github.io/RmlUiDoc/pages/data_bindings.html) stored in the blackboard are supported.
14
+
15
+
**Send Event Message:** When enabled, every RmlUi event (such as a button click) fires an `ezMsgRmlUiEvent` message on the component's owner object. The message carries:
16
+
17
+
*`m_sIdentifier` — the identifier string configured on the RmlUi element (e.g. via the `data-event-id` attribute or the event listener identifier).
18
+
*`m_sType` — the RmlUi event type (e.g. `click`, `change`).
19
+
20
+
This message can be handled in [visual scripts](../custom-code/visual-script/visual-script-overview.md) or C++ components attached to the same object, enabling script-driven UI logic without writing a custom C++ event handler. As an alternative, you can register C++ event handlers directly via `ezRmlUiContext::RegisterEventHandler()`.
21
+
22
+
**On Demand Update:** When enabled (the default), the canvas texture is only re-rendered when something has changed. Disable this to force a re-render every frame.
23
+
24
+
### 2D-Specific Properties
25
+
26
+
**Offset:** A 2D pixel offset (in screen pixels) applied to the canvas position. Combined with **Anchor Point**, this determines where on screen the canvas appears.
27
+
28
+
**Size:** The resolution of the RmlUi canvas in pixels. This also determines the canvas's logical coordinate space for RmlUi layout.
29
+
30
+
**Anchor Point:** A normalized (0–1) 2D value that controls which corner or point of the canvas is placed at the screen anchor. `(0, 0)` anchors the top-left corner; `(1, 1)` anchors the bottom-right corner.
31
+
32
+
**Pass Input:** When enabled, mouse and keyboard input is forwarded to the RmlUi context for interaction. Disable this to make the canvas non-interactive (display only).
33
+
34
+
**Custom Scale:** A scaling factor applied to the canvas. Useful for adapting to different screen densities or for visual effects. Defaults to `1.0`.
35
+
36
+
## Interaction
37
+
38
+
Input is forwarded automatically when **Pass Input** is enabled. For programmatic interaction, call `ReceiveInput()` with a canvas-space mouse position and an `ezRmlUiInputSnapshot`.
6
39
7
40
## See Also
8
41
9
42
*[RmlUi](rmlui.md)
43
+
*[RmlUI Canvas 3D Component](rmlui-canvas3d-component.md)
The *RmlUi Canvas 3D* component (`ezRmlUiCanvas3DComponent`) renders an [RmlUi](rmlui.md) document into a texture that is applied to a mesh in the scene. This allows UI panels to exist as physical objects in the 3D world — for example interactive terminals, noticeboards, or in-world displays.
4
+
5
+
## Component Properties
6
+
7
+
For the base properties shared with the 2D canvas (Rml Resource, Autobind Blackboards, Send Event Message, On Demand Update), see the [RmlUI Canvas 2D Component](rmlui-canvas2d-component.md).
8
+
9
+
### 3D-Specific Properties
10
+
11
+
**Proxy Mesh:** The mesh asset used for hit-testing when raycasting input onto the panel. This should match the visible geometry of the panel surface. See [Interaction](#interaction) below.
12
+
13
+
**Base Material:** The material applied to the rendered mesh. The UI texture is injected into this material via the **Texture Slot Name** parameter.
14
+
15
+
**Material Index:** Which material slot on the mesh to replace when applying the UI texture. Defaults to `0`.
16
+
17
+
**Texture Slot Name:** The name of the texture parameter in the **Base Material** that should receive the rendered UI texture (e.g. `BaseTexture`).
18
+
19
+
**Texture Size:** The pixel resolution of the render target used to render the UI. Higher resolutions give a sharper result on large panels but cost more GPU memory.
20
+
21
+
**Dpi Scale:** A scaling factor applied to the RmlUi document layout, allowing the UI to be authored at a standard resolution and then scaled up for high-resolution textures. Defaults to `1.0`.
22
+
23
+
**Clear Stale Input:** When enabled (the default), mouse hover and press state is automatically cleared when no fresh `RaycastInput()` call arrives for that frame. This prevents phantom hover effects when the player looks away from the panel.
24
+
25
+
**Interactive:** When enabled (the default), the panel accepts raycasted input. Disable this to make the panel a non-interactive display.
26
+
27
+
## Interaction
28
+
29
+
Input is delivered to the 3D canvas via raycasting. Call `RaycastInput()` with a world-space ray origin and direction (e.g. from the player's line-of-sight or crosshair), along with an `ezRmlUiInputSnapshot` containing the current button state. The component intersects the ray against the **Proxy Mesh** to compute the UV coordinate, maps that to a canvas-space position, and forwards the result to the RmlUi context.
30
+
31
+
A ready-made helper is provided by `ezRmlUiCanvas3DInteractionExampleComponent`. This component performs a physics raycast each frame (using a configurable collision layer and maximum distance) and calls `RaycastInput()` on the canvas component found on the hit object. It is intended as a reference implementation — copy and adapt it for your own interaction logic.
Copy file name to clipboardExpand all lines: pages/docs/ui/rmlui.md
+7-21Lines changed: 7 additions & 21 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,37 +22,23 @@ The sample uses multiple *RmlUi Canvas 2D* components in its scene to place the
22
22
23
23
Using `ezRmlUiCanvas2DComponent::GetRmlContext()` you get access to the `ezRmlUiContext`. This class implements `Rml::Core::Context`. This gives you access to all the RmlUi features. See the RmlUi [documentation](https://mikke89.github.io/RmlUiDoc/index.html) for details.
24
24
25
-
## 2D and 3D Canvases
25
+
## Canvas Components
26
26
27
-
The *RmlUi Canvas 2D* component (`ezRmlUiCanvas2DComponent`) renders the UI as a screen-space overlay. This is the standard choice for HUDs and menus.
27
+
ezEngine provides two canvas components for placing RmlUi documents in a scene:
28
28
29
-
The *RmlUi Canvas 3D* component (`ezRmlUiCanvas3DComponent`) renders the UI into a texture that is applied to a mesh in the scene, allowing UI panels to exist as physical objects in the 3D world — for example interactive terminals, noticeboards, or in-world displays. Set the **Proxy Mesh** to define the surface used for hit-testing, the **Base Material** to control the look of the panel, and the **Texture Slot Name** to the material's texture parameter that should receive the rendered UI. Interaction is driven by raycasting: call `RaycastInput()` with a world-space ray (e.g. from a player's line-of-sight or crosshair) to deliver mouse position and click events to the UI. Disable the **Interactive** property to make the panel a non-interactive display.
29
+
* The [RmlUI Canvas 2D Component](rmlui-canvas2d-component.md) (`ezRmlUiCanvas2DComponent`) renders the UI as a screen-space overlay. This is the standard choice for HUDs and menus.
30
+
* The [RmlUI Canvas 3D Component](rmlui-canvas3d-component.md) (`ezRmlUiCanvas3DComponent`) renders the UI into a texture applied to a mesh in the scene, allowing UI panels to exist as physical objects in the 3D world.
30
31
31
-
## Blackboard Data Binding
32
-
33
-
The [blackboard](../misc/blackboards.md) of an object can be automatically bound to the RmlUi data model, making blackboard entries accessible as RmlUi data model variables. Enable the **Autobind Blackboards** property on the canvas component to have it search the owner object's hierarchy for a blackboard component and bind it automatically. The blackboard's name is used as the RmlUi model name.
34
-
35
-
You can also bind blackboards manually from C++ using `ezRmlUiCanvasComponentBase::AddBlackboardBinding()`.
36
-
37
-
Both scalar values and [variant arrays](https://mikke89.github.io/RmlUiDoc/pages/data_bindings.html) stored in the blackboard are supported.
38
-
39
-
## UI Events
40
-
41
-
By default, reacting to RmlUi events (such as button clicks) requires registering C++ event handlers via `ezRmlUiContext::RegisterEventHandler()`.
42
-
43
-
As a simpler alternative, enable the **Send Event Message** property on the canvas component. When enabled, every RmlUi event fires an `ezMsgRmlUiEvent` message on the component's owner object. The message carries:
44
-
45
-
*`m_sIdentifier` — the identifier string configured on the RmlUi element (e.g. via the `data-event-id` attribute or the event listener identifier).
46
-
*`m_sType` — the RmlUi event type (e.g. `click`, `change`).
47
-
48
-
This message can be handled in [visual scripts](../custom-code/visual-script/visual-script-overview.md) or C++ components attached to the same object, enabling script-driven UI logic without writing a custom C++ event handler.
32
+
Both components support blackboard data binding, event messages, and on-demand rendering. See the individual component pages for their full property reference.
49
33
50
34
## Localization
51
35
52
36
All text content in RmlUi documents is automatically passed through ezEngine's localization system (`ezTranslate`). That means you can set up translation tables for different languages.
0 commit comments