embedded_graphics_gop/

fb.rs

// Copyright (c) 2025 nytpu <alex [at] nytpu.com>
// SPDX-License-Identifier: MPL-2.0
// For more license details, see LICENSE or <https://www.mozilla.org/en-US/MPL/2.0/>.

//! [`DrawTarget`s][DrawTarget] directly writing to the hardware framebuffer.
//!
//! These rely on the GPU's device driver to expose direct framebuffer access, which is very common
//! (near-universal?) but not strictly required by the UEFI specification.  However, they allow a
//! potentially much more efficient implementation, especially in single-buffered mode.
//!
//! Most UEFI graphics drivers also keep the framebuffer valid after exiting the UEFI boot
//! services, which is the only way to perform graphics after exiting boot services without
//! including full GPU-specific drivers (or using VGA, or using VESA BIOS Extensions via a CSM; but
//! those are even more limited than the GOP).  Note there are numerous safety and compatibility
//! caveats when doing this, see [`FbDrawTarget::new_free_lifetime`].
//!
//! Currently only support for [`PixelFormat::Rgb`] and [`PixelFormat::Bgr`] framebuffers is
//! implemented; [framebuffers with custom pixel formats][uefi::proto::console::gop::PixelBitmask]
//! cannot be used.  Obviously [`PixelFormat::BltOnly`] framebuffers cannot be used.
//!
//! For [`PixelFormat::Bgr`], these directly writes to the framebuffer (that's correct, even though
//! the input format is [`Rgb888`]; embedded-graphics uses names that are backwards from how
//! everyone else refers to pixel formats), but it has to perform color conversion for every pixel
//! if the implementation framebuffer uses [`PixelFormat::Rgb`].  Although the color conversion
//! performed here should be more efficient than using the generic
//! [`embedded_graphics::draw_target::ColorConverted`][ColorConverted]
//! because it only needs to do a byte swap between two specific formats rather than needing to
//! support all the disparate color formats supported by embedded-graphics.
//!
//! [ColorConverted]: https://docs.rs/embedded-graphics/0.8.1/embedded_graphics/draw_target/struct.ColorConverted.html

use core::convert::Infallible;
use embedded_graphics_core::{draw_target::DrawTarget, pixelcolor::Rgb888, prelude::*};
use uefi::{
	boot::ScopedProtocol,
	proto::console::gop::{FrameBuffer, GraphicsOutput, PixelFormat},
};

#[cfg(feature = "alloc")]
use alloc::{vec, vec::Vec};
#[cfg(feature = "alloc")]
use core::{mem::ManuallyDrop, ptr};
#[cfg(feature = "alloc")]
use embedded_graphics_core::primitives::Rectangle;

#[inline]
fn color_to_storage(pixel_format: PixelFormat, color: Rgb888) -> u32 {
	// Seems backwards because embedded-graphics uses completely backwards names for its pixel
	// formats.  What it calls "RGB" puts red in the *most* significant byte (of a conceptual u24),
	// while everything else would call that BGR since blue is the least-significant (and also
	// comes first in a linear data stream).
	if pixel_format == PixelFormat::Bgr {
		color.into_storage()
	} else {
		Rgb888::new(color.r(), color.g(), color.b()).into_storage()
	}
}

/// A single-buffered framebuffer [`DrawTarget`].
///
/// See [the module-level documentation][crate::fb] for more information on the framebuffer
/// `DrawTarget`s.
///
/// # Examples
///
/// ```no_run
/// 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...
/// ```
#[derive(Debug)]
pub struct FbDrawTarget<'proto> {
	/// Pointer to top-left pixel of the framebuffer
	framebuffer: *mut u32,
	/// Length of the framebuffer in elements
	size: isize,
	/// width in pixels.
	width: u32,
	/// height in pixels.
	height: u32,
	/// The stride, or number of pixels per scanline (must use this rather than resolution.0 when
	/// computing index into framebuffer)
	stride: isize,
	/// The pixel format for the underlying framebuffer
	pixel_format: PixelFormat,
	/// Saved framebuffer object to follow (stated) safety requirements for `framebuffer` pointer.
	/// Could really just use `PhantomData` for it but `FrameBuffer` does explicitly state that to
	/// be safe the pointer cannot outlive the *`FrameBuffer` object* (not the protocol handle) so
	/// just hold it here.  Not like the few bytes are a big deal since there will be at most one
	/// `FbDrawTarget` per display (and more likely one `FbDrawTarget` per GPU)
	_fb_obj: Option<FrameBuffer<'proto>>,
}

