Future Low Priority: Bridging LibGodot.dll with Win32 Windowing System

[GeorgeS2019]

Disclaimer: The following is an AI output, just a recommendation, but food for thought:

---

Making LibGodot work within a WinForms User Control involves bridges between the GDExtension-based library (LibGodot) and the Win32 Windowing system.

To embed this into a WinForms control, you need to provide Godot with a "surface" to draw on that belongs to your WinForms application.

Here is the recommended approach to expose the Windows handle (HWND) and integrate it:

1. The Core Mechanism: RenderingNativeSurface

The modern LibGodot design (targeted for Godot 4.5/4.6) introduces a class called RenderingNativeSurface. This is the abstraction layer Godot uses to render into surfaces provided by a host process.

To make this work in WinForms, you need to:

• On the C# side: Obtain the Handle (IntPtr) of your WinForms UserControl.
• On the LibGodot side: Pass this handle to Godot's DisplayServer or use the set_native_surface method on a Godot Window node.

2. Implementation Recommendation

A. Exposing the Handle from WinForms

In your WinForms UserControl, the handle is readily available. However, for LibGodot to render correctly, you should ensure the control is initialized and has a static handle.

public partial class GodotViewControl : UserControl
{
    public GodotViewControl()
    {
        InitializeComponent();
        // Ensure the handle is created
        var forceHandle = this.Handle; 
    }

    protected override void OnHandleCreated(EventArgs e)
    {
        base.OnHandleCreated(e);
        // This is where you trigger LibGodot initialization
        InitializeLibGodot(this.Handle);
    }
}

B. Linking to LibGodot via GDExtension

Since LibGodot uses GDExtension, you must use the gdextension_create_godot_instance function provided by the library. You will need to wrap the RenderingNativeSurface or use the DisplayServer API to bind the HWND.

The "2dog" strategy:
If you are following the 2dog project's structure, you should look for the set_native_surface implementation. You will need to implement a Windows-specific version of the surface provider:

1. Create a RenderingNativeSurface object in C# (via P/Invoke or the generated bindings).
2. Assign the HWND: Godot's Windows backend expects the HWND to be passed as part of the WindowPlatformData.
3. Call Window.set_native_surface(surface): Call this on the main Godot window object.

3. Proposed API Change for LibGodot

If you are modifying the LibGodot source or contributing to a wrapper, recommend adding a helper method to the DisplayServer or the GodotInstance specifically for Windows:

// Proposed C++ helper in LibGodot for Windows
void godot_attach_to_hwnd(GDExtensionObjectPtr p_instance, HWND p_hwnd) {
    // 1. Get the Window node from the instance
    // 2. Create a Windows-specific RenderingNativeSurface
    // 3. Set the handle
    // 4. Update the DisplayServer to treat this HWND as the rendering target
}

4. Handling Input and Resizing

Embedding the graphics is only half the battle. To make it a true "User Control," you must forward WinForms events to Godot:

• Resizing: Override OnResize in WinForms and call DisplayServer.WindowSetSize in Godot using the new control dimensions.
• Input: Use DisplayServer.InputSetMouseButton and similar methods to inject mouse/keyboard events from WinForms into the Godot instance. The DisplayServerEmbedded class in LibGodot is designed exactly for this "injected" input mode.

Summary Checklist

1. Library: Ensure you have the libgodot.dll compiled with the embedding PRs.
2. Surface: Use RenderingNativeSurface to wrap the UserControl.Handle.
3. Window Mode: Set the Godot project to single_window_mode so it doesn't try to spawn external windows.
4. Integration: Use DisplayServer.window_set_native_handle (if available in your build) or the Window.set_native_surface method introduced in the LibGodot architecture.

[MihaMarkic]

Personally I'd ditch WinForms and perhaps look into WPF and Avalonia. Specially Avalonia.

[GeorgeS2019]

WinForm can host WPF.
Most Avalonia projects have agnostic rendering layers that can be adapted for WPF and Winform

Godot4 already address DirectX Rendering.

LibGodot.dll for Linux rendering is already a PoC in use cases.

LibGodot.dll for Windows rendering is behind schedule.

[GeorgeS2019]

godotengine/godot-proposals#14435

[GeorgeS2019]

Proposed API (libgodot.h)

/**
 * Provide a native OS window/surface handle to LibGodot before the engine boots.
 *
 * MUST be called before libgodot_create_godot_instance().
 *
 * The engine's DisplayServer will render into this surface instead of
 * creating a new OS window. Ignored if NULL.
 *
 * Platform-specific handle types:
 *   Android : ANativeWindow*        (from ANativeWindow_fromSurface())
 *   iOS     : CAMetalLayer*         (UIView.layer via +layerClass override)
 *   macOS   : CAMetalLayer* / NSView*
 *   Windows : HWND
 *   Linux   : wl_surface* (Wayland) / Window XID (X11)
 */
GDE_EXPORT void libgodot_set_native_window(void *p_godot_instance, void *p_os_surface);

Correct call sequence for host applications

// 1. Obtain the OS surface from your UI framework
void* surface = get_metal_layer_or_anative_window();

// 2. Register it — BEFORE the engine boots
libgodot_set_native_window(godot_instance, surface);

// 3. Boot the engine; DisplayServer adopts the provided surface
libgodot_create_godot_instance(argc, argv, &gdext_entry_func);

// 4. Drive the render loop
while (running) {
    libgodot_iteration(godot_instance);
}