halcyon-rs

An SDL & SDL_ttf (3.x) wrapper. Aims for as close to 100% API coverage, while making it neater & safer to use via various Rust mechanisms (see Enhancements). As I'm primarily a C++ developer, this library is probably unsound in various places. These ought to be weeded out over time after reaching full API coverage.

Important

This is purely an API wrapper. It isn't concerned with how you find, and link with, SDL and its satellite libraries on your system; these topics are covered by the sdl3-sys docs.

Concepts

SDL works with raw pointers and ownership rules are mostly described via function documentation. halcyon-rs aims to disambiguate with handles, owned objects and references. For an arbitrary type Foo:

• The handle FooHandle is where the API is actually implemented. Since it isn't tied to anything, it's usually unsafe to use.
• The owned object Foo contains a handle and is responsible for Dropping it.
• The reference Ref<'a, Foo> contains a handle, is lifetime-bound to an owned object, and doesn't drop anything.

Allocations originating from SDL are wrapped in a custom implementation of Box and String. These might not have exact 1:1 semantics with their Rust counterparts; check documentation for specifics.

Enhancements

In an attempt to justify the time spent on this project, here is a list of things that, in my eyes, make halcyon-rs much neater to use over raw SDL bindings:

• Drop impl'd where applicable¹
• Ref for borrowing opaque handles without extra indirection
• halcyon::Result<T> instead of SDL_GetError()
• Box and String for mapping SDL allocations to Rust
• Descriptive bool-enums instead of bool parameters
• Builders wrapping the Properties API
• Encapsulation of reserved struct parameters

Footnotes

1. Certain SDL_gpu objects are an exception, since their destructors require an extra parameter. Such objects have a "manual" drop() method, and have proper documentation of this fact. ↩