SdlVulkan.Renderer 3.1.371

SdlVulkan.Renderer

SDL3 + Vortice.Vulkan rendering library built on DIR.Lib primitives.

Types

• SdlVulkanWindow — SDL3 window with Vulkan instance and surface lifecycle. Creates maximized, resizable windows with Vulkan surface.
• VulkanContext — Vulkan device, swapchain, command buffers, sync management. MaxFramesInFlight = 2 with per-frame vertex buffers.
• VkRenderer — Renderer<VulkanContext> implementation with FillRectangle, DrawRectangle, FillEllipse, DrawText. Exposes FontAtlasDirty for callers to trigger redraws after glyph rasterization.
• VkPipelineSet — GLSL 450 shader compilation and Vulkan pipeline creation (flat, textured, ellipse)
• VkFontAtlas — Dynamic glyph atlas with FreeType2 rasterization and Vulkan texture upload. Supports grow (512→2048), deferred eviction, and skipUnflushed to prevent sampling stale GPU texture data.

Font Atlas Lifecycle

Per frame:

1. BeginFrame() — handles deferred eviction if atlas was full last frame
2. Flush(cmd) — uploads dirty staging region to GPU via vkCmdCopyBufferToImage
3. DrawText(...) → GetGlyph(...) — cache hit returns UV coords; miss rasterizes into staging
4. GetGlyph(..., skipUnflushed: true) — in draw loops, returns zero-width for glyphs not yet uploaded

Thread safety: vkDeviceWaitIdle() before reusing the shared upload buffer (prevents race with MaxFramesInFlight = 2).

Diagnostic logging (Console.Error): [FontAtlas] / [VkRenderer] prefixed lines for Flush, Grow, EvictAll, cache miss, Resize. Capture with 2>stderr.log.

Usage

using SdlVulkan.Renderer;

using var window = SdlVulkanWindow.Create("My App", 800, 600);
window.GetSizeInPixels(out var w, out var h);

var ctx = VulkanContext.Create(window.Instance, window.Surface, (uint)w, (uint)h);
var renderer = new VkRenderer(ctx, (uint)w, (uint)h);

while (running)
{
    if (!renderer.BeginFrame(bgColor)) { renderer.Resize(w, h); continue; }
    renderer.FillRectangle(rect, color);
    renderer.DrawText("Hello", fontPath, 14f, white, layout);
    renderer.EndFrame();
    if (renderer.FontAtlasDirty) needsRedraw = true;
}

Dependencies

• DIR.Lib — Rendering primitives + FreeType glyph rasterization
• SDL3-CS — SDL3 bindings
• Vortice.Vulkan — Vulkan bindings
• Vortice.ShaderCompiler — GLSL to SPIR-V

License

MIT

Rationale: Why SDL3 + Vortice.Vulkan

This library exists because the TianWen project needed a path to HDR display output (HDR10, scRGB, wide color gamut) that its previous Silk.NET + OpenGL stack could not deliver. The investigation below documents the alternatives considered and why SDL3 (via edwardgushchin/SDL3-CS) + Vortice.Vulkan won. This is decision rationale, not documentation of current features — check the types list above for what the library actually does today.

Why OpenGL was a dead end for HDR

• GPU vendors (NVIDIA, AMD) block 10-bit and floating-point pixel formats for OpenGL in windowed mode.
• The Windows HDR compositor (DWM) requires a DXGI swapchain, which only DirectX can drive natively.
• GLFW has no HDR support — glfw issue #890 open since 2016, never implemented.
• GLFW 3.4 (Feb 2024) shipped without it; a proposed GLFW_FLOAT_PIXEL_TYPE patch was never merged.
• Silk.NET's WindowHintBool ends at SrgbCapable / DoubleBuffer — no float pixel type or HDR color space.

Why Vulkan

Vulkan supports HDR output via VK_EXT_swapchain_colorspace + HDR10 surface formats.

