DEV Community

泽
泽

Posted on

Designing a C++ desktop GUI toolkit where widgets never touch the GPU

Writing a desktop app in C++ is supposed to be the easy case. You have a compiler, a debugger, and thirty years of platform APIs behind you.

In practice, the UI is where projects stall. Not because buttons are hard, but because everything under the buttons is a separate project: window creation, the message loop, mouse and keyboard routing, clipboard, IME candidate window placement, a swapchain, font rasterization, image decoding. Each piece is a week of work. Each piece has to be done twice if you want Windows and Linux. And none of it is the thing you actually wanted to build.

Zekit is my attempt to do that layer once. It's a C++20 GUI toolkit that compiles to a single static library — window, GPU renderer, widget set, layout, text, IME. You include one header and link one lib.

Below is the one design rule everything else hangs off, plus a few things I got wrong on the way.

The rule: widgets never touch the GPU

A widget's job is to describe what this frame looks like. Not to draw it.

widget  (doesn't know a GPU exists)
   │   "one rounded rect here, one line of text there"
   ▼
FrameCollector  (CPU side — the only contract)
   │   vertices / textures / draw order
   ▼
window submits → D3D12 │ Vulkan │ OpenGL
Enter fullscreen mode Exit fullscreen mode

Vertices, batching, uploads, and ordering are handled once, on the window side, for every widget.

This is not a style preference. The moment a single widget owns a GL handle or submits its own command buffer, "switch backends without touching UI code" becomes a lie — because you'd have to go and edit that widget. The rule is the precondition for every other promise the library makes.

It's also why the same UI code produces identical output on all three backends, rather than "close enough".

Value semantics, so you never write new or delete

A minimal Zekit program is eleven lines:

#include <Zekit.h>
#include <ZekitApp.h>

ZEKIT_APP_ENTRY(myApp) {
    Kit::Window win;
    win.SetTitle("Zekit");
    win.SetSize(1000, 700);

    win.Show();
    return win.exec();
}
Enter fullscreen mode Exit fullscreen mode

Add a button and it's still under twenty:

Kit::Button btn("OK");
btn.SetPosition(50, 50);
btn.SetSize(220, 60);
win.AddWidget(btn);          // hand it over, done
Enter fullscreen mode Exit fullscreen mode

AddWidget takes the widget by value, moves it into the tree, and returns a reference to the copy that now lives there. That single decision removes a surprising amount of friction:

  • no new, no delete, no unique_ptr ceremony;
  • no member variable dancing to keep a button alive;
  • no destruction-order questions — the tree dies with the window;
  • no null checks, because there are no pointers to null.

The consequence you have to know about: your local btn is a moved-from shell afterwards. Use the returned reference for anything else you want to do with it. The library even lets you assert this, via isMovedFrom().

Three backends, one line

win.UseRenderer(Rhi::Api::D3D12);   // or Vulkan / OpenGL
Enter fullscreen mode Exit fullscreen mode
Backend What it's for
OpenGL compatibility floor — VMs, remote desktop, older integrations
Vulkan when you want control over commands and memory, natural on Linux
D3D12 coexisting with an existing D3D pipeline on Windows

One gotcha I learned the hard way, and now document loudly: UseRenderer must be the first call after construction. Make a window visible, or set its size, and the default backend has already claimed it — a swapchain is created, a pixel format is set — and that is irreversible. A later call returns false and silently falls back. It doesn't crash. It doesn't warn. It just runs on a backend you didn't pick.

The only legal order is:

construct → UseRenderer → SetTitle/SetSize → AddWidget → Show
Enter fullscreen mode Exit fullscreen mode

If you need to verify what actually happened, read rendererApi (what's really running) rather than gpuPreference (what you asked for). Intent versus fact.

Capability checks, not #ifdef walls

Where platforms differ, Zekit asks "does this platform support it" instead of "which platform is this":

if (Kit::Cap::NativeFileDialog) {
    // use the system dialog
} else {
    // use the one bundled in the library
}
Enter fullscreen mode Exit fullscreen mode

The two look equivalent in a small codebase. They aren't. #ifdef scatters platform conditionals into business logic; capability queries keep them in one place. Same for the entry point — the WinMain / main difference is collapsed into a single macro, so one main.cpp builds on both platforms.

Performance: mechanisms, not numbers

I deliberately don't publish frame times or widget counts per millisecond. Those numbers don't survive a change of machine or scene, and quoting them is how you write a claim you'll regret. What I can state are the mechanisms:

  • Off-screen widgets never enter the draw. Clipped widgets are culled before geometry is collected, not drawn-and-hidden.
  • Unchanged widgets reuse last frame's vertices. Segment caching means the CPU work only happens when something actually changed.
  • Bursts of mouse moves collapse into one frame. Dragging a window doesn't repaint per event.

The library is designed around tens of thousands of widgets. How fast your UI runs is best measured by pushing your real UI through it.

The flip side of caching is a discipline you have to accept: if you change a widget's appearance and don't mark it dirty, the cache hits and nothing changes on screen. That's why every mutator is expected to dirty the widget, and why batching exists — mark many widgets, schedule one frame.

What you ship is two things

Zekit.lib
include/
Enter fullscreen mode Exit fullscreen mode

That's it. Font rasterization, image decoding, and the OpenGL loader are all compiled into the same lib. No third-party DLLs to redistribute, and no Vulkan SDK required on the build machine — if there's no Vulkan runtime at startup, it falls back to OpenGL instead of failing to launch.

Which shrinks the "it won't run on the user's machine" failure surface considerably.

What it is not

Being honest about scope saves everyone time:

  • Not a Qt replacement. If you need broad widget coverage, accessibility, translation infrastructure, and a designer tool, use Qt. It has fifteen years of head start and it shows.
  • Not an immediate-mode library. If you're drawing debug panels inside a game engine, Dear ImGui is the better tool and will stay the better tool.
  • Not for web-stack projects, and not worth it if all you need is one settings dialog.

Where it does fit: desktop tools and editors where you want a native-feeling UI and full control over the layer beneath it; and codebases that were about to hand-roll a platform layer anyway.

Four things I'd tell anyone starting the same project

  1. Define the CPU↔GPU contract first. One struct, one direction, no exceptions. Every later shortcut you take will leak through this seam.
  2. Make widgets impossible to misuse. Value semantics and tree ownership cost a week up front and save a year of lifetime bugs.
  3. Keep exactly one source manifest. Two build presets compiling two different file lists is how you get a Windows-only crash that nobody can reproduce.
  4. Ship the gallery before the docs. People judge a UI library by whether they can run something in thirty seconds.

Try it

Zekit is MIT-licensed and builds on Windows and Linux:

One note for anyone cloning: the release page does not include a prebuilt .lib. Build it yourself — two commands with the provided presets:

cmake --preset windows-msvc
cmake --build --preset windows-msvc-release
Enter fullscreen mode Exit fullscreen mode

If you've built a UI layer from scratch before, I'd genuinely like to hear where you drew the widget/GPU boundary — that decision shapes everything downstream, and I'm not convinced mine is the only good answer.

Top comments (0)