ImguiSharp.Redist 0.4.0-preview.3

This is a prerelease version of ImguiSharp.Redist.
dotnet add package ImguiSharp.Redist --version 0.4.0-preview.3
                    
NuGet\Install-Package ImguiSharp.Redist -Version 0.4.0-preview.3
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ImguiSharp.Redist" Version="0.4.0-preview.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ImguiSharp.Redist" Version="0.4.0-preview.3" />
                    
Directory.Packages.props
<PackageReference Include="ImguiSharp.Redist" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ImguiSharp.Redist --version 0.4.0-preview.3
                    
#r "nuget: ImguiSharp.Redist, 0.4.0-preview.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ImguiSharp.Redist@0.4.0-preview.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ImguiSharp.Redist&version=0.4.0-preview.3&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=ImguiSharp.Redist&version=0.4.0-preview.3&prerelease
                    
Install as a Cake Tool

imgui-sharp-native

Hand-written C wrapper around Dear ImGui with SDL3 + SDL_GPU backends, packaged as ImguiSharp.Redist on NuGet. Consumed by SdlSharp.ImGui via P/Invoke on imgui_sharp.

Layout

src/                      C wrapper sources (imgui_sharp.cpp, .h, backend)
third_party/imgui/        Dear ImGui sources (git submodule, pinned tag)
scripts/                  SDL3 fetch helpers (sdl3-versions.json + fetch-sdl3.{sh,ps1})
bindings/                 Generated C# interop contract, shared through the package
nuget/ImguiSharp.Redist/  Native runtimes, binding sources, and opt-in build target
.github/workflows/        CI build matrix + tag-triggered NuGet publish

Building locally

Requirements: CMake 3.20+, a C++ toolchain, and either:

  • an environment where find_package(SDL3 CONFIG) succeeds (system SDL3), or
  • the bundled fetch script to download a pinned SDL3 dev package.
git submodule update --init --recursive

# macOS: fetch SDL3 framework from the upstream DMG
./scripts/fetch-sdl3.sh
cmake -S . -B build -DSDL3_ROOT="$SDL3_ROOT" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
# Windows: fetch SDL3 VC dev package
./scripts/fetch-sdl3.ps1
cmake -S . -B build -A x64 -DSDL3_ROOT="$env:SDL3_ROOT" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Output: build/libimgui_sharp.dylib (macOS) or build/Release/imgui_sharp.dll (Windows).

Runtime SDL3 dependency

libimgui_sharp links against SDL3 but does not ship it. It expects libSDL3 to be co-located in the same directory at runtime — that's what SdlSharp.Redist already provides. On macOS the SDL3 install name is rewritten to @loader_path/libSDL3.dylib so both libraries share one SDL3 instance.

Consuming from a .NET project

<PackageReference Include="SdlSharp" Version="..." />
<PackageReference Include="ImguiSharp.Redist" Version="0.4.0-preview.3" />

SdlSharp.ImGui references both SdlSharp and ImguiSharp.Redist. Applications using that managed package receive its native dependencies transitively.

Starting with 0.4.0-preview.3, ImguiSharp.Redist also contains the matching generated C# bindings. The assembly that provides the managed ImGui API opts in to compiling them:

<PropertyGroup>
  <ImguiSharpIncludeBindings>true</ImguiSharpIncludeBindings>
</PropertyGroup>

The package's build/ImguiSharp.Redist.targets links the sources from its bindings/ directory into that project. The sources are not copied into the consumer repository. The target does not flow transitively, and ordinary applications do not opt in. The generated code requires .NET 10 and unsafe compilation. Define IGSHARP_EXTERNAL_SDL in SdlSharp.ImGui to use SdlSharp's SDL handle definitions; standalone consumers use the generated opaque handles.

Publishing

Pushing a v* tag triggers .github/workflows/release.yml which builds all RIDs, packs the .nupkg, and pushes to nuget.org via trusted publishing (OIDC). First-time setup requires registering this repository as a trusted publisher on nuget.org.

Supported RIDs

win-x64, win-x86, win-arm64, osx-x64, osx-arm64. Linux is deferred (no upstream-prebuilt SDL3 Linux binaries).

ImGui version

Currently Dear ImGui v1.93.0, pinned by the third_party/imgui submodule SHA (c1aaac65e896a45f81f47a4d68f9959e0f86c859). See the current tag with git -C third_party/imgui describe --tags HEAD.

Alpha ABI reset (0.4.0 / ABI 1)