Shader migration effort: low. GLSL shaders compile to SPIR-V with minimal mechanical changes (#version 330 core to #version 450, uniforms packed into UBOs, explicit layout(binding=N), build-time compile via glslc / glslangValidator or runtime via Vortice.ShaderCompiler). Shader math (MTF stretch, Hermite soft-knee, WCS deprojection, histogram) stays identical.

API migration effort: high. The real work was replacing ~2000 lines of OpenGL API calls with swapchain setup, descriptor sets, pipeline objects, command buffers, and synchronization.

Silk.NET status at the time of the decision

• v2.23.0 (Jan 2026) — stable, quarterly maintenance releases.
• 3.0: develop/3.0 branch exists, tracking issue #209 open since June 2020 (5.5+ years). Complete rewrite of bindings generation, no release date, lead developer (Perksey) less active, WebGPU bindings planned.
• Silk.NET's prior usage in TianWen was well-contained: 4 source files, 3 NuGet packages, AOT with trimmer warning suppressions.
• Verdict: not dead, but 3.0 had been in development for years; 2.x worked fine for OpenGL but was a dead end for Vulkan/HDR on any near-term horizon.

Known Silk.NET-side blockers

• macOS regression: Silk.NET 2.21+ cannot create GLFW Vulkan windows on macOS (#2440); 2.20 worked.
• MoltenVK not fully conformant: translates Vulkan to Metal, supports Vulkan 1.4 but some features missing; HDR swapchain extensions may not be implemented.
• Web target lost: Vulkan has no browser support (WebGPU would be the path forward).

Alternatives evaluated (March 2026)

Veldrid — avoid (dead project)

• Last commit: March 2024. Latest NuGet: v4.9.0 (Feb 2023). 159 open issues.
• Clean abstraction (Vulkan, D3D11, Metal, OpenGL) but author (mellinoe) has moved on.
• Targets .NET 6 / netstandard2.0, not .NET 10. No AOT testing. No HDR.

Avalonia + GPU interop — consider only if full UI rewrite desired

• 30K+ stars, extremely active. .NET 10 supported.
• Has GpuInterop sample with Vulkan demo via CompositionDrawingSurface.
• Gives a proper UI framework (menus, panels, dialogs) — could replace hand-built text/panel rendering.
• But: GPU interop is low-level (manage your own Vulkan context inside a compositor callback). HDR depends on the SkiaSharp compositor pipeline (no HDR). Very high migration effort, only worth it if replacing the hand-built UI.

SDL3 (.NET bindings)

• SDL3 itself: 15K stars, actively developed, battle-tested.
• Three competing .NET bindings: ppy/SDL3-CS (osu! team, most production-tested), edwardgushchin/SDL3-CS, flibitijibibo/SDL3-CS.
• SDL3 has native Vulkan surface creation + SDL_GPU abstraction (Vulkan/D3D12/Metal with automatic shader cross-compilation).
• HDR output support at the windowing level.
• SDL3 + keep OpenGL: replaces only GLFW windowing/input. Medium effort. But HDR is still blocked because SDL3's OpenGL renderer hardcodes SDL_COLORSPACE_SRGB.
• SDL3 + SDL_GPU: higher-level Vulkan-like API with shader translation. Medium-high effort.

Evergine Vulkan.NET — best raw Vulkan bindings, no ecosystem

• 284 stars. Source-generated from Vulkan headers (always up-to-date).
• Targets .NET 8+. Full HDR access via raw swapchain formats.
• Raw bindings only — no windowing, no VMA, no shader compiler. Very high migration effort; 5-10x more code than OpenGL for the same result.

Vortice.Vulkan — best raw Vulkan ecosystem (chosen)

• 371 stars (Vulkan), 1.1K stars (Windows/D3D). Last commit: Feb 2026. Only 2 open issues.
• Explicitly targets net9.0 + net10.0. Pure managed C# bindings (delegate* unmanaged function pointers, no P/Invoke). IsAotCompatible = true.
• Bundles VMA (Vulkan Memory Allocator), SPIRV-Cross, and shaderc as companion packages.
• Caveat: single maintainer (bus factor of 1).

WebGPU via wgpu-native — future option, not ready

• wgpu-native: 1.2K stars. Translates to Vulkan/D3D12/Metal.
• .NET bindings immature (Evergine WebGPU.NET Nov 2025, WebGPUSharp 14 stars).
• Shader language is WGSL (GLSL would need porting). HDR not yet in WebGPU spec.
• Revisit when .NET bindings mature.

Why Vortice.Vulkan + edwardgushchin/SDL3-CS

edwardgushchin/SDL3-CS uses LibraryImport (source-generated, AOT-safe) — preferred over ppy/SDL3-CS which uses old DllImport. SDL3-CS.Native NuGet ships desktop natives; Android works but needs manual lib bundling.

SDL3 HDR support: SDL.window.HDR_enabled, SDL.window.SDR_white_level, SDL.window.HDR_headroom display properties, plus PQ (ST 2084) and HLG transfer characteristics. Combined with Vulkan VK_COLOR_SPACE_HDR10_ST2084_EXT swapchain, full HDR output is achievable.

SDL3 Vulkan surface creation: SDL.VulkanLoadLibrary() auto-finds MoltenVK on macOS; SDL.VulkanCreateSurface() returns a VkSurfaceKHR that pairs directly with Vortice.Vulkan.

Could we have stayed on Silk.NET by fixing it upstream?

macOS Vulkan regression (#2440) — small PR, uncertain merge timeline

GLFW 3.4 changed Vulkan detection on macOS; glfwVulkanSupported() can't find the Vulkan loader even though Silk.NET ships it (Silk.NET.Vulkan.Loader.Native). GLFW 3.4 added glfwInitVulkanLoader() which could solve this.

Possible fixes: call glfwInitVulkanLoader() with a custom vkGetInstanceProcAddr before glfwInit(); set VK_ICD_FILENAMES at the bundled MoltenVK ICD; ensure the Vulkan loader is on DYLD_LIBRARY_PATH.

Status: no PRs submitted, zero maintainer engagement on the issue. Silk.NET 2.x is in maintenance mode (14-month gap between 2.22 and 2.23), team focused on 3.0. Trivial PRs merge in 0-11 days; no evidence of substantive external feature PRs merging recently.

HDR - not feasible within Silk.NET's GLFW-based windowing

• GLFW has no API for HDR pixel formats, transfer functions, or color spaces.
• GLFW's own HDR issue (#890) open since 2016.
• Silk.NET's Vulkan bindings already cover all HDR swapchain extensions — the blocker is purely windowing.
• Would require replacing GLFW with SDL3 as windowing backend (huge change) or platform-specific code.

Comparison matrix

SDL3 + OpenGL HDR was corrected to No during evaluation: SDL3's OpenGL renderer hardcodes SDL_COLORSPACE_SRGB as the only accepted output. No float pixel formats, no scRGB, no HDR10 via OpenGL on any platform.

What to watch

• SDL3_GPU maturity — could simplify Vulkan over time.
• WebGPU .NET bindings — if they mature, a future browser target becomes possible.
• Silk.NET 3.0 — if it ever ships with working Vulkan + a non-GLFW windowing path, the comparison may change.