The RendererUtils interface

The UImGui::RendererUtils interface gives you utility functions for creating custom renderers. It looks like this:

class UIMGUI_PUBLIC_API RendererUtils
{
public:
    // Call this inside the window hints interface function of the GenericRenderer class
    // Event safety - startup, post-startup
    static void setupManually() noexcept;

    // Returns a pointer to the current renderer
    // Event safety - any-time
    static GenericRenderer* getRenderer() noexcept;

    // Render a new dear imgui frame
    // Event safety - post-begin
    static void beginImGuiFrame() noexcept;

    // Initialise dear imgui for rendering with a renderer that is not OpenGL or Vulkan
    // CAUTION: For OpenGL or Vulkan, use the specialisations under their respective namespaces
    // Event safety - style, begin
    static void ImGuiInitOther() noexcept;

    // Install window callbacks for dear imgui(only needed for some renderers, such as WebGPU or OpenGL)
    // Event safety - style, begin
    static void ImGuiInstallCallbacks() noexcept;

    class UIMGUI_PUBLIC_API OpenGL
    {
    public:
        // Call this inside the window hints interface function of the GenericRenderer class
        //
        // Recommended args:
        // Emscripten/Web targets - UIMGUI_LATEST_OPENGL_VERSION, UIMGUI_RENDERER_CLIENT_API_OPENGL_ES, UIMGUI_OPENGL_PROFILE_ANY, false, Renderer::data().msaaSampl
        // Desktop - UIMGUI_LATEST_OPENGL_VERSION, UIMGUI_RENDERER_CLIENT_API_OPENGL, UIMGUI_OPENGL_PROFILE_CORE, true, Renderer::data().msaaSamples
        //
        // Event safety - startup, post-startup
        static void setHints(int majorVersion, int minorVersion, RendererClientAPI clientApi, Profile profile, bool bForwardCompatible, uint32_t samples) noexcept;

        // Swaps buffers for OpenGL.
        // Event safety - post-begin
        static void swapFramebuffers() noexcept;

        // Create an OpenGL context(call this in post-window creation)
        // Event safety - startup, post-startup
        static Context* createContext() noexcept;

        // Set current OpenGL context(call this in post-window creation)
        // Event safety - startup, post-startup
        static void setCurrentContext(Context* ctx) noexcept;

        // Destroy the current OpenGL context
        // Event safety - post-startup
        static void destroyContext(Context* ctx) noexcept;

        // Get the current OpenGL context
        // Event safety - startup, post-startup
        static Context* getCurrentContext() noexcept;

        // Returns the function for getting the OpenGL proc address
        // Event safety - startup, post-startup
        static GetProcAddressFun getProcAddressFunction() noexcept;

        // Set the swap interval for the OpenGL renderer
        // Event safety - startup, post-startup
        static void setSwapInterval(int interval) noexcept;

        // Initialise dear imgui for rendering with OpenGL
        // Event safety - style, begin
        static void ImGuiInit() noexcept;
    };

    class Vulkan
    {
    public:
#ifndef __EMSCRIPTEN__
        // Initialise dear imgui for rendering with Vulkan
        // Event safety - style, begin
        static void ImGuiInit() noexcept;

        // Event safety - post-startup
        static VkResult createWindowSurface(VkInstance instance, const VkAllocationCallbacks* allocator, VkSurfaceKHR* surface) noexcept;

        // Event safety - post-startup
        static void fillInstanceAndLayerExtensions(TVector<const char*>& instanceExtensions, TVector<const char*>& instanceLayers) noexcept;
#endif
    };

    class WebGPU
    {
    public:
        // Check for WebGPU support
        // Event safety - any time
        static bool supported() noexcept;
    };
};

Platform-independent functions

The following members are platform-independent:

1. setupManually() - tells the windowing library to set up your custom renderer manually, instead of creating a rendering context for you(Call this for every non-OpenGL renderer)
2. getRenderer() - return an abstract GenericRenderer pointer to the current active renderer
3. beginImGuiFrame() - begins a dear imgui frame. Should be called after the rendering API calls its own begin frame function from its corresponding dear imgui backend
4. ImGuiInitOther - initialises dear imgui for renderer that are not OpenGL or Vulkan.
5. ImGuiInstallCallbacks - installs window callbacks for dear imgui(only needed for select renderers, such as OpenGL or WebGPU)

Caution

When building OpenGL or Vulkan renderers, always use the specialisations of the ImGuiInit function in their respective classes.

OpenGL functions

OpenGL requires some additional setup.

The setHints member

The set setHints function allows you to initialise a custom renderer context for OpenGL.

It looks like this:

void setHints(int majorVersion, int minorVersion, RendererClientAPI clientApi, Profile profile, bool bForwardCompatible, uint32_t);

The majorVersion and minorVersion arguments should be set to a corresponding OpenGL/OpenGL ES version. You can use the UIMGUI_LATEST_OPENGL_VERSION macro to set it to the latest version that's supported on your system

The clientApi argument is an enum of type RendererClientAPI, which looks like this:

enum RendererClientAPI
{
    UIMGUI_RENDERER_CLIENT_API_MANUAL,
    UIMGUI_RENDERER_CLIENT_API_OPENGL,
    UIMGUI_RENDERER_CLIENT_API_OPENGL_ES
};

