Crate mini_sdl

A simple wrapper around SDL2.

This is an early publish of a work-in-progress crate. Use with discretion.

This crate assumes you’ve already installed SDL2 on your system (i.e. ‘brew install sdl2’ on MacOS). It wil not run if SDL2 isn’t found.

Designed primarily to provide raw access to an RGB pixel buffer and display its contents correctly, with timing options like Vsync and frame rate limiting, and scaling options like Aspect Ratio and integer scaling.

I decided to make this crate after spending an entire weekend testing multiple libraries that could potentially perform this task, but failed to either perform well or present the frames with proper frame pacing. SDL2 was the only high-level library that satisfied all requirements, but turned out to be the most complex to use, so wrapping it in something much simpler can be of value to many people who just want a “framebuffer” to write pixels to.

The main goal is to favor simplicity over features. With that said, it will expand in the future, providing access to other basic SDL2 features like sound.

Warning: Some SDL2 internals are exposed as public members, but this kind of access is untested.

Example

This example can be run invoking cargo run -p example from a terminal at the root of the crate.

use mini_sdl::*;

fn main() -> Result<(), String> {
    let mut app = mini_sdl::App::new(
        "test",
        320,
        240,
        Timing::VsyncLimitFPS(60.0),
        Scaling::PreserveAspect,
    )?;

    app.print_fps_interval = Some(1.0);

    while !app.quit_requested {
        app.start_frame()?;
        // When calling update_pixels, "buffer" receives access
        // to the render_target pixels in RGB format.
        // _pitch, not used here, is how many bytes per row.
        app.update_pixels(
            |buffer: &mut [u8], _pitch: usize| {
                let mut i = 0;
                while i < buffer.len() {
                    buffer[i] = 255; // Red
                    buffer[i + 1] = 128; // Green
                    buffer[i + 2] = 16; // Blue
                    i += 3;
                }
            }
        )?;
        app.present_pixel_buffer()?;
        app.finish_frame()?;
    }
    Ok(())
}

Re-exports

• pub use sdl2;

Structs

• App
  A struct that provides SDL initialization and stores the SDL context and its associated data. Designed mostly to be used as a fixed resolution “virtual pixel buffer”, but the SDL canvas is available as one of its fields and can be directly manipulated.
• FontAtlas
• GamePad
  A tiny (4 bytes) struct that contains the state of a “virtual gamepad”. Currently mini_sdl simply maps keyboard keys to it, but in the future it will allow actual gamepads and control remapping.

Enums

• Button
  A virtual gamepad button. Currently hard coded to keyboard keys, it will be mappable in the future.
• Scaling
  The scaling strategy. A “VariableAspectRatio” option may be provided in the future.
• Timing
  The timing strategy used on every frame advance.