ImguiSharp.Redist
0.4.0-preview.3
dotnet add package ImguiSharp.Redist --version 0.4.0-preview.3
NuGet\Install-Package ImguiSharp.Redist -Version 0.4.0-preview.3
<PackageReference Include="ImguiSharp.Redist" Version="0.4.0-preview.3" />
<PackageVersion Include="ImguiSharp.Redist" Version="0.4.0-preview.3" />
<PackageReference Include="ImguiSharp.Redist" />
paket add ImguiSharp.Redist --version 0.4.0-preview.3
#r "nuget: ImguiSharp.Redist, 0.4.0-preview.3"
#:package ImguiSharp.Redist@0.4.0-preview.3
#addin nuget:?package=ImguiSharp.Redist&version=0.4.0-preview.3&prerelease
#tool nuget:?package=ImguiSharp.Redist&version=0.4.0-preview.3&prerelease
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-bitIDor a borrowedDatapointer, with the other member zero. This preserves deferred texture upload without duplicate*TextureDataentry 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,TextureDataand typedTextureListcontainers can be constructed independently. Containers borrow their draw lists/textures; they do not destroy them. - Font memory operations explicitly say
Copy,Borrow, orTransferand override the configuration's ownership setting. Copy is the managed default. Transfer consumes memory allocated byIGSharp_MemAlloc, including on failure. Missing font files return NULL.FontConfig.Flagsis available before loading. - Removed the old draw-flag aliases, reset-callback sentinel,
SetColorEditOptionsandAddRemapCharshim. Use currentDrawFlags, PlatformIO callback getters,IO.ConfigColorEditFlagsandFont_AddRemapCodepointrespectively. - 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.
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 |