Crate beryllium

An opinionated set of "high level" wrappers for the fermium SDL2 bindings.

Initialization And Usage

Very little of SDL2 can be called before you initialize the library. This must be done from the main thread and it must be done only once. beryllium will safely block any double initialization, but I can't enforce that you're on the main thread.

let sdl = unsafe {
  beryllium::init().expect("Couldn't initialize SDL2!")
};

Initialization gives you an SDLToken (no, I will not change the name to SdlToken, that's stupid). This token is the "proof" that you've got SDL2 initialized. Basically every other part of the library is a method off of this token value (polling for events, opening a window, etc), or it's a method of a struct that you create off of this token value (the window you opened, an audio queue, etc).

There's a limited number of other functions that are fine to call even if SDL2 is not initialized, and so they're stand alone top level functions:

• version
• get_error
• lone_message_box

Very little of SDL2 is thread-safe. Your code that interacts with SDL2 will mostly be locked into just the main thread. This isn't a huge deal in practice, but it's something that people might want to know up font.

Safety and Lifetimes

I'm aiming to make as much of the API safe as is possible, but unfortunately not 100% of the interface can be safe. Things are only as safe as they can get, I don't want to ever over promise.

Much of the static safety is done with lifetime tracking, which can make it hard to merge different beryllium values into a single struct. Particularly, values can't easily be combined with their "parent" value. I honestly don't try to do this kind of thing in my own programs. I just have a few free floating values on the stack and then I try to interact with SDL2 as absolutely little as possible. It's an OS abstraction layer, it's not your friend.

If you really feel like you want to try and stick things together into a single struct and then pass that combination around all through the program and stuff, feel free to use transmute to fake the lifetimes involved and ManuallyDrop to carefully clean it up at the end. Or you could go use the sdl2 crate, which handles everything by tracking which subsystems are active via an Rc value in practically everything.

Please note that safety assumptions are usually based on actually looking at the current version's C code, so if an end user uses the Dynamic API to override the version of SDL2 used it's possible they could break safety. It's honestly their fault at that point, not yours or mine. I'm not trying to be glib about it, but calling arbitrary code can't be safety checked. That said, it's an important end user ability that should not be removed.

Rewritten In Rust

Select portions of the SDL2 API have been re-written entirely in Rust (insert memes here). Instead of making a call to whichever SDL2 I simply ported the appropriate code to Rust.

• The Good:
  • It's easier (for us Rust programmers) to understand Rust than C.
  • LLVM can inline Rust code (when appropriate and such).
• The Bad:
  • This takes more dev time to make sure that the new Rust matches the semantics of the C it's replacing.
• The Ugly:
  • If there's a bug user's can use the Dynamic API to apply a patch, so we don't want to do this for anything hardware or OS related (those are the things most like to need driver fixes).

So it's not a lot, and it probably won't ever be a lot, but some small parts have been rewritten in Rust.

Re-exports

pub use fermium as unsafe_raw_ffi;

Structs

AudioFormat	Specifies a particular sample data format.
AudioQueue	Handle to an audio device in "queue" mode, and info about its settings.
CDyLib	Handle to a C ABI dynamic library that has been loaded.
Color	An abstract RGBA color value.
Controller	Handle to a window on the screen.
DefaultAudioQueueRequest	Specifies a request to open an audio queue.
DisplayMode	A description of a fullscreen display mode.
GLWindow	A GLWindow is a Window with an OpenGL context bundled in.
JoystickID	A joystick ID value is just a non-negative i32 value.
KeyInfo	Information
KeyModifiers	Holds flags for the keyboard modifier keys being held.
MouseButtonState	Holds flags for the state of all mouse buttons at any given moment.
Palette	A palette of Color values.
PixelFormat	A handle to the information about a particular pixel layout.
Point	Basic struct for 2D positions.
Rect	Rectangle struct, origin at the upper left.
RendererFlags	Flags for renderer creation.
RendererWindow	This is a [Widow] that also allows SDL2's cross-platform 2D rendering system.
SDLToken	The SDLToken is proof that you have initialized SDL2.
Surface	Handle to a "surface", a CPU-side image.
Texture	Handle to a "texture", a GPU-side image.
Version	A version number.
Window	Handle to a window on the screen.
WindowFlags	Flags that a window might have.

Enums

ArrayPixelOrder
BitmapPixelOrder
ControllerAxis	The types of axises that a Controller has.
ControllerButton	The types of buttons that a Controller has.
Event	The various events that can happen.
FullscreenStyle	The window's fullscreen style.
GLattr	Attributes that you can use to control OpenGL's loading and context creation process.
Keycode	Different keycode values that can come in.
MessageBox	The kind of message box you wish to show.
MouseButton	The possible mouse buttons.
PackedPixelOrder
PixelFormatEnum	The various named pixel formats that SDL2 supports.
PixelLayout
PixelOrder
PixelType
Scancode	Different "scancode" values that can come in.
SurfaceFormat	The desired format for a surface you are creating.

Constants

CONTEXT_DEBUG_FLAG	A flag for use with GLattr::ContextFlags.
CONTEXT_FORWARD_COMPATIBLE_FLAG	A flag for use with GLattr::ContextFlags.
CONTEXT_PROFILE_COMPATIBILITY	Requests an OpenGL Compatibility context.
CONTEXT_PROFILE_CORE	Requests an OpenGL Core context.
CONTEXT_PROFILE_ES	Requests an OpenGL ES context.
CONTEXT_RESET_ISOLATION_FLAG	A flag for use with GLattr::ContextFlags.
CONTEXT_ROBUST_ACCESS_FLAG	A flag for use with GLattr::ContextFlags.
WINDOW_POSITION_CENTERED	Centers the window along the axis used.
WINDOW_POSITION_UNDEFINED	Gives the window an undefined position on this axis.

Functions

get_error	Obtains the current SDL2 error string.
init	Initializes SDL2 and gives you a token as proof, or an error message.
lone_message_box⚠	Shows a basic, stand alone message box.
version	Gets the version of SDL2 being used at runtime.