mochilibraries / mochi.dearimgui

Automatically generated low-level C# bindings for Dear ImGui

Dear ImGui-flavored Mochi

This repo contains C# bindings for Dear ImGui as well as a Biohazrd-powered generator for generating them.

We currently publish NuGet packages for .NET 6 on Windows x64 and Linux x64 (glibc >= 2.27). The Mochi.DearImGui package currently only provides Windows support, it will be a cross-platform meta package in the future. Mochi.DearImGui.linux-x64 provides support for Linux.

A backend for OpenTK is published as Mochi.DearImGui.OpenTK, and is platform-independent. See Mochi.DearImGui.Sample for example usage.

In contrast to other C# bindings for Dear ImGui, this one interacts with the C++ API directly and is lower-level. If you need high-level bindings consider using the excellent ImGui.NET instead.

License

This project is licensed under the MIT License. See the license file for details.

Additionally, this project has some third-party dependencies. See the third-party notice listing for details.

Building

Windows Prerequisites

Windows 10 21H2 x64 is recommended.

Tool	Tested Version
Visual Studio	2022 (17.1.0p2)
.NET 6.0 SDK	6.0.101
CMake	3.22.0

Visual Studio must have the "Desktop development with C++" workload installed.

Linux Prerequisites

Ubuntu 20.04 Focal x64 is recommended, but most distros are expected to work. (Mochi.DearImGui itself should also work on Linux ARM64, but the OpenTK backend doesn't since OpenTK's GLFW redistributable doesn't.)

Package	Tested Version
build-essential	12.8
cmake	3.16.3
dotnet-sdk-6.0	6.0.100

Building Dear ImGui and generating the bindings

1. Ensure Git submodules are up-to-date with git submodule update --init --recursive
2. Build and run generate.cmd (Windows) or generate.sh (Linux) from the repository root

Building and running the sample

Without modification the sample will depend on the bindings being built locally as instructed above.

Simply build+run Mochi.DearImGui.Sample as you would any other .NET project. (IE: Using F5 in Visual Studio or dotnet run --project Mochi.DearImGui.Sample.)

mochi.dearimgui's Issues

Add support for ImPlot

https://github.com/epezent/implot

Mostly making this issue to record why certain decisions were made.

Building ImPlot as a separate DLL

I tested building Mochi.DearImGui.Native with ImPlot, here's the sizes in MB:

Platform	Config	Before	After
win-x64	Release	0.88	2.52
linux-x64	Release	1.16	3.67
win-x64	Debug	1.95	4.39
linux-x64	Debug	3.43	11.9

Pretty significant increase across the board. (Linux debug sizes are a little misleading because the debug info is embedded.)

Windows is not the worst ever, but for optional functionality you might not care about it's pretty significant. I suspect significant size increase is mostly due to ImPlot having basically 12 overloads per plot method. Internally it makes very heavy use of inlining so they're not exactly efficient on code space.

I quickly hacked together building ImPlot separately and got these sizes. (The "Sum" column is the ImPlot runtime + the Dear ImGui-only runtime from above. The "Diff" column is the difference between the sum and the after column above.)

Platform	Config	Size	Sum	Diff
win-x64	Release	1.64	2.52	+0.00
linux-x64	Release	2.56	3.72	+0.05
win-x64	Debug	2.52	4.47	+0.08
linux-x64	Debug	8.77	12.2	+0.30

The overhead of shipping the DLLs separately is either non-existent or basically negligible.

Verdict: Ship the runtimes separately.

Making a separate repo for Mochi.DearImGui.ImPlot

I think it's best to keep things together because it's important that the native runtimes are both built against the same version of Dear ImGui. We also will always want to release them at the same time for the same reason. In their natural environment, both are statically linked so they neither have a heavy emphasis on ABI stability.

Verdict: Keep everything in one repo.

How to enumerate templated overloads

ImPlot presents an unusual circumstance for Biohazrd: It uses templated methods for most of its functionality, but the templates are all defined for specific types in a C++ file.

In C++ the limits to the methods which can be called is basically enforced at link-time. Calling an overload which does not exist is valid C++, but fails during link. As such there isn't directly a way to enumerate which values of T are valid except by convention.

Need to investigate more. Ideally we'd just parse implot_items.cpp to determine which specializations exist, but I don't think Biohazrd will do it cleanly out of the gate.

`Text("")` results in a crash because the format string is null

Because DearImGuiInterpolatedStringHandler.NullTerminateAndGetString returns a span not including the null terminator, "" results in a 0-length ReadOnlySpan<byte>. This causes the byte* from the fixed statement to be null which is not correct in our case.

DearImGuiInterpolatedStringHandler.NullTerminateAndGetString should return a span which includes the null terminator.

Vector4 is different from imvec4

order of vector4 is different from imvec4

struct ImVec4
{
    float                                                     x, y, z, w;
    constexpr ImVec4()                                        : x(0.0f), y(0.0f), z(0.0f), w(0.0f) { }
    constexpr ImVec4(float _x, float _y, float _z, float _w)  : x(_x), y(_y), z(_z), w(_w) { }
#ifdef IM_VEC4_CLASS_EXTRA
    IM_VEC4_CLASS_EXTRA     // Define additional constructors and implicit cast operators in imconfig.h to convert back and forth between your math types and ImVec4.
#endif
};

 public struct Vector4 : IEquatable<Vector4>, IFormattable
    {
        public float W;

        public float X;

        public float Y;

        public float Z;
}

use unmanaged, ref

why don't use the ref keyword in the pointer parameter instead?
and function like ImGui.ListBox

        [DllImport("Mochi.DearImGui.Native", CallingConvention = CallingConvention.Cdecl, EntryPoint = "?ListBox@ImGui@@YA_NPEBDPEAHQEBQEBDHH@Z", ExactSpelling = true)]
        private static extern byte ListBox_PInvoke(byte* label, int* current_item, sbyte** items, int items_count, int height_in_items);

use UnmanagedType.LPArray and use string[];

        [DllImport("Mochi.DearImGui.Native", CallingConvention = CallingConvention.Cdecl, EntryPoint = "?ListBox@ImGui@@YA_NPEBDPEAHQEBQEBDHH@Z", ExactSpelling = true)]
        private static extern byte ListBox_PInvoke(byte* label, int* current_item, [MarshalAs(UnmanagedType.LPArray, ArraySubType = UnmanagedType.LPStr)]string[] items, int items_count, int height_in_items);

Duplicate ImGuiKey enum and odd naming when generating ImGui 1.89.1 (docking)

The generated bindings for the latest version of ImGui (9964740a47fda96ee937cfea272ccac85dc6a500) results in duplicate ImGuiKey enums.

One that's empty, ImGuiKey_0, and ImGuiKey_1 which contains the expected values except the names are prefixed with yet another ImGuiKey_. So the full name of a key is e.g ImGuiKey_1.ImGuiKey_PrintScreen. It works, but I'd prefer the old naming.

What are your thoughts?

Really appreciate the work you've done, thank you!