Struct BltDrawTarget 

pub struct BltDrawTarget<'proto> { /* private fields */ }

Available on crate feature alloc only.

A DrawTarget using only BLT routines to write to the framebuffer.

Works on all UEFI implementations providing the GOP protocol—UEFI Specification 2.11 § 12.9.2; BLT is required to be provided, but drivers/hardware are allowed to not provide direct framebuffer access. However, it requires UEFI boot services to be active as it makes boot services function calls.

Offers single- and double-buffered modes, defaulting to single-buffer mode. In single-buffered mode, drawing is transferred to the framebuffer immediately. In double-buffered mode, drawing is saved to an internal back-buffer and are only transferred to the primary buffer after being explicitly committed.

Note that even in single-buffered mode, an internal framebuffer is still allocated for optimizing draw operations. This framebuffer is kept in sync with any drawing operations performed, so the canvas state stays consistent even when switching between single- and double-buffered mode.

In double-buffered mode, rudimentary damage tracking is performed to minimize the region that gets transferred to the primary buffer. In double-buffered mode, any untransferred changes are automatically transferred when the BltDrawTarget is dropped. Note that the routines in the DrawTarget implementation will never return an error in double-buffered mode and can be considered infallible; as only BltDrawTarget::commit calls UEFI routines.

Examples

use embedded_graphics_gop::BltDrawTarget;
use uefi::{prelude::*, proto::console::gop::GraphicsOutput};

// Get the first available handle for the GOP.
let handle = boot::get_handle_for_protocol::<GraphicsOutput>().unwrap();
// Open the protocol in exclusive mode (exclusive mode is for applications, other modes are
// intended for drivers)
let mut protocol = boot::open_protocol_exclusive::<GraphicsOutput>(handle).unwrap();
// Configure protocol here if desired, for example
let mode = protocol.modes().find(|m| m.info().resolution() == (800, 600)).unwrap();
protocol.set_mode(&mode).unwrap();

// Create the draw target utilizing the configured protocol.
let mut target = BltDrawTarget::new(&mut protocol).unwrap();
// Make it double-buffered
target.double_buffer(true).unwrap();

// ...draw on it...

// Transfer changes to the framebuffer
target.commit().unwrap();

Implementations

impl<'proto> BltDrawTarget<'proto>

