embedded_graphics_gop/

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

//! embedded-graphics `DrawTarget`s for the UEFI Graphics Output Protocol (GOP).
//!
//! Supports using the UEFI block transfer (BLT) routines or utilizing direct framebuffer access,
//! and supports the common framebuffer pixel formats.  Naturally is `no_std`, and also supports
//! no-`alloc` (with reduced functionality).
//!
//! BLT routines require `alloc` and require UEFI boot services; while the framebuffer routines
//! don't require `alloc` in single-buffered mode, and (in practice) will still function even after
//! exiting UEFI boot services.
//!
//! The BLT target allows on-the-fly switching between single- and double-buffered modes with one
//! type while the framebuffer targets don't, because the BLT implementation always requires an
//! allocated backbuffer and always needs to do damage tracking; it's just a matter of choosing
//! when to transfer it to the primary framebuffer.  However, the framebuffer implementations can
//! write directly into the framebuffer and as such don't need an allocated buffer, and they also
//! don't normally need to perform damage tracking which significantly reduces per-pixel draw
//! overhead.
//!
//! # See Also
//!
//! - [`uefi::proto::console::gop`]
//! - [embedded-graphics](https://crates.io/crates/embedded-graphics)
//! - [UEFI Specification § 12.9](https://uefi.org/specs/UEFI/2.11/12_Protocols_Console_Support.html#graphics-output-protocol)
//!
//! # Crate Features
//!
//! - `alloc` (**default**) — adds dependency on the `alloc` crate.  Enables `BltDrawTarget` and
//!   `fb::FbDbDrawTarget`.
//! - `nightly` — only used to enable the
//!   [`doc_cfg` feature](https://doc.rust-lang.org/unstable-book/language-features/doc-cfg.html)
//!   when documenting with a nightly toolchain.
//!
//! # Prior Art
//!
//! [uefi-graphics](https://crates.io/crates/uefi-graphics),
//! [uefi-graphics-driver](https://crates.io/crates/uefi-graphics-driver), and
//! [uefi-graphics2](https://crates.io/crates/uefi-graphics2) already exist and provide somewhat
//! similar functionality.
//!
//! However, they all exclusively support the framebuffer and not BLT routines, and generally seem
//! implemented with minimal regard for the actual content of the embedded-graphics documentation
//! and the UEFI specification.  For instance, none of those check if the framebuffer's pixel
//! format actually matches what they implicitly expect (and as such exclusively support
//! `PixelFormat::Bgr` framebuffers and will otherwise silently write garbage to the framebuffer);
//! and uefi-graphics returns an error when the pixel is out of bounds in `DrawTarget::draw_iter`,
//! which one is specifically not supposed to do (the pixels *should* be silently ignored).
//!
//! They also all feel fairly hastily implemented: e.g. if double-buffering is supported, performing
//! zero damage tracking and copying the entire framebuffer every commit; or all but uefi-graphics2
//! wantonly convert integer types without any previously-performed range/bounds checks nor explicit
//! checked conversions which could lead to out-of-bounds `ptr::write`s; or uefi-graphics2 doesn't
//! respect the horizontal stride and will write garbage to the framebuffer; etc.

#![cfg_attr(feature = "nightly", feature(doc_cfg))]
#![no_std]

#[cfg(feature = "alloc")]
extern crate alloc;

#[cfg(feature = "alloc")]
mod blt;
#[cfg(feature = "alloc")]
pub use blt::BltDrawTarget;

pub mod fb;

#[cfg(feature = "alloc")]
use embedded_graphics_core::primitives::Rectangle;

/// Compute the union/bounding rectangle containing both the existing `current_damage` rectangle
/// and the given new rectangle.
#[cfg(feature = "alloc")]
fn update_damage(current_damage: Rectangle, new_damage: Rectangle) -> Rectangle {
	if current_damage.is_zero_sized() {
		new_damage
	} else if new_damage.is_zero_sized() {
		current_damage
	} else {
		let current_bottom_right = current_damage
			.bottom_right()
			.expect("infallible, confirmed to be non-zero-sized");
		let new_bottom_right = new_damage
			.bottom_right()
			.expect("infallible, confirmed to be non-zero-sized");
		Rectangle::with_corners(
			current_damage.top_left.component_min(new_damage.top_left),
			current_bottom_right.component_max(new_bottom_right),
		)
	}
}