MyGUI: a C++17 widget library that keeps rendering backends behind one interface

One widget API over ten rendering backends

MyGUI is a cross-platform library for creating graphical user interfaces for games and 3D applications, written in C++17 and designed to be fast, flexible and easy to integrate with various rendering engines. The word that matters there is engines, because MyGUI is not tied to one.

The supported backends are Vulkan, Direct3D 9, Direct3D 11, OpenGL in its legacy form, OpenGL 3.x, OpenGL ES 3 and WebGL 2, Ogre, OgreNext and OpenSceneGraph. Each has a numeric CMake identifier:

| Backend | CMake ID | |----------------------------|----------| | Dummy (no-op) | 1 | | Ogre | 3 | | OpenGL | 4 | | Direct3D 9 | 5 | | Direct3D 11 | 6 | | OpenGL 3.x | 7 | | OpenGL ES 3 / WebGL 2 (Emscripten) | 8 | | OgreNext | 9 | | Vulkan | 10 | | OpenSceneGraph | 11 |

The backend is chosen with the MYGUI_RENDERSYSTEM CMake option, and the default in the build options table is 7, which is OpenGL 3.x. The dummy backend with id 1 is a no-op implementation, which is the kind of thing that matters for headless testing rather than for shipping.

The widget set covers the usual interactive furniture for a game: buttons, edit boxes, combo boxes, lists, tree controls, item boxes, tab controls, scroll bars, progress bars and windows. Two features go beyond the standard list. Widgets and their descendants can be rotated in 2D space, which is unusual for a widget library, and widget controllers can be configured for animation effects such as fades and slides.

Layouts and skins are XML, and there are editors for both

The architecture that distinguishes MyGUI from a set of widget headers is that the interface is data rather than code. The layout system loads UI layouts from XML files at runtime, and the skin system makes widget appearance fully customisable through XML-based skin definitions.

Those files are authored in tools rather than by hand. The repository ships visual editors under Tools, and there are five of them. LayoutEditor is a WYSIWYG layout designer that produces .layout XML files. SkinEditor is a widget skin creator. ImageEditor is an image resource editor. FontEditor is a font resource editor, with a separate FontConverter that is a headless CLI tool converting a ResourceTrueTypeFont XML into a ResourceManualFont XML plus PNG atlas pair, which is useful for re-baking fonts from source without launching a GUI editor.

That FontConverter detail is more interesting than it sounds. A headless converter in the same toolchain means fonts can be baked in CI as part of a build pipeline, rather than being an action someone performs by hand in a GUI and then commits.

The result is a workflow split that matches how these teams actually work. Programmers write the logic that responds to widget events, and a designer lays out the interface and defines its look in the editors. The XML is the contract between the two, and the runtime loads it. What the library does not do is compute layout for you in the way that a desktop toolkit does, so the arrangement of widgets is largely what the layout file says.

Font rendering with FreeType and MSDF

Font handling gets its own feature block in the documentation, which is a hint about how much of a game's UI work happens there. TrueType fonts are rendered through FreeType, bitmap fonts are supported, and MSDF, multi-channel signed distance field, font support is available as an option.

The hinting modes listed are native, auto-hint, no-auto-hint, monochrome and disabled, which is the set a developer needs when a pixel game font and a smooth UI font live in the same project. Kerning is dynamic with per-pair spacing adjustments, so you can tune specific pairs rather than applying a global value. Unicode code point ranges are configurable with inclusion and exclusion support, which matters for games that need CJK text for one language and Latin text for another from the same atlas.

Text effects cover shadow, colour, selection highlighting, the cursor, word wrap and alignment. The MSDF shaders are listed for OpenGL 3.x, OpenGL ES, DirectX 11, Ogre and OgreNext, with GLSL, HLSL, Metal and SPIR-V shading languages, so the same signed distance field font can be scaled without blurring across the backends that matter.

The high DPI handling has a specific mechanism worth knowing. Fonts auto-scale to the display DPI with AutoDpi on by default, and the scale can be controlled by calling Gui::setDpiScale() before initialise(), or overridden per font through the DpiScale property in the font XML. Fonts are re-rasterized at the scaled size so they stay pixel-perfect, and setDpiScale() can also scale the entire GUI uniformly without touching the operating system DPI.

Getting high DPI right in an SDL application takes five steps

Because MyGUI is a widget layer rather than a windowing layer, the display setup stays with SDL and the DPI conversation is documented as an explicit sequence for an SDL application.