impl<'proto> FbDrawTarget<'proto> {
	/// 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 `u32`s).
	/// - If the framebuffer pointer returned from UEFI is not aligned to `align_of::<u32>()`
	///   (typically four bytes).
	#[expect(
		clippy::cast_possible_wrap,
		reason = "framebuffer size implicilty fits in isize given height*stride check"
	)]
	#[expect(
		clippy::cast_possible_truncation,
		reason = "width and height confirmed to fit in i32, stride implicitly fits in isize given height*stride fits in isize"
	)]
	pub fn new(protocol: &'proto mut ScopedProtocol<GraphicsOutput>) -> Self {
		let mode_info = protocol.current_mode_info();

		let pixel_format = mode_info.pixel_format();
		assert!(
			matches!(pixel_format, PixelFormat::Rgb | PixelFormat::Bgr),
			"Only RGB and BGR framebuffer pixel formats are supported."
		);

		let (width, height) = mode_info.resolution();
		assert!(
			i32::try_from(width).is_ok(),
			"reported output width {width} >= 2^32 - 1"
		);
		assert!(
			i32::try_from(height).is_ok(),
			"reported output height {height} >= 2^32 - 1"
		);

		let stride = mode_info.stride();
		assert!(
			stride
				.checked_mul(height)
				.and_then(|v| isize::try_from(v).ok())
				.is_some(),
			"height*stride exceeds isize::MAX"
		);

		let mut fb_obj = protocol.frame_buffer();
		let framebuffer = fb_obj.as_mut_ptr();
		// Should be fine even though it's allowed to return `isize::MAX` if the pointer "can't be
		// aligned": https://stackoverflow.com/a/71982312
		assert_eq!(
			framebuffer.align_offset(align_of::<u32>()),
			0,
			"framebuffer pointer not aligned to u32 boundary"
		);

		let fb_size = (fb_obj.size() / 4) as isize; // u32 length

		// Black out the framebuffer
		for i in 0..fb_size {
			// SAFETY: offset is always in bounds of `framebuffer` and should always fit in isize
			// given checks above (and in practice it certainly always will).  Destination is valid
			// and aligned per note and alignment check above.
			unsafe {
				framebuffer.offset(i).write_volatile(0);
			}
		}

		Self {
			framebuffer: framebuffer.cast(),
			size: fb_size,
			width: width as u32,
			height: height as u32,
			stride: stride as isize, // checked above implicitly
			pixel_format,
			_fb_obj: Some(fb_obj),
		}
	}
}

impl FbDrawTarget<'static> {
	/// 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][crate::fb].
	///
	/// 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.
	pub unsafe fn new_free_lifetime(protocol: &mut ScopedProtocol<GraphicsOutput>) -> Self {
		// Just clear owned Framebuffer referencing protocol
		Self {
			_fb_obj: None,
			..FbDrawTarget::new(protocol)
		}
	}
}

impl OriginDimensions for FbDrawTarget<'_> {
	fn size(&self) -> Size {
		Size::new(self.width, self.height)
	}
}

impl DrawTarget for FbDrawTarget<'_> {
	type Color = Rgb888;
	type Error = Infallible;

	#[expect(
		clippy::cast_possible_wrap,
		reason = "width and height confirmed to fit in i32 in constructor"
	)]
	fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>
	where
		I: IntoIterator<Item = Pixel<Self::Color>>,
	{
		let (width, height) = (self.width as i32, self.height as i32);
		for Pixel(Point { x, y }, color) in pixels {
			if (0..width).contains(&x) && (0..height).contains(&y) {
				let (x, y) = (x as isize, y as isize);
				// Always sound arithmetic when offsetting pointer?  I think so since stride*height
				// (i.e. one after last pixel) is always <=isize::MAX
				let offset = y * self.stride + x;
				if offset < self.size {
					let color = color_to_storage(self.pixel_format, color);

					// SAFETY:
					// `ptr::offset`: I believe the offset will always fit in an isize (and in
					// practice it certainly always will).  The offset is checked above to be
					// in-bounds of the framebuffer (and really checked twice, as the size is
					// implicitly encoded in the framebuffer's width and height in pixels).
					//
					// `ptr::write_volatile`: Destination is valid as per the offset above.  It
					// should always be aligned as the base alignment is verified in the
					// constructors and `ptr::offset` always computes in multiples of the pointer
					// type.
					unsafe {
						self.framebuffer.offset(offset).write_volatile(color);
					}
				}
			}
		}
		Ok(())
	}
}

// FIXME: really unhappy with the lack of range checks on integer conversions added to this
// implementation differing from `FbDrawTarget`
// FIXME: also really really don't like all the duplication with both `FbDrawTarget` and from
// `BltDrawTarget`