On desktop systems it should be set to UIMGUI_RENDERER_CLIENT_API_OPENGL, while when targeting the web it should be set to UIMGUI_RENDERER_CLIENT_API_OPENGL_ES.

The profile argument is an enum of type OpenGLProfile, which looks like this:

enum OpenGLProfile
{
    UIMGUI_OPENGL_PROFILE_ANY,
    UIMGUI_OPENGL_PROFILE_CORE,
    UIMGUI_OPENGL_PROFILE_COMPAT,
};

On desktop systems is should be set to UIMGUI_OPENGL_PROFILE_CORE, while when targeting the web it should be set to UIMGUI_OPENGL_PROFILE_ANY.

The bForwardCompatible argument toggles OpenGL forward compatibility. It should be set to true on desktop systems and to false on the web

Finally, the samples argument should be a set to the amount of MSAA samples you want your renderer to use. There is no default value provided because this depends on your environment. If you want to use the current configuration, use this as the argument: Renderer::data().msaaSamples.

The swapFramebuffers() function

This function swaps the current framebuffer to the next frame. This should be called every frame.

Context management

From release 2.0 OpenGL contexts can now be managed through the RendererUtils class using the following functions:

1. createContext() - Creates and returns a pointer to an OpenGL context
2. setCurrentContext(Context*) - Sets the provided context as the current context
3. destroyContext(Context*) - Destroys the provided context
4. getCurrentContext() - Returns the current OpenGL context

The getProcAddressFunction() function

This function returns a C function pointer of type GetProcAddressFun which expands to void(*(*)(const char*))(). The returned function pointer is the function that your OpenGL extension loader uses to get OpenGL symbols dynamically.

The setSwapInterval(int) function

Sets the OpenGL swap interval. Setting it to 0 means that the application is running with a virtually unlimited frame rate. Setting it to 1 synchronises the application's framerate with the monitor's refresh rate.

The ImGuiInit(String) function

Initialises dear imgui for running on top of an OpenGL renderer. Requires the GLSL version string that is used by the renderer's shaders as an argument. You can use the UIMGUI_LATEST_GLSL_VERSION for the latest supported version.

Vulkan functions

We have 3 functions that are used by Vulkan renderers to integrate with the framework.

1. ImGuiInit(ImGui_ImplVulkan_InitInfo&) - Given a reference to an instance of ImGui_ImplVulkan_InitInfo it initialises the Vulkan renderer with dear imgui
2. createWindowSurface() - Given a VkInstance, optional VkAllocatorCallbacks* and a pointer to a VkSurfaceKHR this function creates a surface for the framework's window backend. It returns a VkResult enum that is used to check for errors.
3. fillInstanceAndLayerExtensions() - Given references to TVector<const char*> for the instance extensions and instance layers, this function fills the provided arrays with the extension and layer strings required by the framework's underlying window implementation

Note

In the C API, the fillInstanceAndLayerExtensions takes different arguments and looks like this: void UImGui_RendererUtils_Vulkan_fillInstanceAndLayerExtensions(const char*** instanceExtensions, size_t* instanceExtensionsSize, const char*** instanceLayers, size_t* instanceLayersSize);

Caution

These parts of the interface are not available when targeting Emscripten.

WebGPU functions

There is only 1 WebGPU function, which is the supported() function. This function returns true if WebGPU is supported in the client's browser.

Macros

The RendererUtils' header also includes a number of useful macros. They look like this:

#define UIMGUI_EMSCRIPTEN_LATEST_OPENGL_VERSION 2, 0
#define UIMGUI_EMSCRIPTEN_LATEST_GLSL_VERSION "#version 100"

#define UIMGUI_APPLE_LATEST_OPENGL_VERSION 4, 1
#define UIMGUI_APPLE_LATEST_GLSL_VERSION "#version 410"

#define UIMGUI_ANY_LATEST_OPENGL_VERSION 4, 5
#define UIMGUI_ANY_LATEST_GLSL_VERSION "#version 450"

#ifdef __EMSCRIPTEN__
    #define UIMGUI_LATEST_OPENGL_VERSION UIMGUI_EMSCRIPTEN_LATEST_OPENGL_VERSION
    #define UIMGUI_LATEST_GLSL_VERSION UIMGUI_EMSCRIPTEN_LATEST_GLSL_VERSION
#else
    #ifdef __APPLE__
        #define UIMGUI_LATEST_OPENGL_VERSION UIMGUI_APPLE_LATEST_OPENGL_VERSION
        #define UIMGUI_LATEST_GLSL_VERSION UIMGUI_APPLE_LATEST_GLSL_VERSION
    #else
        #define UIMGUI_LATEST_OPENGL_VERSION UIMGUI_ANY_LATEST_OPENGL_VERSION
        #define UIMGUI_LATEST_GLSL_VERSION UIMGUI_ANY_LATEST_GLSL_VERSION
    #endif
#endif

We already showcased how the macros for the OpenGL versions are used.

For OpenGL custom renderers, one should also provide a GLSL version to dear imgui when calling ImGui_ImplOpenGL3_Init(). This is where the UIMGUI_LATEST_GLSL_VERSION macro is used.

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_RendererUtils_, as defined here.