Struct FbDrawTarget 

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

A single-buffered framebuffer DrawTarget.

See the module-level documentation for more information on the framebuffer DrawTargets.

Examples

use embedded_graphics_gop::fb::FbDrawTarget;
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 = FbDrawTarget::new(&mut protocol);

// ...draw on it...

Implementations

impl<'proto> FbDrawTarget<'proto>

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

Create a new FbDrawTarget given a GOP protocol handle.

Fills the framebuffer with black.

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

Panics

• If the pixel format for the current graphics mode is not PixelFormat::Rgb or PixelFormat::Bgr.
• 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).
• If the framebuffer pointer returned from UEFI is not aligned to align_of::<u32>() (typically four bytes).

Examples found in repository

examples/modes.rs (line 55)

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 formats = Vec::new();
	for (idx, mode) in gop.modes().enumerate() {
		let mode = mode.info();
		let (width, height) = mode.resolution();
		formats.push(alloc::format!(
			"Mode {:02}: resolution {}x{}, pixel format {:?}, stride {}",
			idx,
			width,
			height,
			mode.pixel_format(),
			mode.stride(),
		));
	}

	let mut target = FbDrawTarget::new(&mut gop);

	let font = MonoTextStyle::new(&FONT_10X20, Rgb888::WHITE);

	let mut pos = Point::new(90, 20);
	for format in &formats {
		Text::new(format, pos, font)
			.draw(&mut target)
			.expect("unable to draw text");
		pos.y += 15;
	}

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

impl FbDrawTarget<'static>

pub unsafe fn new_free_lifetime( protocol: &mut ScopedProtocol<GraphicsOutput>, ) -> Self

Equivalent to FbDrawTarget::new, but allows the FbDrawTarget to outlive the input ScopedProtocol.

Allows preserving the framebuffer after closing the GOP handle or even after exiting UEFI boot services (with caveats). See the module-level documentation.

Other than breaking the input protocol lifetime, precisely equivalent to the new method in behavior.

Safety

This technically violates the requirements specified in FrameBuffer, as the pointer outlives the FrameBuffer that created it (in fact, this immediately discards the Framebuffer so it violates the specified safety requirements even before the protocol gets dropped). However, per the implementation in uefi-rs 0.36.1, it directly passes through the pointer given by the UEFI implementation, so the rules for handling it correspond to how it could be handled in C. The implementation follows all the other safety requirements specified by FrameBuffer.

Re-opening a specific GOP handle may invalidate all previous framebuffer pointers, and changing the graphics mode will almost certainly invalidate them.

The ability to preserve the framebuffer pointer after exiting boot services is not specified at all in the UEFI Specification as of version 2.11. As such, it is implementation-specific. One must also ensure the system memory map remains set up properly to keep the pointer pointing to the same physical address.

Examples found in repository

examples/framebuffer_free_lifetime.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");

	// SAFETY: see rules on `FbDrawTarget::new_free_lifetime` for caveats about invalidation,
	// implementation-specific considerations, and complications with exiting boot services.
	//
	// This example does work on QEMU and should work on most real desktop implementations.
	let mut target = unsafe { FbDrawTarget::new_free_lifetime(&mut gop) };
	drop(gop);
	// SAFETY: this is completely disregarding almost everything one needs to do after exiting boot
	// services, just for demonstration purposes.  The example still works after uncommenting this.
	// unsafe { drop(uefi::boot::exit_boot_services(None)) };

	target
		.fill_solid(
			&Rectangle::new(Point::zero(), Size::new(266, 600)),
			Rgb888::RED,
		)
		.expect("infallible");
	target
		.fill_solid(
			&Rectangle::new(Point::new(266, 0), Size::new(267, 600)),
			Rgb888::GREEN,
		)
		.expect("infallible");
	target
		.fill_solid(
			&Rectangle::new(Point::new(533, 0), Size::new(267, 600)),
			Rgb888::BLUE,
		)
		.expect("infallible");

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

Trait Implementations

impl<'proto> Debug for FbDrawTarget<'proto>

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

Formats the value using the given formatter.

impl DrawTarget for FbDrawTarget<'_>

type Color = Rgb888

The pixel color type the targetted display supports.

type Error = Infallible

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_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 fill_solid( &mut self, area: &Rectangle, color: Self::Color, ) -> Result<(), Self::Error>

Fill a given area with a solid color.

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

Fill the entire display with a solid color.

impl OriginDimensions for FbDrawTarget<'_>

fn size(&self) -> Size

Returns the size of the bounding box.