This release intentionally replaces the previous alpha API. Update native binaries and managed bindings together. There are no compatibility entry points.

  • Drawing calls use the complete upstream signature, including flags and the current thickness/flags order. InputText calls include callback/user-data arguments; SDL_GPU rendering includes the optional pipeline argument.
  • All image and texture-stack calls accept IGSharp_TextureRef: either a 64-bit ID or a borrowed Data pointer, with the other member zero. This preserves deferred texture upload without duplicate *TextureData entry points.
  • Bounded text uses UTF-8 pointer/byte-count pairs. Text measurement and wrapping return byte offsets into the input, never a pointer into temporary managed data.
  • Owned helpers consistently use Create/Destroy. DrawData, TextureData and typed TextureList containers can be constructed independently. Containers borrow their draw lists/textures; they do not destroy them.
  • Font memory operations explicitly say Copy, Borrow, or Transfer and override the configuration's ownership setting. Copy is the managed default. Transfer consumes memory allocated by IGSharp_MemAlloc, including on failure. Missing font files return NULL. FontConfig.Flags is available before loading.
  • Removed the old draw-flag aliases, reset-callback sentinel, SetColorEditOptions and AddRemapChar shim. Use current DrawFlags, PlatformIO callback getters, IO.ConfigColorEditFlags and Font_AddRemapCodepoint respectively.
  • ImGui 1.93 changes enum values and IO/Style fields. Regenerate instead of copying old definitions. Glyph codepoints and draw indices remain explicitly 16-bit; texture IDs are 64-bit on every platform. C booleans are one byte and all entry points/callbacks use cdecl.

Generated C# interop

Both public C headers are the source of truth. bindings/ contains generated .NET 10 imports, enums, inline-array structs, UTF-8 convenience adapters, and runtime layout validation. The generator needs Python 3.9+ and Clang; consumers of its committed output do not.

python3 scripts/generate-bindings.py
python3 scripts/generate-bindings.py --check
python3 scripts/check-api-coverage.py

Native.cs exposes raw pointer signatures. Native.Utf8.cs adds span overloads: bounded text derives its byte count from the span; NUL-terminated C strings must include their terminator (an empty span represents NULL). Do not use independent marshalled strings as a begin/end pair. Borrowed string results stay pointers so .NET never frees native-owned storage.

Call Native.ValidateAbi() before reading any mirrored struct. It verifies the wrapper version/schema, then every struct size, alignment, and field offset. The schema includes declarations and enum values, so equal-size layout or enum changes cannot silently pass. The generated mirrors are for pointer access; use the generated imports rather than Marshal.StructureToPtr for bool fields.

Regenerate only in this repository, then pack ImguiSharp.Redist to distribute the sources and native binaries together. SdlSharp.ImGui consumes the sources from its restored package and has no generated copy or separate generator. The ImguiSharpBindingsDirectory MSBuild property identifies the packaged sources for tools such as SdlSharp's API coverage checker.

For local development, stage the native binaries under nuget/ImguiSharp.Redist/runtimes/<rid>/native/, then run:

dotnet pack nuget/ImguiSharp.Redist/ImguiSharp.Redist.csproj -c Release -o packages
python3 scripts/test-bindings-package.py packages/ImguiSharp.Redist.0.4.0-preview.3.nupkg

Restore SdlSharp with this package directory as a NuGet source. Use an isolated package cache when testing an unpublished package version to avoid reusing an older local package with the same version. The package test checks source contents, opt-in compilation, and direct and transitive consumers that do not opt in.

Interop lifetime rules

Destroy owned objects on their owner thread, before their context. Never destroy borrowed handles returned by getters. Frame views expire at the next frame; container buffers and storage references may be invalidated by mutation. Keep borrowed font data and glyph ranges alive until the font is removed. Adding a font copies its config and exclusion ranges, but retains its legacy glyph ranges.

Keep callbacks and their state alive until unregistered and all queued callbacks have completed. Catch managed exceptions in callback trampolines. Use the new PlatformIO callback getters to save/restore handlers. TextureData.QueueUserData allows rendering queues to communicate retained texture references; clear it when the queue releases the texture. DrawCmd_GetInfo provides a command snapshot in one native call while preserving its deferred texture reference.

Shared-library P/Invoke tests

After configuring with -DIMGUI_SHARP_BUILD_TESTS=ON and building, run:

ctest --test-dir build --output-on-failure
dotnet run --project tests/interop -- \
  "$PWD/build/libimgui_sharp.dylib" \
  "$PWD/third_party/imgui/misc/fonts/ProggyClean.ttf"

