Crate mini_gl_fb[][src]

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.

Featureglutin+mini_gl_fbwinit+pixelsminifb
gotta_go_fast-like functionYesNoNo
Event-based APIYesYesNo
Multi-windowYesYesUnsupported
VsyncYes (use glutin)Confusing wgpu stuffOnly FPS locking
Buffer allocationBy userConfusing wgpu stuffBy user
ResizableYesRequires restartYes
ScalableYesIntegerBuggy on Windows
Hardware-acceleratedYesVerymacOS-only
Basic inputYesNoAlways
Multiple rendering backendsNo (OpenGL)Yes, by wgpuNo (one per platform)
Custom shadersYesPre-providedNo shaders
Requires OpenGL3.3+NoNo

Re-exports

pub extern crate rustic_gl;
pub extern crate glutin;
pub extern crate gl;
pub use breakout::GlutinBreakout;
pub use breakout::BasicInput;
pub use config::Config;
pub use config::ConfigBuilder;
pub use core::Internal;
pub use core::BufferFormat;
pub use 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.