RmlUi Documentation

RmlUi uses a modular architecture to separate rendering, system interaction, and windowing logic:

• Renderer: Implements the render interface for a specific rendering API (e.g., OpenGL, Vulkan, DirectX 12). It handles drawing geometry, textures, and shaders.
• Platform: Implements the system interface for a specific operating system or windowing library (e.g., Win32, GLFW, SDL). It handles windowing, input, and clipboard operations.
• Backend: A combination of a Renderer and a Platform.

Integration Strategy:

• Use provided Renderers and Platforms directly in your project to avoid writing custom interfaces.
• Do not use the provided Backends directly. Instead, copy and modify them to suit your specific windowing framework needs.

RmlUi supports a wide range of advanced UI features including:

• Layout: Flexbox layout support.
• Animations: Transitions and transforms (handled via RCSS), and complex animations.
• Data Binding: Demonstrating how to bind UI elements to data sources.
• Visual Effects: Advanced filters and effects applied to UI elements.
• Vector Graphics: Support for Lottie animations (via Lottie plugin) and SVG images (via SVG plugin).
• Testing: A built-in visual testing framework for automated layout testing.

Various samples are available in the repository to demonstrate these features, such as the data_binding sample, effects sample, demo sample (form controls and sandbox), animation sample, lottie sample, and svg sample.

To use RmlUi, follow these initialization steps:

1. Install your custom RenderInterface using Rml::SetRenderInterface.
2. Call Rml::Initialise().
3. Create an Rml::Context using Rml::CreateContext(name, size) to manage documents.
4. Load required fonts using Rml::LoadFontFace(path) or Rml::LoadFontFace(path, is_fallback).
5. Shutdown the library using Rml::Shutdown() when the application exits.

MyRenderInterface render_interface;

Rml::SetRenderInterface(&render_interface);

Rml::Initialise();

Rml::Context* context = Rml::CreateContext("main", Rml::Vector2i(window_width, window_height));

Rml::LoadFontFace("LatoLatin-Regular.ttf");
Rml::LoadFontFace("NotoEmoji-Regular.ttf", true);

// ... application loop ...

Rml::Shutdown();

You can install RmlUi using the vcpkg dependency manager.

vcpkg install rmlui

To keep the UI responsive and rendered, your application loop must perform the following steps:

1. Process Input: Submit mouse or keyboard events to the context (e.g., context->ProcessMouseMove).
2. Update: Call context->Update() to process animations, data bindings, and input changes.
3. Render: Call context->Render() to submit geometry to the RenderInterface.
4. Present: Use your backend to swap buffers/present the frame.

while (!exit_application)
{
    // 1. Process Input
    if (my_input->MouseMoved())
        context->ProcessMouseMove(mouse_pos.x, mouse_pos.y, 0);

    // 2. Update
    context->Update();

    // 3. Render
    Backend::BeginFrame();
    context->Render();

    // 4. Present
    Backend::PresentFrame();
}

Integrating RmlUi follows these general steps:

1. Build or Fetch: Build RmlUi using CMake/vcpkg or fetch the pre-built binaries and link them to your application.
2. Implement Renderer: Implement the abstract RenderInterface (defined in Include/RmlUi/Core/RenderInterface.h) or use one of the provided backends.
3. Initialize: Initialize RmlUi with your implemented interfaces, create a context, provide font files, and load an RML document.
4. Main Loop: In your application loop, call the context's update and render methods, and submit input events to the library.
5. Run: Compile and execute your application.

To build RmlUi along with its included samples, use CMake with a vcpkg toolchain. This example installs the necessary dependencies (freetype and glfw3), clones the repository, and configures the build using the samples preset and the GLFW_GL3 backend.

Note: You must replace <path-to-vcpkg> with the actual path to your vcpkg installation.

vcpkg install freetype glfw3
git clone https://github.com/mikke89/RmlUi.git
cd RmlUi
cmake -B Build -S . --preset samples -DRMLUI_BACKEND=GLFW_GL3 -DCMAKE_TOOLCHAIN_FILE="<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake"
cmake --build Build

The RmlUi test suite consists of three separate projects located under the Source directory. To include them in your build, enable the BUILD_TESTING CMake option. Once enabled, you can build the following targets:

• rmlui_visual_tests: For testing the layout engine via visual comparison.
• rmlui_unit_tests: For verifying individual library units.
• rmlui_benchmarks: For performance tracking and identifying hotspots.