On Windows, pass the absolute path to build/Release/imgui_sharp.dll. Test builds stage SDL next to the native library. The macOS fetch/build scripts re-sign the standalone dylibs after install-name changes. CI verifies generated files and upstream namespace/enum coverage, resolves every export, and runs the P/Invoke suite on matching architectures (including a self-contained win-x86 process). Cross-architecture jobs compile/publish tests but do not claim runtime validation.

API coverage

The wrapper exports 923 IGSharp_* C functions covering essentially the entire master-branch public API: the everyday widget surface (windows, layout, ID/style stacks, all widget families, popups, menus, tables, tabs), the DrawList API, fonts and font introspection, ListClipper, InputText callbacks, plots, drag and drop, multi-select, table sort specs, logging, ini settings serialization, clipboard/IME/allocator override setters, debug and error-recovery tools, and the ImGuiStorage / ImGuiTextFilter / ImGuiTextBuffer helpers. Coverage excludes variadic/V-suffix overloads, docking/multi-viewport, and a few helper operations described below. Backend coverage is listed separately. For a concrete list, see src/imgui_sharp.h.

ImGuiIO and ImGuiStyle are exposed as layout-compatible C structs (IGSharp_IO, IGSharp_Style) — call IGSharp_GetIO() / IGSharp_GetStyle() to obtain a pointer and read or write fields directly. Layout match with upstream is enforced at compile time by the asserts in src/imgui_sharp_layout_check.cpp.

Intentionally skipped APIs

The main exclusions are listed below. Opaque objects also hide internal fields. Text-filter input buffers are accessible with TextFilter_GetInputBuf and GetInputBufSize; call TextFilter_Build after editing the buffer.

Category Examples Reason Addable?
Variadic / V-suffix overloads TextV, TextColoredV, BulletTextV, SeparatorTextV The typed/non-variadic form is enough — C# formats at the call site before calling Text(...) No — format at call site
Docking / multi-viewport DockSpace, DockBuilder*, ImGuiDockNode, viewport-as-OS-window, the platform/renderer callback table Not on the master branch we track, and our SDL3 + SDL_GPU backends are single-viewport No (until upstream merges to master)

Standalone draw lists

After IGSharp_NewFrame, create a list with IGSharp_DrawList_Create(IGSharp_GetDrawListSharedData()). It is initialized for drawing; push a clip rect and texture before adding primitives. On each subsequent frame, call IGSharp_DrawList_ResetForNewFrame after NewFrame, then restore the clip rect and texture. Destroy the list before its context. A list created with NULL shared data is storage-only. Clones are renderable snapshots, not lists that can be reset or extended.

Backend coverage

The SDL3 platform wrapper supports all upstream initialization modes, events, frame setup, shutdown, gamepad selection, and mouse-capture configuration. Only the SDL_GPU renderer is bundled; other platform initialization modes require the caller to provide a renderer. The SDL_GPU wrapper supports initialization, frame preparation, rendering, shutdown, device-object recreation, manual UpdateTexture, and access to the callback render-state device. IGSharp_ImplSDLGPU3_RenderDrawData accepts an optional custom graphics pipeline; pass NULL for the backend default pipeline.

Sampler selection uses the standard PlatformIO_GetDrawCallbackSetSamplerLinear and SetSamplerNearest callbacks with DrawList_AddCallback. The borrowed render state device is available only during rendering. Device recreation and manual texture updates must run outside an active render pass.

Regression checks

The opt-in tests run headlessly and compile the public headers as C and C++. They exercise standalone draw-list creation/reuse at Retina density, compare v1.93 drawing geometry with direct upstream calls (including flag forwarding and the preserved argument order), test callback resolution, popup returns, color options, text filtering, selection swapping, glyph-range copying, and backend forwarding against recording stubs.

cmake -S . -B build -DIMGUI_SHARP_BUILD_TESTS=ON -DSDL3_ROOT="/path/to/SDL3"
cmake --build build --config Debug
ctest --test-dir build -C Debug --output-on-failure

The pipeline forwarding test uses the real upstream declarations but does not exercise GPU rendering. Run tests on a host that can execute the target architecture.

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on ImguiSharp.Redist:

Package Downloads
SdlSharp.ImGui

Dear ImGui bindings for SdlSharp, using SDL3 GPU backend.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.4.0-preview.3 104 10/23/2026
0.4.0-preview.2 53 10/22/2026
0.4.0-preview.1 68 10/17/2026
0.3.0-preview.3 82 9/9/2026
0.3.0-preview.2 100 9/6/2026
0.3.0-preview.1 96 7/2/2026
0.2.0-preview.2 72 4/25/2026
0.2.0-preview.1 71 4/24/2026
0.1.0-preview.1 80 4/23/2026