Create SDL3 overloads that don't require use of unsafe

[nolife99]

Some of the generated bindings return a pointer when it could return a ref (like how SDL.CreateSurfaceFrom returns SDLSurface* but SDL.DestroySurface can take a ref SDLSurface). It is safe to return a ref as the pointers are guaranteed to be pinned. Or, for async support, you can wrap the pointers in a struct and pass the pointer in the struct to the p/invoke.

Using the below methods, all pointers can be converted into a ref and vice versa
https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.unsafe.asref?view=net-6.0#system-runtime-compilerservices-unsafe-asref-1(system-void*)
https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.unsafe.aspointer?view=net-6.0

Additionally, I would also suggest changing the ref parameters to ref readonly parameters if possible (prevents having to write more code to support the current restricted overloads)

I understand that the goal is to keep a minimal bindings library, however adding new overloads to support non-unsafe code helps in writing significantly less code (and having to add unsafe everywhere)

[JunaMeinhold]

Hi, the goal of my bindings is not minimal, but rather maximum performance, and any managed abstraction would slow it down, my libraries and wrappers are specifically tailored around it, the only thing i could enable is wrap pointers in handles which helps a bit with that matter but you still will have to write unsafe code.

[JunaMeinhold]

The Hexa.NET.* project and package family is not meant for beginners, but rather for people who are tired of the GC and want low level access and some convenience without compromise.

[nolife99]

Unsafe.AsRef and friends for pointers add pretty much zero overhead (for both methods it is one instruction, AsPointer is just conv.u and AsRef is a reinterpret cast. you use ref parameters for many functions anyways) so that is why I suggest adding ref returns for pointer returns as well

[JunaMeinhold]

This would be extremely prone to memory leaks if someone doesn't watch out and forgets a ref it's automatically a leak and ref type val = ref ... comes with restrictions language wise

ref var surf = ref CreateSurfaceFrom(...);
DoSomething(surf); // forgot 'ref', leaks

var surf = CreateSurfaceFrom(...); // leaks and is valid code with a ref return.

And on top of all if the c api returns a null pointer, you can't even check if it's null or not and then it crashes. ref is not meant for unmanaged pointers, they don't sit in the same memory as c# objects/variables

[JunaMeinhold]

the only thing i can do as i said is this, the SDLWindowPtr is just a wrapper struct around the SDLWindow* pointer, all overloads will accept the XXXPtr as argument and you can implicitly convert between XXXPtr and XXX*

// See https://aka.ms/new-console-template for more information

using Hexa.NET.SDL3;

SDL.SetHint(SDL.SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH, "1");
SDL.Init(SDLInitFlags.Events | SDLInitFlags.Video);

SDLWindowPtr window = SDL.CreateWindow("Test Window", 1280, 720, SDLWindowFlags.Resizable);
if (window.IsNull)
{
    return;
}

uint windowId = SDL.GetWindowID(window);

SDLEvent sdlEvent = default;
bool exiting = false;
while (!exiting)
{
    SDL.PumpEvents();

    while (SDL.PollEvent(ref sdlEvent))
    {
        switch ((SDLEventType)sdlEvent.Type)
        {
            case SDLEventType.Quit:
                exiting = true;
                break;

            case SDLEventType.Terminating:
                exiting = true;
                break;

            case SDLEventType.WindowCloseRequested:
                var windowEvent = sdlEvent.Window;
                if (windowEvent.WindowID == windowId)
                {
                    exiting = true;
                }
                break;
        }
    }
}

SDL.Quit();

[nolife99]

And on top of all if the c api returns a null pointer, you can't even check if it's null or not and then it crashes. ref is not meant for unmanaged pointers, they don't sit in the same memory as c# objects/variables

in response to this, remember that you can get the address of a ref
the below method also checks for null pointers and works as expected, even for c apis
https://learn.microsoft.com/en-us/dotnet/api/system.runtime.compilerservices.unsafe.isnullref?view=net-9.0

[nolife99]

However I think that struct wrappers are significantly cleaner and inlining the methods of the struct itself will end up having pretty much zero overhead

[JunaMeinhold]

well no that is not an option with Unsafe.IsNullRef(T)

it even says that it's this, which means that it had de referenced it before, which btw you have to do if you want a ref on a unmanaged pointer and even then it's not the address of it, it's the address of the variable in that scope on the stack not heap.

(void*)(&source) == nullptr

[nolife99]

I've tested this and it actually works with null pointers. Proof of this is that Unsafe.NullRef actually returns a pointer at address 0, not any variable on the stack. Respectively, it's counterpart Unsafe.IsNullRef works to check if a pointer, REGARDLESS of managed or unmanaged, has address 0. I've used these methods in my own application when interoping with libraries like OpenGL.

This article proves that c++ nullptr does point to address 0, consequently, it works with Unsafe.IsNullRef
https://stackoverflow.com/questions/61197936/can-i-guarantee-that-the-address-of-nullptr-is-always-0

By the way, taking a ref to a null pointer doesn't cause a fatal error, although trying to get the value of it will just throw a NullReferenceException rather than crashing the program

Here's a little test program to demonstrate null ref and nullptr

class Program
{
    static unsafe void Main(string[] args)
    {
        ref var nullptr = ref Unsafe.NullRef<long>();
        var ptrRaw = (long*)null;

        Console.WriteLine((long*)Unsafe.AsPointer(ref nullptr) == ptrRaw);
    }
}

Here is the result:

The below code also returns true:

ref var nullptr = ref Unsafe.AsRef<long>((long*)null);
Console.WriteLine(Unsafe.IsNullRef(ref nullptr));

[JunaMeinhold]

Look, requests like this can feel like demands, and honestly, it's frustrating. I manage 90+ projects alone, and this particular change would require fundamental breaking changes across my entire ecosystem—including my game engine that depends heavily on this library. The migration toll wouldn't just be on me, but on every downstream project and user.

This feels like boilerplate-heavy work that's trickier and riskier than simply adding unsafe to the parent scope.

unsafe 
{
    var surface = SDL.CreateSurfaceFrom(...);
    var texture = SDL.CreateTextureFromSurface(renderer, surface);
    SDL.SetTextureBlendMode(texture, blendMode);
    SDL.DestroySurface(surface);
    // ... dozens more calls, zero extra keywords
}

// ref spam everywhere
ref var surface = ref SDL.CreateSurfaceFrom(...);
SDL.CreateTextureFromSurface(renderer, ref surface);
SDL.SetTextureBlendMode(ref texture, ref blendMode);
SDL.DestroySurface(ref surface);

Also, ref isn't allowed in async scopes, with unsafe you can work around it, but with ref not.

Beyond the technical issues, this would create a minefield for users. With refs, forgetting a single ref keyword turns into a silent memory leak:

ref var surface = ref CreateSurfaceFrom(...);
DoSomething(surface);  // Oops, forgot 'ref' - compiles fine, leaks memory

At least with pointers, memory management is explicit and failures are obvious.

In the future, please consider the scope and impact of what you're requesting. This isn't a small feature addition—it's asking me to fundamentally redesign the core architecture of the library. It would help to assess whether a request requires changing the entire design philosophy before making it.
Also, it really helps when requests are phrased politely, for example:

• 'Could you consider adding these overloads?'
• 'Would it be possible to add support for non-unsafe code?'
• 'It would be great if the bindings could support this; any chance you might implement it?'

This makes it clear that it's a suggestion, not an expectation, and reduces the feeling of pressure.