Struct Framebuffer

#[non_exhaustive]
pub struct Framebuffer {
    pub buffer_size: LogicalSize<i32>,
    pub vp_size: PhysicalSize<i32>,
    pub did_draw: bool,
    pub inverted_y: bool,
    pub internal: FramebufferInternal,
}

The Framebuffer struct manages the framebuffer of a MGlFb window. Through this struct, you can update the size and content of the buffer. Framebuffers are usually obtained through MiniGlFb::glutin_breakout, but they’re also returned by init_framebuffer.

Basic usage

Firstly, one of the most important things to do when managing a Framebuffer manually is to make sure that whenever the window is resized, the Framebuffer is the first to know. Usually, this is handled for you by MiniGlFb, but that isn’t the case when using the GlutinBreakout.

Whenever you receive a resize event for your window, make sure to call Framebuffer::resize_viewport with the new physical dimensions of your window. You can also figure out some logical dimensions and call Framebuffer::resize_buffer too.

Additionally, when managing multiple framebuffers at once, you should make sure to call GlutinBreakout::make_current when appropriate, before calling any Framebuffer methods. Forgetting to call make_current can cause OpenGL to get confused and draw to the wrong window, which is probably not what you want.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

buffer_size: LogicalSize<i32>

The logical size of the buffer. When you update the buffer via update_buffer, it is expected to contain buffer_size.width * buffer_size.height pixels.

vp_size: PhysicalSize<i32>

The physical size of the viewport. This should always be kept up to date with the size of the window, and there is no reason to set it otherwise unless you’re drawing multiple buffers to one window or something funky like that.

did_draw: bool

This is set to true every time draw is called. (or, by extension, update_buffer)

It’s safe to set this to false afterwards, it’s just a flag to let you know if code you’re calling into has updated the buffer or not.

inverted_y: bool

True if the origin should be the bottom left of the screen instead of the top left. For historical reasons, this is the default. This should only be configured by changing the Config passed to get_fancy.

internal: FramebufferInternal

Contains internal OpenGL things.

Accessing fields directly is not the intended usage. If a feature is missing please open an issue. The fields are public, however, so that while you are waiting for a feature to be exposed, if you need something in a pinch you can dig in easily and make it happen.

The internal fields may change.

Implementations

impl Framebuffer

pub fn update_buffer<T>(&mut self, image_data: &[T])

Examples found in repository

examples/multi_window.rs (line 90)

    fn redraw(&mut self) {
        self.breakout.fb.update_buffer(&self.buffer);
        self.breakout.context.swap_buffers().unwrap();
    }

examples/glutin_breakout.rs (line 45)

fn main() {
    let (event_loop, mut fb) = mini_gl_fb::gotta_go_fast("Hello world!", 800.0, 600.0);
    let mut buffer = vec![[128u8, 0, 0, 255]; 800 * 600];
    fb.update_buffer(&buffer);

    let GlutinBreakout {
        context,
        mut fb,
    } = fb.glutin_breakout();

    let mut mouse_down = false;

    event_loop.run(move |event, _, flow| {
        match event {
            Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
                *flow = ControlFlow::Exit;
            }
            Event::WindowEvent { event: KeyboardInput { input, .. }, .. } => {
                if let Some(k) = input.virtual_keycode {
                    if k == VirtualKeyCode::Escape && input.state == ElementState::Pressed {
                        *flow = ControlFlow::Exit;
                    }
                }
            }
            Event::WindowEvent { event: WindowEvent::Resized(size), .. } => {
                context.resize(size);
                context.window().request_redraw();
            }
            Event::WindowEvent { event: WindowEvent::CursorMoved { position, .. }, .. } => {
                let (x, y) = position.to_logical::<f64>(context.window().scale_factor()).into();
                println!("({}, {})", x, y);
                let mouse_x = min(max(x, 0), 800 - 1);
                let mouse_y = min(max(fb.buffer_size.height - y, 0), 600 - 1);
                if mouse_down {
                    buffer[(mouse_x + mouse_y * 800) as usize] = [64, 128, 255, 255];
                    fb.update_buffer(&buffer);
                    context.window().request_redraw();
                }
            }
            Event::WindowEvent { event: WindowEvent::MouseInput { state, .. }, .. } => {
                if state == ElementState::Pressed {
                    mouse_down = true;
                } else {
                    mouse_down = false;
                }
            }
            Event::RedrawRequested(_) => {
                fb.redraw();
                context.swap_buffers().unwrap();
            }
            _ => {}
        }
    });
}

