Integrating RmlUi into an existing SDL3 / GL3 / glad project

[trexxet]

Hi. My C++ project is using SDL3 for system interactions, OpenGL3 with glad loader, Lua (sol3) for scripting, and have been using Nuklear for GUI. Nuklear and Dear ImGUI are excellent choices for a quick & simple GUI, however, immediate mode UIs are an absolute pain to integrate with scripting, and has some other limiting caveats, e.g. constant CPU load.

Thus, I decided to switch to RmlUi, which looks promising to me - UI layout can be defined in separate files (so no need to bind it to Lua to make UI moddable; and if I need, it has some kind of Lua support, which I haven't looked into yet), performance seems to be +- fine, support for SDL3 and GL3. Though, trying to integrate it had led me to several pitfalls, which are not covered in docs and samples.

So, I'd like to ask if my solution is optimal, note some problems and share it for those trying to do the same:

include(FetchContent)

option(RMLUI_SAMPLES "Build samples of the library." OFF)
set(RMLUI_FONT_ENGINE "freetype" CACHE STRING "Font engine to build RmlUi with. If set to \"none\", RmlUi won't build with any of the included font engines and some samples might be disabled.")

FetchContent_Declare(
	RmlUi
	GIT_REPOSITORY https://github.com/mikke89/RmlUi.git
# 6.0 does not support SDL3
	GIT_TAG        47476069e9283f39333331e0afaa58be26dfa44a
	GIT_SHALLOW    TRUE
)
FetchContent_MakeAvailable(RmlUi)

# for some reason, ${RmlUi_POPULATED} stays empty

set(RMLUI_BACKEND_PATH ${RmlUi_SOURCE_DIR}/Backends)
add_library(rmlui_backend_SDL_GL3 INTERFACE)
target_sources(rmlui_backend_SDL_GL3 INTERFACE
	${RMLUI_BACKEND_PATH}/RmlUi_Platform_SDL.cpp
	${RMLUI_BACKEND_PATH}/RmlUi_Renderer_GL3.cpp
)
# Specifying the corresponding headers in target_sources(), as it's done in Backends/CMakeLists.txt, won't let the IDE to find them
target_include_directories(rmlui_backend_SDL_GL3 INTERFACE ${RMLUI_BACKEND_PATH})
target_compile_definitions(rmlui_backend_SDL_GL3 INTERFACE
        # Must be set explicitly
	RMLUI_SDL_VERSION_MAJOR=3
        # GL interface has it's own glad implementation, so it must be disabled by providing the header name of yours
	RMLUI_GL3_CUSTOM_LOADER=<glad/gl.h>
)

target_link_libraries(targetname PUBLIC 
	glad
	glm::glm
	SDL3::SDL3
	SDL3_image::SDL3_image
	lua::lua
	sol2::sol2
	RmlUi::RmlUi
	rmlui_backend_SDL_GL3
	-lstdc++exp
)

[mikke89]

Hi.

Overall this looks pretty reasonable to me, with your specific requirements. You could perhaps consider taking advantage of our backend targets directly, as shown below. For people starting out fresh, I would generally recommend to use a package manager, like vcpkg, instead of FetchContent.

So far we have mainly treated the backends as example code. There are just so many ways to set things up, and a lot of customization options, so it is a bit hard to find something that can be widely recommended. And each backend has something specific to it. But maybe we could make some improvements. There has also been some chatter of adding the various backends as features to e.g. vcpkg.

For users that want something quicker up and running, you could take advantage of our cmake targets for the backends. This one also handles transitive dependencies. Here is something quite minimal that should work, assuming that Freetype, SDL3, and SDL3-image is available somehow (skipping the custom loader here).

CMakeLists.txt:

cmake_minimum_required(VERSION 3.27)
project(Snake)

set(CMAKE_CXX_STANDARD 20)

find_package(Freetype CONFIG REQUIRED)
find_package(SDL3 CONFIG REQUIRED)
find_package(SDL3_image CONFIG REQUIRED)

include(FetchContent)

set(RMLUI_BACKEND "SDL_GL3" CACHE STRING "RmlUi Backend")
# This ensures the backend targets are added. We are setting this manually as an alternative to enabling the samples. 
set(RMLUI_SHELL ON)

FetchContent_Declare(
	RmlUi
	GIT_REPOSITORY  https://github.com/mikke89/RmlUi.git
	GIT_TAG        47476069e9283f39333331e0afaa58be26dfa44a
	GIT_SHALLOW    TRUE
)
FetchContent_MakeAvailable(RmlUi)

add_executable(Snake main.cpp)

target_link_libraries(Snake PUBLIC
	RmlUi::RmlUi
	rmlui_backend_SDL_GL3
)

main.cpp:

#include <RmlUi/Core.h>
#include <RmlUi/Debugger.h>
#include <RmlUi_Backend.h>

static const char* document_rml = R"(
<rml>
<head>
<style>
    body {
        font-family: rmlui-debugger-font;
        font-size: 12px;
        top: 100px; right: 100px; bottom: 100px; left: 100px;
        padding: 150px;
        text-align: center;
        background: #333;
        color: white;
    }
    p {
        display: block;
        padding: 30px;
    }
    p:hover {
        background: #444;
    }
</style>
</head>
<body>
    <p>Hello world!</p>
</body>
</rml>
)";


int main() {
    Backend::Initialize("Znake", 1024, 768, true);

    Rml::SetSystemInterface(Backend::GetSystemInterface());
    Rml::SetRenderInterface(Backend::GetRenderInterface());
    Rml::Initialise();

    Rml::Context *context = Rml::CreateContext("Znake", {1024, 768});

    Rml::Debugger::Initialise(context);
    Rml::Debugger::SetVisible(true);

    Rml::ElementDocument *document = context->LoadDocumentFromMemory(document_rml);

    document->Show();

    while (Backend::ProcessEvents(context)) {
        context->Update();
        Backend::BeginFrame();
        context->Render();
        Backend::PresentFrame();
    }

    Rml::Shutdown();
    Backend::Shutdown();

    return 0;
}

Have fun with the library, and make sure to show us your creations in time :) Let us know if there is anything we can help out with.

[trexxet]

I think it's fine to manually configure the target only for the renderer/platform interface, as it requires some customization (the user may have their own glad implementation, prefer delegating gl loading to Rml, or use a different loader like gl3w). Better documentation coverage would be helpful.

Sure, here: #757

[mikke89]

Yeah, sounds good. It's super valuable that new users post their initial experiences and give feedback on the documentation. I'll see if I can improve it a bit. The documentation is also a community effort, and we do take pull requests, so any specific suggestions are also very much welcome!

[mikke89]

Hey, I added some more details in the documentation just now, and an example based on your post here: https://mikke89.github.io/RmlUiDoc/pages/cpp_manual/integrating.html#backends

Let me know what you think, if you have some concrete feedback, a quick PR would be appreciated. FYI, there is an edit button at the top of each doc page.

[trexxet]

Looks clear to me - everything I had to investigate at the first integration stage is either fixed or covered in the docs. Thanks!

[trexxet]

So, I finished integrating RmlUI into my project (that's a highly moddable and performance-oriented engine for turn-based strategy games) - everything works as expected. There’s still a lot to do and investigate, so I’ll let you know if I find anything interesting or confusing. Thanks!