embedded_graphics_gop/

blt.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/>.

use alloc::{vec, vec::Vec};
use embedded_graphics_core::{pixelcolor::Rgb888, prelude::*, primitives::Rectangle};
use uefi::{
	boot::ScopedProtocol,
	proto::console::gop::{BltOp, BltPixel, BltRegion, GraphicsOutput},
};

/// 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
///
/// ```no_run
/// 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();
/// ```
#[derive(Debug)]
pub struct BltDrawTarget<'proto> {
	/// GOP protocol handle
	handle: &'proto mut ScopedProtocol<GraphicsOutput>,
	/// Internal framebuffer to optimize `draw_iter` calls
	backbuffer: Vec<BltPixel>,
	/// If it is in double buffered mode
	double_buffer: bool,
	/// Damage to backbuffer since last commit, if in double-buffered mode.
	damage: Rectangle,
	/// Width of the current video mode
	width: u32,
	/// Height of the current video mode
	height: u32,
}

impl<'proto> BltDrawTarget<'proto> {
	/// 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 `u32`s).
	#[expect(
		clippy::cast_possible_truncation,
		reason = "Asserted width and height always fit in [0, i32::MAX), so they will always fit in u32."
	)]
	pub fn new(protocol: &'proto mut ScopedProtocol<GraphicsOutput>) -> uefi::Result<Self> {
		let mode_info = protocol.current_mode_info();
		let (width, height) = mode_info.resolution();
		assert!(
			i32::try_from(width).is_ok(),
			"reported output width {width} >= 2^31 - 1"
		);
		assert!(
			i32::try_from(height).is_ok(),
			"reported output height {height} >= 2^31 - 1"
		);
		// Fill framebuffer with black
		protocol.blt(BltOp::VideoFill {
			color: BltPixel::new(0, 0, 0),
			dest: (0, 0),
			dims: (width, height),
		})?;
		Ok(Self {
			handle: protocol,
			// checked_mul checks for usize::MAX, but then allocating the vector will also check
			// against allocating more than isize::MAX bytes.
			backbuffer: vec![
				BltPixel::new(0, 0, 0);
				width
					.checked_mul(height)
					.expect("width*height exceeds usize::MAX")
			],
			double_buffer: false,
			damage: Rectangle::zero(),
			width: width as u32,
			height: height as u32,
		})
	}

	/// 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.
	pub fn double_buffer(&mut self, double_buffer: bool) -> uefi::Result<()> {
		if self.double_buffer && !double_buffer {
			self.commit()?;
		}
		self.double_buffer = double_buffer;
		Ok(())
	}

	/// Return whether double-buffering mode is currently enabled.
	pub fn get_double_buffer(&self) -> bool {
		self.double_buffer
	}

	/// Copy the given `rect` (or the current damage region if `None`) to the framebuffer, or from
	/// the backbuffer to the framebuffer if `backwards` is true.  Clears the damage rectangle after
	/// copying.
	#[expect(clippy::cast_sign_loss, reason = "Known to fit in usize")]
	fn copy_rect(&mut self, rect: Option<Rectangle>, backwards: bool) -> uefi::Result<()> {
		let area = self
			.bounding_box()
			.intersection(&rect.unwrap_or(self.damage));
		if self.double_buffer && !area.is_zero_sized() {
			let top_left = (
				self.damage.top_left.x as usize,
				self.damage.top_left.y as usize,
			);
			let dims = (
				self.damage.size.width as usize,
				self.damage.size.height as usize,
			);
			let subrectangle = BltRegion::SubRectangle {
				coords: top_left,
				px_stride: self.width as usize,
			};

			if backwards {
				self.handle.blt(BltOp::VideoToBltBuffer {
					buffer: &mut self.backbuffer,
					src: top_left,
					dest: subrectangle,
					dims,
				})?;
			} else {
				self.handle.blt(BltOp::BufferToVideo {
					buffer: self.backbuffer.as_slice(),
					src: subrectangle,
					dest: top_left,
					dims,
				})?;
			}
		}
		self.damage = Rectangle::zero();
		Ok(())
	}

	/// 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.
	pub fn commit(&mut self) -> uefi::Result<()> {
		self.copy_rect(None, 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.
	///
	/// # Errors
	///
	/// Returns a [`uefi::Error`] if an error occurs while reading the primary buffer data into the
	/// backbuffer.
	pub fn discard_changes(&mut self) -> uefi::Result<()> {
		self.copy_rect(None, 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 `BltDrawTarget`.
	pub fn discard_changes_no_reset(&mut self) {
		self.damage = Rectangle::zero();
	}
}

impl Drop for BltDrawTarget<'_> {
	fn drop(&mut self) {
		let _ = self.commit();
	}
}

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

impl DrawTarget for BltDrawTarget<'_> {
	// Specified BLTPixel color format
	type Color = Rgb888;
	type Error = uefi::Error;

	#[expect(
		clippy::cast_possible_truncation,
		clippy::cast_possible_wrap,
		clippy::cast_sign_loss,
		reason = "width and height were confirmed to fit within range of i32 and usize in constructors."
	)]
	fn draw_iter<I>(&mut self, pixels: I) -> Result<(), Self::Error>
	where
		I: IntoIterator<Item = Pixel<Self::Color>>,
	{
		// Just computing one rectangle containing all pixels drawn rather than trying to do more
		// granular damage tracking
		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 usize, y as usize);
				// Always sound arithmetic?  I think so since width*height (i.e. one after last
				// pixel) is always <=(isize::MAX/4)
				//
				// The color conversion will likely be more efficient using these constructors,
				// rather than using `.into_storage().into()` which would shift the Rgb888 into a
				// u32, only to immediately shift and mask it back into a BltPixel.
				self.backbuffer[(y * self.width as usize) + x] =
					BltPixel::new(color.r(), color.g(), color.b());

				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())
		};
		if !damage_rectangle.is_zero_sized() {
			if self.double_buffer {
				self.damage = crate::update_damage(self.damage, damage_rectangle);
			} else {
				self.copy_rect(Some(damage_rectangle), true)?;
			}
		}
		Ok(())
	}

	// Could in theory provide a `DrawTarget::fill_contiguous` implementation that doesn't need to
	// track the bounding rectangle nor check if points lie inside the framebuffer, but would need
	// to keep track of whether the point from the color iterator lies inside of it anyways and
	// it'd be a lot of code duplication and effort for little gain

	#[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 = BltPixel::new(color.r(), color.g(), color.b());

			// XXX: needed to keep the backbuffer in sync even in single-buffered mode, but seems
			// janky and inefficent.
			for y in
				(area.top_left.y as usize)..(area.top_left.y as usize + area.size.height as usize)
			{
				for x in (area.top_left.x as usize)
					..(area.top_left.x as usize + area.size.width as usize)
				{
					// See draw_iter for reasoning around math staying in-bounds
					self.backbuffer[y * self.width as usize + x] = color;
				}
			}

			if self.double_buffer {
				self.damage = crate::update_damage(self.damage, area);
			} else {
				self.handle.blt(BltOp::VideoFill {
					color,
					dest: (area.top_left.x as usize, area.top_left.y as usize),
					dims: (area.size.width as usize, area.size.height as usize),
				})?;
			}
		}
		Ok(())
	}
}