examples/game_of_life.rs (line 56)

fn main() {
    let mut event_loop = EventLoop::new();
    let mut fb = mini_gl_fb::get_fancy(config! {
        window_title: String::from("PSA: Conway wants you to appreciate group theory instead"),
        window_size: LogicalSize::new(800.0, 800.0),
        buffer_size: Some(LogicalSize::new(WIDTH as _, HEIGHT as _))
    }, &event_loop);

    fb.change_buffer_format::<u8>(BufferFormat::R);
    fb.use_post_process_shader(POST_PROCESS);

    let mut neighbors = vec![0; WIDTH * HEIGHT];
    let mut cells = vec![false; WIDTH * HEIGHT];

    cells[5 * WIDTH + 10] = true;
    cells[5 * WIDTH + 11] = true;
    cells[5 * WIDTH + 12] = true;

    cells[50 * WIDTH + 50] = true;
    cells[51 * WIDTH + 51] = true;
    cells[52 * WIDTH + 49] = true;
    cells[52 * WIDTH + 50] = true;
    cells[52 * WIDTH + 51] = true;

    // ID of the Wakeup which means we should update the board
    let mut update_id: Option<u32> = None;

    fb.glutin_handle_basic_input(&mut event_loop, |fb, input| {
        // We're going to use wakeups to update the grid
        input.wait = true;

        if update_id.is_none() {
            update_id = Some(input.schedule_wakeup(Instant::now() + Duration::from_millis(500)))
        } else if let Some(mut wakeup) = input.wakeup {
            if Some(wakeup.id) == update_id {
                // Time to update our grid
                calculate_neighbors(&mut cells, &mut neighbors);
                make_some_babies(&mut cells, &mut neighbors);
                fb.update_buffer(&cells);

                // Reschedule another update
                wakeup.when = Instant::now() + Duration::from_millis(
                    if input.key_is_down(VirtualKeyCode::LShift) {
                        TURBO_SPEED
                    } else {
                        NORMAL_SPEED
                    }
                );

                input.reschedule_wakeup(wakeup);
            }

            // We will get called again after all wakeups are handled
            return true;
        }

        if input.key_is_down(VirtualKeyCode::Escape) {
            return false;
        }

        if input.mouse_is_down(MouseButton::Left) || input.mouse_is_down(MouseButton::Right) {
            // Mouse was pressed
            let (x, y) = input.mouse_pos;
            let x = x.min(WIDTH as f64 - 0.0001).max(0.0).floor() as usize;
            let y = y.min(HEIGHT as f64 - 0.0001).max(0.0).floor() as usize;
            cells[y * WIDTH + x] = input.mouse_is_down(MouseButton::Left);
            fb.update_buffer(&cells);
            // Give the user extra time to make something pretty each time they click
            if !input.key_is_down(VirtualKeyCode::LShift) {
                input.adjust_wakeup(update_id.unwrap(), Wakeup::after_millis(2000));
            }
        }

        // TODO support right shift. Probably by querying modifiers somehow. (modifiers support)
        if input.key_pressed(VirtualKeyCode::LShift) {
            // immediately update
            input.adjust_wakeup(update_id.unwrap(), Wakeup::after_millis(0));
        } else if input.key_released(VirtualKeyCode::LShift) {
            // immediately stop updating
            input.adjust_wakeup(update_id.unwrap(), Wakeup::after_millis(NORMAL_SPEED));
        }

        true
    });
}

pub fn use_vertex_shader(&mut self, source: &str)

pub fn use_fragment_shader(&mut self, source: &str)

