GitHub

Backends

ImGui is a very embeddable library because it abstracts things like drawing to the screen and creating windows to its backends. There are many official backends, but currently CImGui.jl only supports the GLFW/OpenGL3 backend. Other popular backends like SFML and SDL could be added in the future if someone should invest time to make these packages work.

CImGui.set_backend — Function
set_backend(backend::Symbol)

Set the backend to use. Currently supported backends are:

  • :GlfwOpenGL3 (GLFW/OpenGL3, requires ModernGL.jl and GLFW.jl)
source
CImGui.render — Function
render(ui::Function, ctx::Ptr{lib.ImGuiContext}; kwargs...)

Top-level function to call a renderloop implemented by the backend selected by set_backend(). This function will not return until the program exits, either by the user closing the window or ui() returning :imgui_exit_loop. It will also not yield the loop, though you may explicitly call yield() in ui().

Arguments

Positional arguments:

  • ui: The function to execute in the renderloop. This where all the GUI code with calls to CImGui should go.
  • ctx: The ImGui context to use. Note that DestroyContext() will automatically be called on it at the end of the renderloop, so it will be unusable afterwards.

Keyword arguments:

  • hotloading=true: Enable calling the latest version of ui() using @invokelatest. This is handy when using Revise.jl.

  • on_exit::Union{Function, Nothing}=nothing: A destructor/finalizer function that will be called before destroying ctx. This might be useful if you're using some external library that needs to be cleaned up in a certain order.

  • clear_color=Cfloat[0.45, 0.55, 0.60, 1.00]: The color of the window background. This can also be a Ref{Vector{Cfloat}} if you want to control the color dynamically (see the official demo for an example).

  • window_size=(1280, 720): The initial size of the window.

  • window_title="CImGui": The window title.

  • engine=nothing: An optional ImGuiTestEngine.Engine instance. If there are any tests registered with the test engine they will be queued and run automatically.

  • opengl_version::VersionNumber=v"3.2": The OpenGL version to use.

  • wait_events=false: Set to true to call GLFW.WaitEvents() instead of GLFW.PollEvents() (only supported for the GLFW/OpenGL backend).

  • spawn::Union{Bool, Integer, Symbol}=1: How/where to spawn the renderloop. It defaults to thread 1 for safety, but note that currently Julia also uses thread 1 to run the libuv event loop: #50643. The renderloop does yield() on each iteration but it's still likely to hog thread 1 which may cause libuv things like task switching to become slower. In most cases this is unlikely to be a problem, but keep it in mind if you observe IO/task heavy things being slower than you'd expect.

    Possible values are:

    • true: a thread will automatically be chosen, preferring the :interactive threadpool.
    • false: don't spawn a task at all. The caller is reponsible for disabling task migration etc.
    • An Integer: the task will be pinned to this thread ID.
    • :default/:interactive: the task will be pinned to an arbitrary thread in the threadpool.
    Warning

    Only thread 1 is sure to be portable across platforms, do otherwise at your own risk. See also:

  • wait::Bool=true: Block until the spawned renderloop task exits.

source