On Windows, you call SetProcessDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2) before creating the window. You then create the SDL window with SDL_WINDOW_ALLOW_HIGHDPI and initialise the rendering context.

Next you compute the scale. Windows uses SDL_GetDisplayDPI() divided by 96.0f, while macOS uses the pixel width from SDL_GetWindowSizeInPixels() divided by the window width from SDL_GetWindowSize(). You call Gui::setDpiScale(dpiScale) before Gui::initialise().

The final step is where the platforms diverge: divide SDL window sizes and mouse coordinates by dpiScale on Windows, and keep them unchanged on macOS. The documentation says to use these logical dimensions for setViewSize() and drawable pixels for the rendering viewport.

That asymmetry is the kind of detail that produces a bug on one platform only. A window that renders at the right size but has a mouse cursor offset by the scale factor is a classic high DPI complaint, and the documentation is clear that the fix differs by operating system rather than being handled for you.

Building it and linking against it

The requirements are CMake 3.22 or newer, a C++17 compiler, SDL2 for the tools and demos, FreeType which is optional and enabled by default, glad which is required on Windows for the OpenGL and OpenGL 3.x backends, and one of the render systems.

The quick start is three commands:

git clone https://github.com/MyGUI/mygui.git
cd mygui
cmake -S . -B build -DMYGUI_RENDERSYSTEM=7
cmake --build build

Consuming it from your own CMake project uses modern imported targets:

find_package(MyGUI REQUIRED)
target_link_libraries(myapp PRIVATE MyGUI::MyGUI MyGUI::OgrePlatform)

There is one exported target per backend, alongside the core library: MyGUI::MyGUI, MyGUI::OgrePlatform, MyGUI::OpenGLPlatform, MyGUI::OpenGL3Platform, MyGUI::OpenGLESPlatform for Emscripten, MyGUI::DirectXPlatform, MyGUI::DirectX11Platform, MyGUI::OgreNextPlatform, MyGUI::VulkanPlatform and MyGUI::OsgPlatform. For OgreNext, the documentation says to add its installation prefix to CMAKE_PREFIX_PATH when configuring the consumer, or set OGRE_DIR.

The build options let you trim what you compile. MYGUI_USE_FREETYPE is on by default, MYGUI_MSDF_FONTS is off, the demos, advanced demos, tools and unit tests are all on, and MYGUI_BUILD_WRAPPER, which builds C# bindings, is off and Windows only. Tests run with ctest against the build directory, and there is also a Python install test script.

Where MyGUI is the wrong choice

The comparison that matters is with a desktop widget toolkit, not with another game engine UI library. MyGUI is a rendering layer that draws widgets and routes events. It does not bring the desktop conventions, and the feature list does not mention accessibility, theming beyond XML skins, or a layout engine that reflows on resize. A project that needs a settings dialog, a text entry with proper caret behaviour across scripts, or keyboard focus handling that matches the platform will find that work belongs to it.

The editor-driven workflow is also a commitment. Adopting MyGUI means adopting a layout XML format and a skin XML format, which means the designers on the team use these tools rather than whatever they already use. That is fine when the team is the audience, and a problem when an external studio delivers assets.

The build system is another practical cost. Ten backends means ten platform and driver combinations to test, and the Windows path additionally needs glad for the OpenGL backends and Direct3D versions of everything. The dependency list is not small, and while the build is CMake and well organised, it is a lot of surface for a library whose stated purpose is to sit inside a game engine that already has a rendering system.

Against writing the UI directly in your engine, MyGUI is worth it when you have many screens and want them authored rather than coded, and it is worth less when the interface is a menu and a couple of dialogs. The repository carries COPYING.MIT alongside the MIT reference in the badge, and the licence field on the repository is classified as a custom one, so read the file rather than assuming.

Editorial conclusion

MyGUI fits a game or 3D application team that wants a retained-mode widget system with designer-authored layouts and skins, and that is willing to pick one rendering backend and carry the C++17 dependency chain. It does not fit a project that needs a toolkit with a managed layout system, an accessibility story, or a widget set maintained outside your own team. Before adopting it, build it with the backend you intend to ship rather than the default, check whether the C# bindings matter to you since they are Windows only and off by default, and read the COPYING.MIT file yourself, because the licence field on the repository is classified as a custom one.

Frequently asked questions

Official sources

1. Issues
2. MyGUI/mygui on GitHub
3. Project website
4. README
5. Releases