Examples found in repository

examples/custom_shaders.rs (line 118)

fn main() {
    let width = 800.0;
    let height = 600.0;

    let (mut event_loop, mut fb) = mini_gl_fb::gotta_go_fast("Hello shaders!", width, height);

    let mut buffer = vec![[128u8, 0, 0, 255]; (width * height) as usize];
    // let's write a red line into the buffer roughly along the diagonal (misses many pixels)
    for i in 0..100 {
        let j = i as f64 / 100.0;
        let index = (width * j * (height + 1.0)).floor() as usize;
        buffer[index] = [255, 0, 0, 255];
    }

    // Let's keep using the default vertex shader
    // fb.internal.use_vertex_shader(...);
    fb.internal.fb.use_geometry_shader(GEOMETRY_SOURCE);
    fb.internal.fb.use_fragment_shader(FRAGMENT_SOURCE);

    fb.update_buffer(&buffer);

    fb.persist_and_redraw(&mut event_loop, true);
}

pub fn use_post_process_shader(&mut self, source: &str)

pub fn use_geometry_shader(&mut self, source: &str)

Examples found in repository

examples/custom_shaders.rs (line 117)

fn main() {
    let width = 800.0;
    let height = 600.0;

    let (mut event_loop, mut fb) = mini_gl_fb::gotta_go_fast("Hello shaders!", width, height);

    let mut buffer = vec![[128u8, 0, 0, 255]; (width * height) as usize];
    // let's write a red line into the buffer roughly along the diagonal (misses many pixels)
    for i in 0..100 {
        let j = i as f64 / 100.0;
        let index = (width * j * (height + 1.0)).floor() as usize;
        buffer[index] = [255, 0, 0, 255];
    }

    // Let's keep using the default vertex shader
    // fb.internal.use_vertex_shader(...);
    fb.internal.fb.use_geometry_shader(GEOMETRY_SOURCE);
    fb.internal.fb.use_fragment_shader(FRAGMENT_SOURCE);

    fb.update_buffer(&buffer);

    fb.persist_and_redraw(&mut event_loop, true);
}

pub fn use_grayscale_shader(&mut self)

pub fn change_buffer_format<T: ToGlType>(&mut self, format: BufferFormat)

pub fn resize_buffer(&mut self, buffer_width: u32, buffer_height: u32)

Examples found in repository

examples/multi_window.rs (line 118)

    fn resize(&mut self, new_size: LogicalSize<u32>) {
        let mut new_buffer = vec![self.bg; new_size.width as usize * new_size.height as usize];

        if self.buffer_size.width > 0 {
            // use rchunks for inverted y
            for (old_line, new_line) in self.buffer.chunks_exact(self.buffer_size.width as usize)
                .zip(new_buffer.chunks_exact_mut(new_size.width as usize)) {
                if old_line.len() <= new_line.len() {
                    new_line[0..old_line.len()].copy_from_slice(old_line)
                } else {
                    new_line.copy_from_slice(&old_line[0..new_line.len()])
                }
            }
        }

        self.buffer = new_buffer;
        self.buffer_size = new_size;
        self.breakout.fb.resize_buffer(new_size.width, new_size.height);
    }

pub fn resize_viewport(&mut self, width: u32, height: u32)

Examples found in repository

