Crate mini_gl_fb

Hardware accelerated library inspired by minifb and friends.

Basic Usage

Start with the function gotta_go_fast. This will create an EventLoop, basic window, and a buffer that you can draw to, all in just one function call. The main public API is available through the MiniGlFb type.

extern crate mini_gl_fb;

fn main() {
    // Create the event loop and framebuffer
    let (mut event_loop, mut fb) = mini_gl_fb::gotta_go_fast("Hello world!", 800.0, 600.0);

    // Fill the buffer with something
    let buffer = vec![[128u8, 0, 0, 255]; 800 * 600];
    fb.update_buffer(&buffer);

    // Show the window until the user decides to quit (close button, or Esc)
    fb.persist(&mut event_loop);
}

The default buffer format is 32bit RGBA, so every pixel is four bytes. Buffer[0] is the bottom left pixel (not the top). See Config::invert_y for information on this. The buffer should be tightly packed with no padding after each row.

Interlude: Library philosophy

All of the internals of this library are exposed. Any fields behind MiniGlFb::internal are not considered a part of the public API but are exposed in case the library is missing a feature that you need “right now.” This library is not here to box you in.

Likewise, by exposing as much as possible it allows you to grow what may have started as a simple project without hassle. This allows you to slowly move away from mini_gl_fb if necessary, without requiring you to completely drop the library the second you need to do something “advanced.”

This also means there’s a number of ways to do the same thing, but this seems like a fair compromise.

More advanced configuration

Use the get_fancy function for more settings. See Config for what’s available. This allows you to, for instance, create a window with a buffer of a different size than the window. This is useful for HiDPI support, since you can take advantage of the full resolution of the screen.

get_fancy (and all the functions in the library) require you to bring your own event loop. This allows for multiple windows. See the multi_window example.

use mini_gl_fb::{get_fancy, config};
use mini_gl_fb::glutin::event_loop::EventLoop;
use mini_gl_fb::glutin::dpi::LogicalSize;

let event_loop = EventLoop::new();
let config = config! {
   window_title: window_title.to_string(),
   window_size: LogicalSize::new(window_width, window_height)
};
let fb = get_fancy(config, &event_loop);

(See the Config documentation for an explanation of the config! macro.)

If you think something else should be exposed as an option, open an issue!

Bring your own context (and event handling)!

Default context is provided by glutin. If that’s not good enough for you [grr! ;^)], there’s the function core::init_framebuffer. Create your own OpenGL context, load the OpenGL functions, and then call core::init_framebuffer to get a framebuffer with a texture already set up.

Note on possible context creation failure:

Currently uses the gl crate for OpenGL loading. OpenGL context creation may fail if your setup does not support the newest OpenGL. This bug needs to be verified and is be fixable. OpenGL ~3 is currently required, but OpenGL 2.1 support should be feasible if requested.

Feature matrix

MGlFb does not implement every feature and is not compatible with everything, but there are still reasons to choose it over other libraries.

Feature	glutin+mini_gl_fb	winit+pixels	minifb
gotta_go_fast-like function	Yes	No	No
Event-based API	Yes	Yes	No
Multi-window	Yes	Yes	Unsupported
Vsync	Yes (use glutin)	Confusing wgpu stuff	Only FPS locking
Buffer allocation	By user	Confusing wgpu stuff	By user
Resizable	Yes	Requires restart	Yes
Scalable	Yes	Integer	Buggy on Windows
Hardware-accelerated	Yes	Very	macOS-only
Basic input	Yes	No	Always
Multiple rendering backends	No (OpenGL)	Yes, by wgpu	No (one per platform)
Custom shaders	Yes	Pre-provided	No shaders
Requires OpenGL	3.3+	No	No

Re-exports

pub extern crate gl;

pub extern crate glutin;

pub extern crate rustic_gl;

pub use breakout::GlutinBreakout;

pub use breakout::BasicInput;

pub use config::Config;

pub use config::ConfigBuilder;

pub use crate::core::Internal;

pub use crate::core::BufferFormat;

pub use crate::core::Framebuffer;

Modules

breakout

Contains the GlutinBreakout struct, which is a way to “break out” the Glutin context and Framebuffer object and manipulate them directly.

config

core

Macros

config

The config! macro is intended to make it easy for us to add new fields in the future while staying backwards-compatible. This is done by making Config #[non_exhaustive] but still providing Default, so that users can obtain the defaults and modify it to their liking. The config! macro automates this, and makes custom configs just as easy as constructing Config directly would be.

Structs

MiniGlFb

Main wrapper type.

Functions

get_fancy

Create a window with a custom configuration.

gotta_go_fast

Creates a non-resizable window and framebuffer with a given size in logical pixels. On HiDPI screens, the physical size of the window may be larger or smaller than the provided values, but the buffer will be scaled to match.