Repository files navigation

DearImguiSharp is a minimalisticpersonal use .NET wrapper for the immediate mode GUI library, Dear ImGui (https://github.com/ocornut/imgui) built ontop ofcimgui. The goal of Dear ImGui is to allow a developer to build graphical interfaces using a simple immediate-mode style.

By itself, Dear ImGui does not care what technology you use for rendering; it simply outputs textured triangles. Many example renderers exist such as ones for popular graphics APIs: OGL2, OGL3, D3D9 and D3D11 etc.

I originally built this because I believe that while it generates more optimal, convenient bindings,ImGui.NET is too fragile. The custom written binding generator is difficult to maintain and does sometimes break between source library updates.

Normally this wouldn't be a big issue; but

• Maintenance ease.

  • Uses tried and tested Mono binding generatorCppSharp.
  • Uses minimal code fixes/changes, in hope API changes wouldn't break things.

• Vanilla

  • No redefinitions of method names etc.
  • Makes it easy to use original C++ documentation for learning the library.

• Exposes Internal APIs & Backends:

  • Exposesinternal Dear ImGui API that's often omitted from other wrappers.
  • And Win32, D3D9/11/12, OGL2/3, GLFW, SDL2 & Vulkan backends.
  • For more details, seeDearImguiSharp-NativeBuilds.

The goal is to be as 'minimal effort' in the wrapper generation step as possible.
For this, we wrapcimgui as opposed to the originalimgui project [C more reliable to wrap].

Aside from capitalization being modified to match general C# code using CppSharp, the library API should exactly match the original source library.

• All structures reside in theDearImguiSharp namespace.
• All functions reside in theDearImguiSharp.ImGui class.
• Some custom defined functions reside inDearImguiSharp.ImGui.Custom. These are hand-generated for user convenience; but might not always be up to date.
• Access to raw P/Invokes is available viaImGui.__Internal.

usingDearImguiSharp;// Elsewhere in code._context=ImGui.CreateContext(null);ImGui.StyleColorsDark(null);

Please note that the bindings don't have default values for some parameters; where a default value exists in the original API, you can pass null, 0 or the default value for the given type.

Const parameters for certain value types are incorrectly generated by CppSharp.

For example,PushStyleColorVec4 should haveint idx, ImVec2.__Internal val as parameters and notint idx, IntPtr val.

The example above and many others I have tried to fix, but there's no guarantee.

• Go toDearImguiSharp-NativeBuilds.
• Follow instructions in the readme.

• Clone this repository and its submodules.
• Go toDearImguiSharp-NativeBuilds and then thecimgui submodule.
• Replace headers (cimgui.h,cimgui.cpp,cimgui_impl.h) inCodeGenerator project with the ones created using cimgui.
• Add#include "extra.h" to top ofcimgui_impl.h.
• Build and runCodeGenerator. Copy autogeneratedcimgui.dll.cs toDearImguiSharp and compile.

I don't have any test project currently available in this repository. I originally built this library to create overlays for existing applications by hooking the DirectX API.

In that vein, you may check outReloaded.Imgui.Hook which utilizes this library. This is what I use to test the library.

As I am not a graphics programmer, contribution of any sample program would be highly appreciated.

From a performance enthusiast; CppSharp doesn't generate the most efficient code (it's full of reference types!) so let's not make the GC trigger happy.

• Avoid the heap like the plague.
  • Especially with types likeImVec2 andImVec4.
  • This means do not usevar vector = new ImVec2();.
  • Use the stack!
• Assume everything is disposable (useusing statement).
  • Or you'll probably be leaking memory.

How? This library goes out of its way to expose the low level P/Invokes and structures autogenerated by CppSharp (normally private).

Don't do this:

usingvarvector=newImVec2();// Heap allocation + Unmanaged Heap Allocation + Dictionary EntryImGui.CalcTextSize(vector,text,null,false,-1.0f);

This is slightly better (but limits you to stack):

varvecInternal=newImVec2.__Internal();varvector=newImVec2(&vecInternal);// Heap allocationImGui.CalcTextSize(vector,text,null,false,-1.0f);

This is the best:

varvecInternal=newImVec2.__Internal();ImGui.__Internal.CalcTextSize((IntPtr)(&vecInternal),text,null,false,-1.0f);

This library is aminimal effort library. We try to manually fix the least amount of things so hopefully in the future we can just wrap newer versions of dear imgui without worrying about API changes.

• Modify CppSharp generator to not redefine typedef'd void** to IntPtr as this produces incorrect code (no implicit conversion from void** to IntPtr).

• Optimize wrapper by using more efficient bindings. (e.g. MapImVec2 toSystem.Numerics.Vector2).

• Support other operating systems:

  • Some kind of reasonable test; maybe useVeldrid.

I plan to address these in the future but it likely wouldn't be any time soon.

This project was my first time using CppSharp, so there might still be stuff to still learn.I'll happily accept pull requests for any of these features or general quality of life improvements.

• Dear ImGui: Original Library
• cimgui: C Bindings for Dear Imgui by @sonoro1234.
• ImGui.NET: Alternative wrapper using custom code generator by @mellinoe. The most popular one.
• ImGui.Net (Evergine): Team Evergine's take on a custom generator for ImGui. Looks inspired by the original.
• ImGuiSharp: Fairly recent wrapper based on CppSharp, similar to this project. Inspired by the original ImGui.NET and this project.
• Mochi.DearImGui: Wrapper for win-x64, win-arm64 & linux-x64 with surprisingly clean codegen & good performance 👍.
• DearImGui: imgui + implot with OpenTK controller, close to zero heap allocations + original documentation in IntelliSense

I was pretty surprised byMochi.DearImGui when I discovered it (Sept. 2022) personally; but cannot unfortunately use it as there isn'twin-x86 support and adding it to the code generator would unfortunately be a lot of work, with the mess that ABIs are underwin-x86.