Add SDL3 bindings for C headers with support for all platforms #1

Susko3 · 2024-04-06T14:04:04Z

osu!framework changes: https://github.com/ppy/osu-framework/compare/master...Susko3:osu-framework:wip-SDL3?expand=1 (osu! framework changes include async mouse+keyboard, which is really nice for latency and should fix ppy/osu-framework#6181)
osu! changes: https://github.com/ppy/osu/compare/master...Susko3:osu:wip-SDL3?expand=1
iOS might not work: libsdl-org/SDL#9430.

Bindings generated with ClangSharp on SDL commit libsdl-org/SDL@6ad390f.

These bindings should be bit-perfect and cross-generate all platform definitions on windows (it should be simple to get this generating on Linux as well, just need to undefine the main platfom macro 72353a8).

They also include:

automatically generated (source generation) friendly overloads for string? + ReadOnlySpan<byte> (for UTF-8 string literals) (c5e3181, 91cef07)
manually written macro function definitions (42b1966)
type-friendly properties/getters on some structs (9a5d2e4)
memory safe arrays (75db9b1)
a custom SDL patch so the C# bindings have proper types (e85349e) (this can't be applied upstream due to various reasons)
and more minor changes that make the bindings nicer to use

The whole binding generation process is driven by a python script. If that is unacceptable, I can rewrite it as a C# console application.

I've made the commits go step-by-step, showing the changes to the generated files along the way. This should be useful for git blaming; to know why/what each line does in the python file.

To test this, you can run the SDL3-CS.Tests project, but you'll need to bring your own SDL3 library. Adding github actions/nuget packing for native will come later.

The bindings don't yet compile. There are errors in SDL_pixels.g.cs, SDL_stdinc.g.cs and SDL_thread.g.cs, a bunch of warnings about "Function like macro definition records are not supported", and a few "Info: Potential missing remapping". Built on SDL commit: libsdl-org/SDL@6ad390f

Probably needs similar undefines on Linux and macOS. Notice that the signatures of `SDL_CreateThread` and `SDL_CreateThreadWithStackSize` have changed.

There are warnings for platform-specific functions.

Doesn't compile because of duplicate `_XEvent` definitions. Linux fails crossgen on Windows due to missing `endian.h`

This works because SDL checks <endian.h> iff SDL_BYTEORDER isn't defined. https://github.com/libsdl-org/SDL/blob/6ad390fc5093bcbf785b7ad103484501d11d8c2a/include/SDL3/SDL_endian.h#L58-L60

The win32 types are kinda cursed, but it makes it easy to copy&paste and check.

These map to 16-bit `ushort` on windows, but are 32-bit on Unix.

This matches .NET's UTF-8 `ReadOnlySpan<byte>` (see `SDL_hints.g.cs`).

