rlImGui: putting Dear ImGui panels inside a Raylib game

What the integration actually is

rlImGui is described in one line as a Raylib integration with Dear ImGui, and in the repository description as a Raylib integration with Dear ImGui. In practice it is a backend, the piece that translates Dear ImGui's draw lists into raylib's rendering calls, plus a small convenience layer.

The audience is specific: developers writing tools, editors and debug interfaces on top of raylib. raylib is a simple C library for games and graphics, and it deliberately does not include a widget toolkit. Dear ImGui is a C++ immediate mode GUI library that does, but it needs a backend for each platform. rlImGui is the raylib one, so a raylib developer can have debug panels, settings windows, asset browsers and the like without writing a renderer.

The primary language is C, with the backend written in C++, and the licence is Zlib.

One structural decision deserves attention because it affects whether you can use the project at all. Dear ImGui is a C++ library, so rlImGui uses C++ to create the backend and the integration with raylib. However, the rlImGui.h API only uses features common to C and C++, so rlImGui can be built as a static library and used by pure C code. Users of ImGui who wish to use pure C must use an ImGui wrapper such as cimgui.

Four calls around the game loop

The setup section is the whole integration in one screen, and it is worth reading closely because the placement of the calls is the part that matters.

#include "rlImGui.h"	// include the API header

// before your game loop
rlImGuiSetup(true); 	// sets up ImGui with ether a dark or light default theme

// inside your game loop, between BeginDrawing() and EndDrawing()
rlImGuiBegin();			// starts the ImGui content mode. Make all ImGui calls after this

rlImGuiEnd();			// ends the ImGui content mode. Make all ImGui calls before this

// after your game loop is over, before you close the window

rlImGuiShutdown();		// cleans up ImGui

Three things are encoded in those comments. Setup happens before the game loop, and it takes a boolean that selects a dark or light default theme. The content calls happen inside the game loop, and specifically between BeginDrawing() and EndDrawing(), which means the ImGui overlay is composed within the same frame as the game. Shutdown happens after the loop and before the window closes.

The Begin and End pair is the pattern to internalise. Every ImGui call has to happen between them, and the comments say so explicitly in both directions: all ImGui calls after Begin, all ImGui calls before End. Getting that wrong is the usual first mistake, and the result is a panel that does not appear or a crash at the end of the frame.

The two examples in the repository's examples folder show the range. The simple example is described as the most simple use of ImGui in raylib, showing only the ImGui demo window. The editor example is more complex and shows how to use raylib 2D and 3D cameras to draw into ImGui windows using render textures.

How you get the source into your project

There are two ways to consume rlImGui, and the project is explicit that the build tooling is not a requirement.

You can use it as a static library, or you can directly include the files into your game project. The repository itself is set up to use Premake to generate a static library and examples for Visual Studio 2019, and Premake can also be used to generate makefiles for Linux. But the README states plainly that Premake is not required to use rlImGui, it is simply what is used for development.

For other build systems, the instruction is that you can simply build rlImGui and ImGui into a library, or even add the files directly to your game if it can use C++ code. There are no specific build requirements for rlImGui itself, and it has no dependencies other than raylib and imgui.

That is a real advantage for a library like this, which is often pulled into an existing engine or tool with a build system you do not control. Dropping in source files beats fighting a build system.

The version story is the part to plan around. The main repository will always pull from the latest raylib and the latest Dear ImGui, each from the respective GitHub repositories. Tags and releases are made for major releases of raylib or significant changes to Dear ImGui, and two are listed: Raylib 6.0 with ImGui 1.92.7 and Raylib 5.5 with ImGui 1.92.7, each on its own branch of the repository.

So the choice is tracking head versus pinning a known combination. For a game in production, the tagged branch is the safer choice, because the main branch will move underneath you whenever either upstream library ships a change.

Raylib textures drawn as ImGui widgets

Beyond the backend, rlImGui ships a set of helpers that come up constantly when you are building a game editor, and the image functions are the most used of them.