/// A double-buffered framebuffer [`DrawTarget`].
///
/// Rudimentary damage tracking is performed to minimize the region that gets copied to the primary
/// buffer.
///
/// Any untransferred changes are automatically transferred when the `FbDbDrawTarget` is dropped.
///
/// See [the module-level documentation][crate::fb] for more information on the framebuffer
/// `DrawTarget`s.
///
/// # Examples
///
/// ```no_run
/// use embedded_graphics_gop::fb::FbDbDrawTarget;
/// 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 = FbDbDrawTarget::new(&mut protocol);
///
/// // ...draw on it...
///
/// // Transfer changes to the framebuffer
/// target.commit();
/// ```
#[cfg(feature = "alloc")]
#[derive(Debug)]
pub struct FbDbDrawTarget<'proto> {
	framebuffer: *mut u32,
	/// Backbuffer.  Of same size as framebuffer (including stride)
	backbuffer: Vec<u32>,
	width: u32,
	height: u32,
	stride: isize,
	pixel_format: PixelFormat,
	damage: Rectangle,
	fb_obj: Option<FrameBuffer<'proto>>,
}

#[cfg(feature = "alloc")]
impl<'proto> FbDbDrawTarget<'proto> {
	/// Create a new `FbDbDrawTarget` given a GOP protocol handle.
	///
	/// Fills the framebuffer and backbuffer with black.
	///
	/// Note that one should configure the desired graphics mode for the protocol prior to creating
	/// the `FbDbDrawTarget`.
	///
	/// # Panics
	///
	/// Exactly the same as [`FbDrawTarget::new`].
	#[expect(
		clippy::cast_possible_wrap,
		clippy::cast_sign_loss,
		reason = "framebuffer size implicilty fits in isize and usize given height*stride check"
	)]
	#[expect(
		clippy::cast_possible_truncation,
		reason = "width and height confirmed to fit in i32, stride implicitly fits in isize given height*stride fits in isize"
	)]
	pub fn new(protocol: &'proto mut ScopedProtocol<GraphicsOutput>) -> Self {
		let mode_info = protocol.current_mode_info();

		let pixel_format = mode_info.pixel_format();
		assert!(
			matches!(pixel_format, PixelFormat::Rgb | PixelFormat::Bgr),
			"Only RGB and BGR framebuffer pixel formats are supported."
		);

		let (width, height) = mode_info.resolution();
		assert!(
			i32::try_from(width).is_ok(),
			"reported output width {width} >= 2^32 - 1"
		);
		assert!(
			i32::try_from(height).is_ok(),
			"reported output height {height} >= 2^32 - 1"
		);

		let stride = mode_info.stride();
		assert!(
			stride
				.checked_mul(height)
				.and_then(|v| isize::try_from(v).ok())
				.is_some(),
			"height*stride exceeds isize::MAX"
		);

		let mut fb_obj = protocol.frame_buffer();
		let framebuffer = fb_obj.as_mut_ptr();
		assert_eq!(
			framebuffer.align_offset(align_of::<u32>()),
			0,
			"framebuffer pointer not aligned to u32 boundary"
		);

		let fb_size = (fb_obj.size() / 4) as isize;

		// Black out the framebuffer
		for i in 0..fb_size {
			// SAFETY: offset is always in bounds of `framebuffer` and should always fit in isize
			// given checks above (and in practice it certainly always will).  Destination is valid
			// and aligned per note and alignment check above.
			unsafe {
				framebuffer.offset(i).write_volatile(0);
			}
		}

		Self {
			framebuffer: framebuffer.cast(),
			backbuffer: vec![0; fb_size as usize],
			width: width as u32,
			height: height as u32,
			stride: stride as isize,
			pixel_format,
			damage: Rectangle::zero(),
			fb_obj: Some(fb_obj),
		}
	}

	/// Copy the current damage region to the framebuffer, or from the backbuffer to the framebuffer
	/// if `backwards` is true.  Clears the damage rectangle after copying.
	fn copy_rect(&mut self, backwards: bool) {
		let area = self.damage.intersection(&self.bounding_box());
		if !area.is_zero_sized() {
			let src = if backwards {
				self.framebuffer
			} else {
				self.backbuffer.as_ptr()
			};
			let dest = if backwards {
				self.backbuffer.as_mut_ptr()
			} else {
				self.framebuffer
			};

			// XXX: would it be more efficient to just memcpy() from top-left to bottom-right even
			// though that'd copy a bunch of superfluous unmodified data too?
			for y in area.rows() {
				let y = y as isize;
				let scanline = y * self.stride + area.top_left.x as isize;
				// SAFETY: the framebuffer and backbuffer cannot possibly overlap as one is from
				// the Rust allocator and one is static from the GPU.  They are the same size.  The
				// area was clipped to be in-bounds of the framebuffer.
				unsafe {
					ptr::copy_nonoverlapping(
						src.offset(scanline),
						dest.offset(scanline),
						area.size.width as usize,
					);
				}
			}
		}
		self.damage = Rectangle::zero();
	}

	/// Transfer the backbuffer contents to the primary buffer.
	pub fn commit(&mut self) {
		self.copy_rect(false);
	}

	/// 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.
	pub fn discard_changes(&mut self) {
		self.copy_rect(true);
	}

	/// 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 `FbDbDrawTarget`.
	pub fn discard_changes_no_reset(&mut self) {
		self.damage = Rectangle::zero();
	}
}

