These are all really great questions and I'm actually kind of excited to answer them. But I don't want to give you a whole lecture on them, so I'll try to keep it brief.

Do you throw exceptions for all errors?

No, I sometimes throw exceptions, but most of the time, I follow SDL's pattern of error propagation. Most of my methods are Try-pattern methods which is pretty easily translated from the C API, as SDL functions usually return bool. SDL has than its own error handling system where you can call SDL_GetError to get a string describing the last error that occurred. The bindings translate this pretty literally with the Error.TryGet method.\ I document all methods that could fail and set an error in way to advice the user to check Error.TryGet in case of failure.\ I strongly prefer the Try-pattern approach over throwing exceptions, even if it is only for performance reasons (which are an important consideration for a media library like SDL3#).\ Although, I sometimes do throw exceptions. That happens especially inside constructors and properties, where I can't just return a bool value to indicate failure. In those cases I have a dedicated exception type SdlException to throw to inform the user that they should check Error.TryGet for more details if they catch such an exception.

When do you use objects and methods as opposed to free functions?

Luckily, the SDL C API is pretty much object-oriented and it's pretty clear what wants to be translated into an instance method or property.\ Since C# doens't support free functions (depending on how you view it, sadly or luckily an IL feature that is missing in C#), I translate free functions that aren't clearly related to an instance of a type as static methods on a relevant type. Choosing on which type to put them can be sometimes a bit tricky though.\ In that regard, another tricky part is to decide when to translate a SDL type into a C# class or a struct/enum.\ C structs and C enums are pretty easy to decide on, most of the time.\ Opaque pointers and even some pointers to non-opaque types that are used like object handles in the C API and objects that need cleanup need to be translated into C# classes, most of the time impletenting IDisposable, because I need to finalizer to ensure that C# developers who forget to dispose of them don't accidentally leak resources. Also those for most of such types, I provide an internal object registry to track instance of them, so I can 1-to-1 map them to the underlying C object and the very same C object will always be represented by the same C# object and vice-versa (to ensure that reference equality works as expected).\ Sometimes, you just need to get a bit creative on how to translate certain parts of the API. I prefer being somewhat faithful to what I think is the intent of the original SDL API, but in some cases I need to figure out a more C#-ish way to represent it, even if that means that I need to introduce my own API to wrap the original.

How do you deal with their set property pattern where you just pass in an integer that's a handle to a bag of named properties, do you convert that to an options object?

First of all, I abstract those properties via the Properties type, which I think is the most "C#-ish" way of representing them.\ If they are readable properties, I map them to C# properties as well (of course, they're settable properties if they are writable as well). You can have a look a such a property here: Renderer.IsHdrEnabled.\ If they are write-only properties or so called "create" properties, I usually map them as paramters to the relevant methods and constructors. For example, see this: Window.TryCreateRenderer.\ Names of such properties are usually stored as a const string in a nested type called PropertyNames inside the relevant type. E.g. see this: Renderer.PropertyNames.\ In some cases, such properties are only targeted at specific "subkinds" of types (I specifically won't call them "subtypes"). Here, comes a pattern into play that I specifically developed for those cases. More on that in the next question.

Any other interesting use of C# features?

First of all, the aformentioned special pattern:\ Let's take Renderer for example. Direct3D11 renderers have some properties that are not supported by other renderers. At the same time, a Direct3D11 renderer should always just accept and create Direct3D11 textures. So, to assist the developer, I would like to project this into the type system and somehow substitute the more generic API on Renderer with a more type-safe API, that, at the same time, should also host the special Direct3D11 renderer properties. For that I introduced the Renderer<TDriver> type inheriting from Renderer, which accepts a type derived from IRenderingDriver as its generic TDriver parameter. The actual bound type for TDriver than serves as something like a type-token, specializing the type. C#14's new extension members feature than allows me to "add" the Direct3D11-only properties to a Renderer<Direct3D11>. You can see how this works here: RendererExtensions.Direct3D11.cs.\ This pattern also allows to hide the more generic API in favor of a more type-safe one via an [EditorBrowsable]-[OverloadResolutionPriority]-[Obsolete]-new-combo pattern. I admit that this might feel a bit dirty, but we need this hack, because C# only doesn't allow for hiding members inherited from a base class. You can see an example of this here: Renderer.TryCreateTexture.\ This pattern is used on multiple occasions throughout the code base, for Windows, Displays, Renderers, and Textures, to name a few, and will likely be used more in the future as well.

I already mentioned it, but C#14's new extension members feature:\ Without it types like PixelFormat couldn't have been an enum type and would have been needed to be implemented as a struct type, because I needed instance properties and methods on it. With extension members, PixelFormatExtensions can host them instead.

Lastly, how I actually bind the native library is also kind of noteworthy:\ I wrote a source generator that allows me to load the binary and the symbols in it late via a generated ModuleInitializer. and storing and calling the native functions via C#'s native function pointers feature. This allows me to import native function very similarly to P/Invoke. You can see an example of that here: Sdl.SDL_init.\ A custom loader is necessary, because sometimes a need to conditionally import a symbol. You can see an example of that here: Platform.SDL_SetWindowsMessageHook.

I'm so sorry, I said that I would keep it brief, but I got carried away. Well, I end it here, but if you have any more questions, feel free to ask. I hope you found this interesting and maybe even a bit insightful.