search

Sewer56 / DearImguiSharp

Personal use bindings for Dear ImGui created using CppSharp
30 stars 6 forks source link

readme

DearImguiSharp

Nuget

DearImguiSharp is a minimalistic personal use .NET wrapper for the immediate mode GUI library, Dear ImGui (https://github.com/ocornut/imgui) built ontop of cimgui. 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.

Motivation

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

Goals of DearImguiSharp

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

Usage

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

using DearImguiSharp;

// 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.

Known Issues

Const Struct Params

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

For example, PushStyleColorVec4 should have int idx, ImVec2.__Internal val as parameters and not int idx, IntPtr val.

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

Building

Building cimgui

Building the Wrapper

Testing

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 out Reloaded.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.

Performance Recommendation(s)

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.

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:

using var vector = new ImVec2(); // Heap allocation + Unmanaged Heap Allocation + Dictionary Entry
ImGui.CalcTextSize(vector, text, null, false, -1.0f);

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

var vecInternal = new ImVec2.__Internal();
var vector = new ImVec2(&vecInternal); // Heap allocation
ImGui.CalcTextSize(vector, text, null, false, -1.0f);

This is the best:

var vecInternal = new ImVec2.__Internal();
ImGui.__Internal.CalcTextSize((IntPtr) (&vecInternal), text, null, false, -1.0f);

This library is a minimal 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.

To Do

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.

Related Projects

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