#[cfg(feature = "alloc")]
impl FbDbDrawTarget<'static> {
	/// Equivalent to [`FbDbDrawTarget::new`], but allows the `FbDrawTarget` to outlive the input
	/// `ScopedProtocol`.
	///
	/// See [`FbDrawTarget::new_free_lifetime`] for complete usage and safety information.
	#[expect(
		clippy::missing_safety_doc,
		reason = "Links to FbDrawTarget::new_free_lifetime"
	)]
	pub unsafe fn new_free_lifetime(protocol: &mut ScopedProtocol<GraphicsOutput>) -> Self {
		let p = ManuallyDrop::new(FbDbDrawTarget::new(protocol));
		// Just clear owned Framebuffer referencing protocol, but since `Drop` is implemented we
		// have to do this...
		// <https://github.com/rust-lang/rfcs/pull/3466>
		// SAFETY: read is from a known-valid pointer.  Struct read from is immediately forgotten
		// after reading so no issues with use-after-free/double-free/etc.  All things that need to
		// be dropped (i.e. have explicit `Drop` and aren't preserved into here) are dropped.
		unsafe {
			// just extract `_fb_obj` so it gets dropped immediately
			let _ = ptr::read(&raw const p.fb_obj);
			Self {
				framebuffer: p.framebuffer,
				backbuffer: ptr::read(&raw const p.backbuffer),
				width: p.width,
				height: p.height,
				stride: p.stride,
				pixel_format: p.pixel_format,
				damage: p.damage,
				fb_obj: None,
			}
		}
	}
}

#[cfg(feature = "alloc")]
impl Drop for FbDbDrawTarget<'_> {
	fn drop(&mut self) {
		self.commit();
	}
}

#[cfg(feature = "alloc")]
impl OriginDimensions for FbDbDrawTarget<'_> {
	fn size(&self) -> Size {
		Size::new(self.width, self.height)
	}
}

#[cfg(feature = "alloc")]
impl DrawTarget for FbDbDrawTarget<'_> {
	type Color = Rgb888;
	type Error = Infallible;

	#[expect(
		clippy::cast_possible_wrap,
		clippy::cast_possible_truncation,
		clippy::cast_sign_loss,
		reason = "width and height confirmed to fit in i32 in constructor"
	)]
	fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>
	where
		I: IntoIterator<Item = Pixel<Self::Color>>,
	{
		let mut top_left = (self.width as usize, self.height as usize);
		let mut bottom_right = (0, 0);

		let (width, height) = (self.width as i32, self.height as i32);
		for Pixel(Point { x, y }, color) in pixels {
			if (0..width).contains(&x) && (0..height).contains(&y) {
				let (x, y) = (x as isize, y as isize);
				let offset = y as usize * self.stride as usize + x as usize;
				// superfluous as offset is already implicitly in bounds
				if offset < self.backbuffer.len() {
					self.backbuffer[offset] = color_to_storage(self.pixel_format, color);

					let (x, y) = (x as usize, y as usize);
					top_left = (usize::min(top_left.0, x), usize::min(top_left.1, y));
					bottom_right = (usize::max(bottom_right.0, x), usize::max(bottom_right.1, y));
				}
			}
		}
		let damage_rectangle = if top_left.0 > bottom_right.0 || top_left.1 > bottom_right.1 {
			Rectangle::zero()
		} else {
			Rectangle::with_corners(
				Point::new(top_left.0 as i32, top_left.1 as i32),
				Point::new(bottom_right.0 as i32, bottom_right.1 as i32),
			)
			.intersection(&self.bounding_box())
		};
		self.damage = crate::update_damage(self.damage, damage_rectangle);
		Ok(())
	}

	#[expect(
		clippy::cast_sign_loss,
		reason = "top-left and bottom-right corners confirmed to be in bounds of screen which are confirmed to fit in usize"
	)]
	fn fill_solid(&mut self, area: &Rectangle, color: Self::Color) -> Result<(), Self::Error> {
		let area = area.intersection(&self.bounding_box());
		if !area.is_zero_sized() {
			let color = color_to_storage(self.pixel_format, color);

			for y in
				(area.top_left.y as usize)..(area.top_left.y as usize + area.size.height as usize)
			{
				let scanline = y * self.stride as usize;
				for x in (area.top_left.x as usize)
					..(area.top_left.x as usize + area.size.width as usize)
				{
					self.backbuffer[scanline + x] = color;
				}
			}

			self.damage = crate::update_damage(self.damage, area);
		}
		Ok(())
	}
}