pub fn new(protocol: &'proto mut ScopedProtocol<GraphicsOutput>) -> Result<Self>

Create a new BltDrawTarget given a GOP protocol handle.

Fills the framebuffer and back-buffer with black.

Note that one should configure the desired graphics mode for the protocol prior to creating the BltDrawTarget.

Errors

Returns a uefi::Error if the BLT operation to black out the framebuffer fails.

Panics

• If the reported resolution of the current graphics mode is ≥ 2^31 - 1 in either dimension.
• If the reported number of pixels addressed by the current graphics mode (width×height) exceeds isize::MAX / 4 (i.e. largest possible size for an array of u32s).

Examples found in repository

examples/double_buffered.rs (line 37)

fn main() -> Status {
	helpers::init().unwrap();

	let handle =
		boot::get_handle_for_protocol::<GraphicsOutput>().expect("Unable to get GOP handle");
	let mut gop =
		boot::open_protocol_exclusive::<GraphicsOutput>(handle).expect("Unable to open GOP handle");

	let mode_800x600 = gop
		.modes()
		// one of the standard modes, although some systems may only provide 640×480
		.find(|m| m.info().resolution() == (800, 600))
		.expect("Unable to find 800x600 video mode");
	gop.set_mode(&mode_800x600)
		.expect("Couldn't switch to 800x600 video mode");

	let mut target = BltDrawTarget::new(&mut gop).expect("unable to open BLTDrawTarget");
	target.double_buffer(true).expect("no errors possible");

	let center = Point::new(400, 300);

	let white_fill = PrimitiveStyle::with_fill(Rgb888::WHITE);
	let (red_outline, green_outline, blue_outline) = {
		let base = PrimitiveStyleBuilder::new().stroke_width(10);
		(
			base.stroke_color(Rgb888::RED).build(),
			base.stroke_color(Rgb888::GREEN).build(),
			base.stroke_color(Rgb888::BLUE).build(),
		)
	};

	Circle::with_center(center, 500)
		.into_styled(red_outline)
		.draw(&mut target)
		.expect("infallible");

	Circle::with_center(center, 400)
		.into_styled(green_outline)
		.draw(&mut target)
		.expect("infallible");

	target.commit().expect("failed to copy to framebuffer");

	// Would cover circles
	Rectangle::with_center(Point::new(50, 50), Size::new(700, 500))
		.into_styled(white_fill)
		.draw(&mut target)
		.expect("infallible");

	target
		.discard_changes()
		.expect("failed to reset from framebuffer");

	Circle::with_center(center, 300)
		.into_styled(blue_outline)
		.draw(&mut target)
		.expect("infallible");

	// should auto-commit
	drop(target);

	boot::stall(Duration::from_secs(10));
	runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
}

examples/ball.rs (line 37)

fn main() -> Status {
	helpers::init().unwrap();

	let handle =
		boot::get_handle_for_protocol::<GraphicsOutput>().expect("Unable to get GOP handle");
	let mut gop =
		boot::open_protocol_exclusive::<GraphicsOutput>(handle).expect("Unable to open GOP handle");

	let mode_800x600 = gop
		.modes()
		// one of the standard modes, although some systems may only provide 640×480
		.find(|m| m.info().resolution() == (800, 600))
		.expect("Unable to find 800x600 video mode");
	gop.set_mode(&mode_800x600)
		.expect("Couldn't switch to 800x600 video mode");

	let mut target = BltDrawTarget::new(&mut gop).expect("unable to open BLTDrawTarget");

	target
		.double_buffer(true)
		.expect("failed to set double buffer");

	let red_fill = PrimitiveStyle::with_fill(Rgb888::RED);
	let blue_fill = PrimitiveStyle::with_fill(Rgb888::BLUE);

	let mut ball_pos = Point::new(200, 300);
	let mut ball_dir = Point::new(5, 5);
	let ball_size = 10;
	for _ in 0..1000 {
		// Drawing over old position with blue instead of black to leave trail behind and
		// demonstrate more colors
		Rectangle::new(ball_pos, Size::new(ball_size, ball_size))
			.into_styled(blue_fill)
			.draw(&mut target)
			.expect("infallible");

		ball_pos += ball_dir;

		if ball_pos.x <= 0 {
			ball_pos.x = 0;
			ball_dir.x = -ball_dir.x;
		} else if ball_pos.x >= 790 {
			ball_pos.x = 790;
			ball_dir.x = -ball_dir.x;
		}
		if ball_pos.y <= 0 {
			ball_pos.y = 0;
			ball_dir.y = -ball_dir.y;
		} else if ball_pos.y >= 590 {
			ball_pos.y = 590;
			ball_dir.y = -ball_dir.y;
		}

		Circle::new(ball_pos, ball_size)
			.into_styled(red_fill)
			.draw(&mut target)
			.expect("infallible");

		// In real code would probably want to set up UEFI timer and commit in there?
		target
			.commit()
			.expect("unable to commit changes to framebuffer");
		boot::stall(Duration::from_millis(10));
	}

	runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
}

pub fn double_buffer(&mut self, double_buffer: bool) -> Result<()>

Enable or disable the double-buffering mode.

If current in double-buffered mode and it is being disabled, then the buffer contents will be committed.

Errors

Returns a uefi::Error if disabling double-buffering and an error occured when committing current contents.

Examples found in repository

examples/double_buffered.rs (line 38)

fn main() -> Status {
	helpers::init().unwrap();

	let handle =
		boot::get_handle_for_protocol::<GraphicsOutput>().expect("Unable to get GOP handle");
	let mut gop =
		boot::open_protocol_exclusive::<GraphicsOutput>(handle).expect("Unable to open GOP handle");

	let mode_800x600 = gop
		.modes()
		// one of the standard modes, although some systems may only provide 640×480
		.find(|m| m.info().resolution() == (800, 600))
		.expect("Unable to find 800x600 video mode");
	gop.set_mode(&mode_800x600)
		.expect("Couldn't switch to 800x600 video mode");

	let mut target = BltDrawTarget::new(&mut gop).expect("unable to open BLTDrawTarget");
	target.double_buffer(true).expect("no errors possible");

	let center = Point::new(400, 300);

	let white_fill = PrimitiveStyle::with_fill(Rgb888::WHITE);
	let (red_outline, green_outline, blue_outline) = {
		let base = PrimitiveStyleBuilder::new().stroke_width(10);
		(
			base.stroke_color(Rgb888::RED).build(),
			base.stroke_color(Rgb888::GREEN).build(),
			base.stroke_color(Rgb888::BLUE).build(),
		)
	};

	Circle::with_center(center, 500)
		.into_styled(red_outline)
		.draw(&mut target)
		.expect("infallible");

	Circle::with_center(center, 400)
		.into_styled(green_outline)
		.draw(&mut target)
		.expect("infallible");

	target.commit().expect("failed to copy to framebuffer");

	// Would cover circles
	Rectangle::with_center(Point::new(50, 50), Size::new(700, 500))
		.into_styled(white_fill)
		.draw(&mut target)
		.expect("infallible");

	target
		.discard_changes()
		.expect("failed to reset from framebuffer");

	Circle::with_center(center, 300)
		.into_styled(blue_outline)
		.draw(&mut target)
		.expect("infallible");

	// should auto-commit
	drop(target);

	boot::stall(Duration::from_secs(10));
	runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
}

examples/ball.rs (line 40)

fn main() -> Status {
	helpers::init().unwrap();

	let handle =
		boot::get_handle_for_protocol::<GraphicsOutput>().expect("Unable to get GOP handle");
	let mut gop =
		boot::open_protocol_exclusive::<GraphicsOutput>(handle).expect("Unable to open GOP handle");

	let mode_800x600 = gop
		.modes()
		// one of the standard modes, although some systems may only provide 640×480
		.find(|m| m.info().resolution() == (800, 600))
		.expect("Unable to find 800x600 video mode");
	gop.set_mode(&mode_800x600)
		.expect("Couldn't switch to 800x600 video mode");

	let mut target = BltDrawTarget::new(&mut gop).expect("unable to open BLTDrawTarget");

	target
		.double_buffer(true)
		.expect("failed to set double buffer");

	let red_fill = PrimitiveStyle::with_fill(Rgb888::RED);
	let blue_fill = PrimitiveStyle::with_fill(Rgb888::BLUE);

	let mut ball_pos = Point::new(200, 300);
	let mut ball_dir = Point::new(5, 5);
	let ball_size = 10;
	for _ in 0..1000 {
		// Drawing over old position with blue instead of black to leave trail behind and
		// demonstrate more colors
		Rectangle::new(ball_pos, Size::new(ball_size, ball_size))
			.into_styled(blue_fill)
			.draw(&mut target)
			.expect("infallible");

		ball_pos += ball_dir;

		if ball_pos.x <= 0 {
			ball_pos.x = 0;
			ball_dir.x = -ball_dir.x;
		} else if ball_pos.x >= 790 {
			ball_pos.x = 790;
			ball_dir.x = -ball_dir.x;
		}
		if ball_pos.y <= 0 {
			ball_pos.y = 0;
			ball_dir.y = -ball_dir.y;
		} else if ball_pos.y >= 590 {
			ball_pos.y = 590;
			ball_dir.y = -ball_dir.y;
		}

		Circle::new(ball_pos, ball_size)
			.into_styled(red_fill)
			.draw(&mut target)
			.expect("infallible");

		// In real code would probably want to set up UEFI timer and commit in there?
		target
			.commit()
			.expect("unable to commit changes to framebuffer");
		boot::stall(Duration::from_millis(10));
	}

	runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
}

pub fn get_double_buffer(&self) -> bool

Return whether double-buffering mode is currently enabled.

pub fn commit(&mut self) -> Result<()>

Transfer the backbuffer contents to the primary buffer.

If in single-buffering mode, has no effect.

Errors

Returns a uefi::Error if an error occurs while transferring the backbuffer. Will never return an error in single-buffered mode.

Examples found in repository

examples/double_buffered.rs (line 62)

fn main() -> Status {
	helpers::init().unwrap();

	let handle =
		boot::get_handle_for_protocol::<GraphicsOutput>().expect("Unable to get GOP handle");
	let mut gop =
		boot::open_protocol_exclusive::<GraphicsOutput>(handle).expect("Unable to open GOP handle");

	let mode_800x600 = gop
		.modes()
		// one of the standard modes, although some systems may only provide 640×480
		.find(|m| m.info().resolution() == (800, 600))
		.expect("Unable to find 800x600 video mode");
	gop.set_mode(&mode_800x600)
		.expect("Couldn't switch to 800x600 video mode");

	let mut target = BltDrawTarget::new(&mut gop).expect("unable to open BLTDrawTarget");
	target.double_buffer(true).expect("no errors possible");

	let center = Point::new(400, 300);

	let white_fill = PrimitiveStyle::with_fill(Rgb888::WHITE);
	let (red_outline, green_outline, blue_outline) = {
		let base = PrimitiveStyleBuilder::new().stroke_width(10);
		(
			base.stroke_color(Rgb888::RED).build(),
			base.stroke_color(Rgb888::GREEN).build(),
			base.stroke_color(Rgb888::BLUE).build(),
		)
	};

	Circle::with_center(center, 500)
		.into_styled(red_outline)
		.draw(&mut target)
		.expect("infallible");

	Circle::with_center(center, 400)
		.into_styled(green_outline)
		.draw(&mut target)
		.expect("infallible");

	target.commit().expect("failed to copy to framebuffer");

	// Would cover circles
	Rectangle::with_center(Point::new(50, 50), Size::new(700, 500))
		.into_styled(white_fill)
		.draw(&mut target)
		.expect("infallible");

	target
		.discard_changes()
		.expect("failed to reset from framebuffer");

	Circle::with_center(center, 300)
		.into_styled(blue_outline)
		.draw(&mut target)
		.expect("infallible");

	// should auto-commit
	drop(target);

	boot::stall(Duration::from_secs(10));
	runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
}

examples/ball.rs (line 81)

fn main() -> Status {
	helpers::init().unwrap();

	let handle =
		boot::get_handle_for_protocol::<GraphicsOutput>().expect("Unable to get GOP handle");
	let mut gop =
		boot::open_protocol_exclusive::<GraphicsOutput>(handle).expect("Unable to open GOP handle");

	let mode_800x600 = gop
		.modes()
		// one of the standard modes, although some systems may only provide 640×480
		.find(|m| m.info().resolution() == (800, 600))
		.expect("Unable to find 800x600 video mode");
	gop.set_mode(&mode_800x600)
		.expect("Couldn't switch to 800x600 video mode");

	let mut target = BltDrawTarget::new(&mut gop).expect("unable to open BLTDrawTarget");

	target
		.double_buffer(true)
		.expect("failed to set double buffer");

	let red_fill = PrimitiveStyle::with_fill(Rgb888::RED);
	let blue_fill = PrimitiveStyle::with_fill(Rgb888::BLUE);

	let mut ball_pos = Point::new(200, 300);
	let mut ball_dir = Point::new(5, 5);
	let ball_size = 10;
	for _ in 0..1000 {
		// Drawing over old position with blue instead of black to leave trail behind and
		// demonstrate more colors
		Rectangle::new(ball_pos, Size::new(ball_size, ball_size))
			.into_styled(blue_fill)
			.draw(&mut target)
			.expect("infallible");

		ball_pos += ball_dir;

		if ball_pos.x <= 0 {
			ball_pos.x = 0;
			ball_dir.x = -ball_dir.x;
		} else if ball_pos.x >= 790 {
			ball_pos.x = 790;
			ball_dir.x = -ball_dir.x;
		}
		if ball_pos.y <= 0 {
			ball_pos.y = 0;
			ball_dir.y = -ball_dir.y;
		} else if ball_pos.y >= 590 {
			ball_pos.y = 590;
			ball_dir.y = -ball_dir.y;
		}

		Circle::new(ball_pos, ball_size)
			.into_styled(red_fill)
			.draw(&mut target)
			.expect("infallible");

		// In real code would probably want to set up UEFI timer and commit in there?
		target
			.commit()
			.expect("unable to commit changes to framebuffer");
		boot::stall(Duration::from_millis(10));
	}

	runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
}

pub fn discard_changes(&mut self) -> Result<()>

Discard any uncommitted changes when in double-buffered mode.

The damaged portion of the backbuffer will have its contents overwritten with the current state of the primary buffer, truly discarding any changes since the last commit.

Errors

Returns a uefi::Error if an error occurs while reading the primary buffer data into the backbuffer.

Examples found in repository

examples/double_buffered.rs (line 71)

fn main() -> Status {
	helpers::init().unwrap();

	let handle =
		boot::get_handle_for_protocol::<GraphicsOutput>().expect("Unable to get GOP handle");
	let mut gop =
		boot::open_protocol_exclusive::<GraphicsOutput>(handle).expect("Unable to open GOP handle");

	let mode_800x600 = gop
		.modes()
		// one of the standard modes, although some systems may only provide 640×480
		.find(|m| m.info().resolution() == (800, 600))
		.expect("Unable to find 800x600 video mode");
	gop.set_mode(&mode_800x600)
		.expect("Couldn't switch to 800x600 video mode");

	let mut target = BltDrawTarget::new(&mut gop).expect("unable to open BLTDrawTarget");
	target.double_buffer(true).expect("no errors possible");

	let center = Point::new(400, 300);

	let white_fill = PrimitiveStyle::with_fill(Rgb888::WHITE);
	let (red_outline, green_outline, blue_outline) = {
		let base = PrimitiveStyleBuilder::new().stroke_width(10);
		(
			base.stroke_color(Rgb888::RED).build(),
			base.stroke_color(Rgb888::GREEN).build(),
			base.stroke_color(Rgb888::BLUE).build(),
		)
	};

	Circle::with_center(center, 500)
		.into_styled(red_outline)
		.draw(&mut target)
		.expect("infallible");

	Circle::with_center(center, 400)
		.into_styled(green_outline)
		.draw(&mut target)
		.expect("infallible");

	target.commit().expect("failed to copy to framebuffer");

	// Would cover circles
	Rectangle::with_center(Point::new(50, 50), Size::new(700, 500))
		.into_styled(white_fill)
		.draw(&mut target)
		.expect("infallible");

	target
		.discard_changes()
		.expect("failed to reset from framebuffer");

	Circle::with_center(center, 300)
		.into_styled(blue_outline)
		.draw(&mut target)
		.expect("infallible");

	// should auto-commit
	drop(target);

	boot::stall(Duration::from_secs(10));
	runtime::reset(ResetType::SHUTDOWN, Status::SUCCESS, None);
}

pub fn discard_changes_no_reset(&mut self)

When in double-buffered mode, discard any uncommitted changes without resetting the backbuffer contents.

Note that this leaves the backbuffer untouched but marked as not needing to be transferred. This will make future drawing and committing very inconsistent and should likely only be used to discard changes prior to dropping the BltDrawTarget.

Trait Implementations

impl<'proto> Debug for BltDrawTarget<'proto>

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

Formats the value using the given formatter.

impl DrawTarget for BltDrawTarget<'_>

type Color = Rgb888

The pixel color type the targetted display supports.

type Error = Error

Error type to return when a drawing operation fails.

fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>

where I: IntoIterator<Item = Pixel<Self::Color>>,

Draw individual pixels to the display without a defined order.

fn fill_solid( &mut self, area: &Rectangle, color: Self::Color, ) -> Result<(), Self::Error>

Fill a given area with a solid color.

fn fill_contiguous<I>( &mut self, area: &Rectangle, colors: I, ) -> Result<(), Self::Error>

where I: IntoIterator<Item = Self::Color>,

Fill a given area with an iterator providing a contiguous stream of pixel colors.

fn clear(&mut self, color: Self::Color) -> Result<(), Self::Error>

Fill the entire display with a solid color.

impl Drop for BltDrawTarget<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl OriginDimensions for BltDrawTarget<'_>

fn size(&self) -> Size

Returns the size of the bounding box.