examples/multi_window.rs (line 217)

    fn handle_event(&mut self, event: &Event<()>) -> bool {
        match *event {
            Event::WindowEvent {
                window_id: id,
                event: WindowEvent::CloseRequested,
                ..
            } if self.matches_id(id) => {
                return false;
            }
            Event::WindowEvent {
                window_id: id,
                event: WindowEvent::KeyboardInput {
                    input: KeyboardInput {
                        virtual_keycode: Some(VirtualKeyCode::Escape),
                        state: ElementState::Pressed,
                        ..
                    },
                    ..
                },
                ..
            } if self.matches_id(id) => {
                if let Some(_) = self.window().fullscreen() {
                    self.window().set_fullscreen(None);
                } else {
                    return false;
                }
            }
            Event::RedrawRequested(id) if self.matches_id(id) => {
                unsafe { self.breakout.make_current().unwrap(); }
                self.redraw();
            }
            Event::WindowEvent {
                window_id: id,
                event: WindowEvent::Resized(size),
                ..
            } if self.matches_id(id) => {
                unsafe { self.breakout.make_current().unwrap(); }
                self.breakout.fb.resize_viewport(size.width, size.height);
                self.resize(size.to_logical(self.window().scale_factor() * SCALE_FACTOR));
                self.request_redraw();
            }
            Event::WindowEvent {
                window_id: id,
                event: WindowEvent::MouseInput {
                    button: MouseButton::Left,
                    state,
                    ..
                },
                ..
            } if self.matches_id(id) => {
                self.mouse_state = state;
                self.line_start = None;
            }
            Event::WindowEvent {
                window_id: id,
                event: WindowEvent::CursorMoved {
                    position,
                    ..
                },
                ..
            } if self.matches_id(id) => {
                if self.mouse_state == ElementState::Pressed {
                    let inner_size = self.window().inner_size();
                    let position = LogicalPosition::new(
                        ((position.x / inner_size.width as f64) * self.buffer_size.width as f64).floor(),
                        ((position.y / inner_size.height as f64) * self.buffer_size.height as f64).floor()
                    ).cast::<i32>();

                    if let Some(line_start) = self.line_start {
                        self.plot_line(line_start, position);
                    } else {
                        self.plot(position);
                    }

                    self.line_start = Some(position);

                    self.request_redraw();
                }
            }
            _ => {}
        }

        true
    }

pub fn redraw(&mut self)

Examples found in repository

examples/glutin_breakout.rs (line 57)

fn main() {
    let (event_loop, mut fb) = mini_gl_fb::gotta_go_fast("Hello world!", 800.0, 600.0);
    let mut buffer = vec![[128u8, 0, 0, 255]; 800 * 600];
    fb.update_buffer(&buffer);

    let GlutinBreakout {
        context,
        mut fb,
    } = fb.glutin_breakout();

    let mut mouse_down = false;

    event_loop.run(move |event, _, flow| {
        match event {
            Event::WindowEvent { event: WindowEvent::CloseRequested, .. } => {
                *flow = ControlFlow::Exit;
            }
            Event::WindowEvent { event: KeyboardInput { input, .. }, .. } => {
                if let Some(k) = input.virtual_keycode {
                    if k == VirtualKeyCode::Escape && input.state == ElementState::Pressed {
                        *flow = ControlFlow::Exit;
                    }
                }
            }
            Event::WindowEvent { event: WindowEvent::Resized(size), .. } => {
                context.resize(size);
                context.window().request_redraw();
            }
            Event::WindowEvent { event: WindowEvent::CursorMoved { position, .. }, .. } => {
                let (x, y) = position.to_logical::<f64>(context.window().scale_factor()).into();
                println!("({}, {})", x, y);
                let mouse_x = min(max(x, 0), 800 - 1);
                let mouse_y = min(max(fb.buffer_size.height - y, 0), 600 - 1);
                if mouse_down {
                    buffer[(mouse_x + mouse_y * 800) as usize] = [64, 128, 255, 255];
                    fb.update_buffer(&buffer);
                    context.window().request_redraw();
                }
            }
            Event::WindowEvent { event: WindowEvent::MouseInput { state, .. }, .. } => {
                if state == ElementState::Pressed {
                    mouse_down = true;
                } else {
                    mouse_down = false;
                }
            }
            Event::RedrawRequested(_) => {
                fb.redraw();
                context.swap_buffers().unwrap();
            }
            _ => {}
        }
    });
}

pub fn draw<F: FnOnce(&Framebuffer)>(&mut self, f: F)

Draw the quad to the active context. Optionally issue other commands after binding everything but before drawing it.

You probably want redraw (equivalent to .draw(|_| {})).

pub fn relink_program(&mut self)

Trait Implementations

impl Debug for Framebuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.