Renderer

The Renderer interface looks like this:

class Renderer
{
        static RendererData& data() noexcept;
        static void saveSettings() noexcept;

        static const FString& getVendorString() noexcept;
        static const FString& getAPIVersion() noexcept;
        static const FString& getGPUName() noexcept;
        static const FString& getDriverVersion() noexcept;

        static void forceUpdate() noexcept;
};

Warning

All the get functions will not produce expected results when targeting WASM

---

The first function returns a reference to the RendererData struct that looks like this:

struct RendererData
{
    RendererType rendererType = UIMGUI_RENDERER_TYPE_OPENGL; // Sets the renderer type
    RendererType textureRendererType = UIMGUI_RENDERER_TYPE_OPENGL; // Sets the texture renderer backend
    bool bUsingVSync = true;            // Enables V-Sync, defaults to true
    uint32_t msaaSamples = 8;           // The number of samples for MSAA, supersampling
    bool bEnablePowerSavingMode = true; // Enables the power saving mode
    float idleFrameRate = 9;            // The number of frames to render when idle 
    String emscriptenCanvas             // The HTML canvas selector to draw inside of
};

You can see descriptions in the code comments above. It is defined as part of the C API under C/Internal/RendererData.h.

The saveSettings function saves the settings in this struct to the Renderer config file under Config/Core/Renderer.yaml.

All functions after that, return information fetched from the Graphics API about your GPU, like the driver version or API version.

Caution

On Emscripten/Web: A mismatch between the canvas selector in your HTML template and the one set in your Config/Core/Renderer.yaml WILL NOT PRODUCE AN ERROR. Instead, it will lead to a distorted view and low resolution.

Caution

Emscripten/Web: As of release 2.1 the WebGPU renderer has been temporarily removed. This is not a breaking change per-se, since WebGPU users will be redirected to the OpenGL renderer when targeting emscripten. Due to technical difficulties with maintaining the current implementation we're planning on adding the renderer again in 2027.

Caution

Enabling power saving mode may impact the usability of highly dynamic applications, such as those that rely on updating plots, animation or logic every frame. This caveat might not apply for your application in certain cases, though. Read the tip below for more info.

Tip

You can mitigate the issues listed in the last note by calling Renderer::forceUpdate every time a certain widget that requires high refresh rate is being rendered. This function temporarily disables power saving mode.

Settings

The settings for the renderer are stored at Config/Core/Renderer.yaml, which looks like this:

renderer: opengl # For built-in OpenGL(opengl, gl, ogl or legacy), for built-in Vulkan/WebGPU(vulkan, vk, webgpu, wgpu), custom for custom renderers              
v-sync: false                
msaa-samples: 8
power-saving:
  enabled: true
  idle-frames: 9
emscripten:
  canvas-selector: "#canvas"

And corresponds directly to the RendererData struct documented above.

A custom-renderer field can also exist to accommodate settings for custom renderers. This field is parsed manually. More details can be found on the creating a custom renderer page

Caution

On Emscripten/Web: A mismatch between the canvas selector in your HTML template and the one set in your Config/Core/Renderer.yaml WILL NOT PRODUCE AN ERROR. Instead, it will lead to a distorted view and low resolution.

Event safety

The following members of the Renderer interface are marked as Any time:

1. data()
2. saveSettings()

The rest are marked as Begin.

C API

The C API is the same as the C++ one, but using standard C API semantics such as prefixing each function with UImGui_Renderer_, as defined here.

The C API also allows for setting the renderer metadata using the following functions:

// Event Safety - post-startup
void UImGui_RendererInternalMetadata_setVendorString(UImGui_String str);

// Event Safety - post-startup
void UImGui_RendererInternalMetadata_setApiVersion(UImGui_String str);

// Event Safety - post-startup
void UImGui_RendererInternalMetadata_setDriverVersion(UImGui_String str);

// Event Safety - post-startup
void UImGui_RendererInternalMetadata_setGPUName(UImGui_String str);

This is only intended for use with custom renderers.