Produces a lot of noise about unused remappings (as we're processing a header at a time). All remappings (except `SDL_JoystickGUID`) have been added. `SDL_JoystickGUID` is a remapping of a struct, so it's harded to do programatically.

See commit: 72353a8

This doesn't compile as ClangSharp fails to emit `unchecked` in `SDL_pen.g.cs` and `SDL_touch.g.cs`. And `(SDL_bool)` casts in `SDL_rect.g.cs`.

…eaders

This doesn't compile because of duplicate `SDL_Keycode` definition

…definition

All of these get "Function like macro definition records are not supported: [...] Generated bindings may be incomplete." warnings when running ClangSharp.

Useful as any pointer type can implicitly covert to void *.

This could be done with a source generator, but this is simpler.

…har *` functions

This is done by adding a `Unsafe_` prefix to `(const) char *` (C# `byte*`) functions. I am using `string?` instead of `ReadOnlyMemory<byte>?` because the returned pointer can get invalidated and cause memory-safety issues. The returned pointer is automatically freed if the return type is `char *`. I've checked that the documentation for all functions (except in SDL_stdinc.h) requires calling `SDL_free()` on the pointer.

This helps consumers avoid having to do ugly casts as was previously done in `SDL_quit.cs`. It's very important that the underlying type doesn't change as that might break ABI compat.

Just a playground to see how the string/type/array friendly overloads work. You'll have to provide the SDL3 library manually.

smoogipoo · 2024-04-07T03:51:30Z

Well done 👏. For the time being I've manually gone through every file (including generated ones) just to ensure nothing's weird, and applied a few fixes.

I think this is fine for the time being, leaving to future PRs (in order of importance):

Compiling + embedding of native library (Add native build workflow #2).
Nupkg generation + deploy (Add deploy workflow #3).
Hopefully automatic binding generation.
macOS/Linux binding generation (haven't tried yet, as I said I've gone through every file manually for now).

Susko3 added 30 commits April 5, 2024 23:59

Add global/base files

7012887

Undefine _WIN32 to generate only platform-agnostic APIs

72353a8

Probably needs similar undefines on Linux and macOS. Notice that the signatures of `SDL_CreateThread` and `SDL_CreateThreadWithStackSize` have changed.

Fix errors in SDL_pixels.g.cs by specifying enum types

efc9422

Fix errors in SDL_stdinc.g.cs with define magic

4fbe435

Add simple check for generated functions

0fc701a

There are warnings for platform-specific functions.

Add platform specific generation for SDL_main.h and SDL_system.h

2ccdcb0

Doesn't compile because of duplicate `_XEvent` definitions. Linux fails crossgen on Windows due to missing `endian.h`

Fix duplicate XEvent struct definitions

cef2e24

Fix missing <endian.h> when cross-compiling on windows

ba56109

This works because SDL checks <endian.h> iff SDL_BYTEORDER isn't defined. https://github.com/libsdl-org/SDL/blob/6ad390fc5093bcbf785b7ad103484501d11d8c2a/include/SDL3/SDL_endian.h#L58-L60

Add custom definition for win32 MSG struct

52d13f2

The win32 types are kinda cursed, but it makes it easy to copy&paste and check.

Exclude SDL_main() from DllImport as it isn't exported by SDL3.dll

4ed850c

Add recommended remapping for SDL_hidapi.h

a2178e0

Remap wchar_t * to IntPtr

13b34fe

These map to 16-bit `ushort` on windows, but are 32-bit on Unix.

Map C char to C# byte instead of sbyte

53f98fe

This matches .NET's UTF-8 `ReadOnlySpan<byte>` (see `SDL_hints.g.cs`).

Remap C void * to C# IntPtr

dfe2b5b

Don't log potential typedef remappings

75a9cde

Produces a lot of noise about unused remappings (as we're processing a header at a time). All remappings (except `SDL_JoystickGUID`) have been added. `SDL_JoystickGUID` is a remapping of a struct, so it's harded to do programatically.

Add [UnsupportedOSPlatform("windows")] to SDL_CreateThread() functions

a25b4be

See commit: 72353a8

Add [Flags] attribute to mask/flags enums

dfe0d25

Add C# enum "typedefs" for C typedefs

409ecf7

This doesn't compile as ClangSharp fails to emit `unchecked` in `SDL_pen.g.cs` and `SDL_touch.g.cs`. And `(SDL_bool)` casts in `SDL_rect.g.cs`.

Fix invalid int -> SDL_bool conversion by manually changing SDL h…

9e44316

…eaders

Manually define broken constants

caa4820

Define SDL_FUNCTION_POINTER_IS_VOID_POINTER

37da786

Manually implement endianness-specific audio formats

5747f16

Remap SDL_KeyCode enum to SDL_Keycode typedef

b97a553

This doesn't compile because of duplicate `SDL_Keycode` definition

Move SDL_Keycode typdef to global python script to avoid duplicate …

4b1a1e2

…definition

Manually implement macro functions

42b1966

All of these get "Function like macro definition records are not supported: [...] Generated bindings may be incomplete." warnings when running ClangSharp.

Add void * overload for SDL_free()

702dc06

Useful as any pointer type can implicitly covert to void *.

Add PtrToStringUTF8() for byte *

711e004

Add C# type-friendly properties/getters to some structs

9a5d2e4

Add memory safe IDisposable overloads to array-returning functions

75db9b1

This could be done with a source generator, but this is simpler.

Susko3 and others added 7 commits April 6, 2024 14:24

Add source generator for ReadOnlySpan<byte> overloads of C `const c…

c5e3181

…har *` functions

Change SDL sources to use more proper types

e85349e

This helps consumers avoid having to do ugly casts as was previously done in `SDL_quit.cs`. It's very important that the underlying type doesn't change as that might break ABI compat.

Add sample/tests project

bb9834d

Just a playground to see how the string/type/array friendly overloads work. You'll have to provide the SDL3 library manually.

Add [MustDisposeResource] annoations to array helpers

3edde48

Add DotSettings

8003b85

Refactorings + auto styling

913afa5

smoogipoo approved these changes Apr 7, 2024

View reviewed changes

smoogipoo merged commit 07a8cd9 into ppy:master Apr 7, 2024
1 check passed

Susko3 deleted the initial branch April 7, 2024 09:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add SDL3 bindings for C headers with support for all platforms #1

Add SDL3 bindings for C headers with support for all platforms #1

Susko3 commented Apr 6, 2024

smoogipoo commented Apr 7, 2024 •

edited

Add SDL3 bindings for C headers with support for all platforms #1

Add SDL3 bindings for C headers with support for all platforms #1

Conversation

Susko3 commented Apr 6, 2024

smoogipoo commented Apr 7, 2024 • edited

smoogipoo commented Apr 7, 2024 •

edited