void rlImGuiImage(const Texture *image);
void rlImGuiImageSize(const Texture *image, int width, int height);
void rlImGuiImageSizeV(const Texture* image, Vector2 size);
void rlImGuiImageRect(const Texture* image, int destWidth, int destHeight, Rectangle sourceRect);
void rlImGuiImageRenderTexture(const RenderTexture* image);
void rlImGuiImageRenderTextureFit(const RenderTexture* image, bool center);

bool rlImGuiImageButton(const Texture *image);
bool rlImGuiImageButtonSize(const char* name, const Texture* image, Vector2 size);

The distinction that matters is between a Texture and a RenderTexture. A Texture is a static image, and the Image family of functions places one inside a panel at a given size or from a source rectangle. A RenderTexture is a live offscreen buffer, so the RenderTexture variants are how you show a 3D scene or a camera view inside an ImGui window. That is the mechanism behind the editor example, which draws raylib 2D and 3D camera output into ImGui windows.

The button variants return a bool, so they fit directly into an ImGui button interaction.

There is also a colour converter. rlImGuiColors.h holds a converter to change raylib colours into ImGui colours, which saves a lot of manual channel juggling when you are mixing engine-rendered content with ImGui panels.

Icons are on by default, and can be turned off

Support for Font Awesome 6 is built into rlImGui and enabled by default. To use the ICON_FA macros for any icon in the free set, you include one header.

#include "extras/IconsFontAwesome6.h"

If you would rather not carry the font, you can define NO_FONT_AWESOME to disable Font Awesome support.

This is a small feature but a telling one. A debug or editor panel without icons is a wall of text, and the icon set is what makes an ImGui overlay look like a tool rather than a debug print. Having it enabled by default with a single define to opt out is a sensible default that costs nothing if you ignore it.

The extras directory also holds the colour converter and the resource files the examples use, and the repository root carries the backend source directly: rlImGui.h and rlImGui.cpp alongside imgui_impl_raylib.h, which is the low level header.

The low level API and the high DPI trade-off

Two escape hatches are documented, and both matter for real projects.

The first is the low level API in imgui_impl_raylib.h. If you want more control over the ImGui backend, you can use it, and the API follows the patterns of other ImGui backends. The important difference is that it does not do automatic context management, and an example of its use is in imgui_style_example.cpp. So the high level rlImGui calls handle the ImGui context for you, and the low level path is for the case where you are managing contexts yourself, for example when you have several contexts or want to drive the frame timing yourself.

The second is high DPI, and the README spends more words on it than on anything else in the document.

If your system does a display scale, like 125% or 150%, you will write code to handle that. Setting the FLAG_WINDOW_HIGHDPI flag in raylib creates a frame buffer that is automatically scaled to fit your display, which makes it easy to define all your code in a normal resolution. The disadvantage is that it becomes harder to define other buffers in the native resolution, and the most common side effect is that fonts look blurry, because they are rendered at the non-scaled resolution.

rlImGui on non-apple platforms scales the default fonts by the display scale to compensate, but if you have your own fonts you will need to do the same. Apple platforms have several driver bugs with high DPI, which rlImGui tries to compensate for, but the results may vary or be inconsistent with other platforms.

The recommendation the README makes is the interesting part. The better option is not to use FLAG_WINDOW_HIGHDPI and let raylib run in the native resolution, and then scale all your input values by GetWindowDPIScale. That is more work, and it is the recommendation because the blurry font path is a permanent visual defect rather than a temporary inconvenience.

Editorial conclusion

Adopt rlImGui if you are building a tool, editor or debug overlay in a Raylib game and want Dear ImGui's widget set without writing a renderer backend yourself. Do not adopt it for a C-only project that cannot compile C++, since the backend is C++ and pure C users need a separate ImGui wrapper such as cimgui. Before you start, decide between the main branch, which tracks the latest raylib and Dear ImGui, and a pinned tag such as Raylib_6_0, and read the high DPI note, because the default path renders fonts at the non-scaled resolution.

Frequently asked questions

Official sources

1. Issues
2. License: Zlib
3. raylib-extras/rlImGui on GitHub
4. README
5. Releases