Expand description
§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() -> SdlResult {
let time = std::time::Instant::now();
let mut app = mini_sdl::App::new(
"test", // App Name displayed on window.
320, // Pixel buffer resolution, won't be used if you draw directly to canvas.
240,
Timing::VsyncLimitFPS(60.0), // Frame Timing strategy.
Scaling::PreserveAspect, // Pixel buffer scaling strategy, ignored if you draw directly to canvas.
None // Audio sampling rate, if audio is desired.
)?;
app.print_fps_interval = Some(1.0);
while !app.quit_requested {
app.frame_start()?;
// When calling pixel_buffer_update, "buffer" receives access
// to the render_target pixels in RGB format.
// _pitch, not used here, is how many bytes per row.
app.pixel_buffer_update(
|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.pixel_buffer_present()?;
app.frame_finish()?;
// Quit after 2 seconds
if time.elapsed().as_secs_f64() > 2.0 {
app.quit_requested = true
}
}
Ok(())
}§Static Builds
To build statically, run the ‘cargo build’ command preceded by these flags which will point out where “sdl2” and “sdl2_ttf” are:
RUSTFLAGS='-L /opt/homebrew/Cellar/sdl2/2.30.8/lib -L /opt/homebrew/Cellar/sdl2_ttf/2.22.0/lib' cargo buildReplace the paths with ones valid for your system, then add the “static-link” feature to cargo.toml.
Re-exports§
pub use sdl2;
Structs§
- APad
- A simple virtual Game controller with digital buttons and a few analogue axis.
- 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.
- Audio
Input - Used internally to push audio samples to the audio device. Although you can access it directly, it requires locking the audio device so it’s easier to use ‘App::audio_push_samples’ instead.
- Smooth
Buffer - Simple fixed size ringbuffer with fast averaging.
- Stereo
Frame - A single audio sample, with left and right channels.
Enums§
- Button
- A virtual gamepad button with a 0 or 1 state.
- Scaling
- The scaling strategy for the render target. A “VariableAspectRatio” option that preserves a minimum size while alowing vertical or horizontal aspects may be provided in the future. To use the entire window without scaling simply draw directly to “canvas”.
- Timing
- The timing strategy used on every frame advance.