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:
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)getRenderer()
- return an abstractGenericRenderer
pointer to the current active rendererbeginImGuiFrame()
- begins a dear imgui frame. Should be called after the rendering API calls its own begin frame function from its corresponding dear imgui backendImGuiInitOther
- initialises dear imgui for renderer that are not OpenGL or Vulkan.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:
createContext()
- Creates and returns a pointer to an OpenGL contextsetCurrentContext(Context*)
- Sets the provided context as the current contextdestroyContext(Context*)
- Destroys the provided contextgetCurrentContext()
- 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.
ImGuiInit(ImGui_ImplVulkan_InitInfo&)
- Given a reference to an instance ofImGui_ImplVulkan_InitInfo
it initialises the Vulkan renderer with dear imguicreateWindowSurface()
- Given aVkInstance
, optionalVkAllocatorCallbacks*
and a pointer to aVkSurfaceKHR
this function creates a surface for the framework's window backend. It returns aVkResult
enum that is used to check for errors.fillInstanceAndLayerExtensions()
- Given references toTVector<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.
- Home
- Beginner content
- Install guide
- Creating and using the UI components
- The Instance
- The Init Info struct
- Building better titlebar menus
- Textures
- Logging
- Unicode support
- Additional features
- Client-side bar
- Custom type definitions
- Memory management
- C API development
- Config files and Folders
- Interfaces
- Internal Event safety
- Customising the build system
- Modules system
- Collaborating with others
- Advanced content
- Loading dynamic libraries at runtime
- Understanding the library layout
- Compilation mode modifiers
- Supporting plugins
- Production export and deployment
- OS integration tips
- Targeting WASM
- Using a custom rendering engine:
- Using a custom windowing backend:
- Developer and contributor resources
- Misc