ltk/src/render/mod.rs

// SPDX-License-Identifier: LGPL-2.1-only
// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>

//! Rendering surface used by every widget.
//!
//! [`Canvas`] is a thin enum wrapper over the per-frame rendering
//! backend. The CPU backend is [`SoftwareCanvas`] (tiny-skia + fontdue
//! rasterised into a `Pixmap`). The GPU backend is
//! [`crate::gles_render::GlesCanvas`] (EGL + GLES2/3).
//!
//! Widgets only ever see `&mut Canvas` — they call `fill_rect`,
//! `draw_text`, etc. The enum dispatches by `match self` (no `dyn`,
//! so the call sites stay monomorphic and inlinable). Field-style
//! access to backend internals (`pixmap`, `font`, `dpi_scale`…) is
//! replaced by accessor methods that the GPU variant can also
//! implement.
//!
//! # Submodule layout
//!
//! * [`setup`] — `SoftwareCanvas::{new, sub_canvas, resize, blit,
//!   set_font_registry, font_for}` (construction + accessors).
//! * [`clip`] — `SoftwareCanvas::{set_clip_rects, clear_clip,
//!   has_clip, strip_intersects_clip, clear_rects_transparent}`.
//! * [`primitives`] — `SoftwareCanvas::{clear, fill, fill_rect,
//!   stroke_rect, draw_line}`.
//! * [`text`] — `SoftwareCanvas::{draw_text, measure_text,
//!   rasterize_cached}`.
//! * [`image`] — `SoftwareCanvas::{draw_image_data,
//!   write_to_wayland_buf}`.
//! * [`helpers`] — free functions: `build_rounded_rect`,
//!   `find_font`, `find_font_opt`, `SYSTEM_FONT_CANDIDATES`.

use std::cell::Cell;
use std::sync::Arc;

use fontdue::{ Font, LineMetrics, Metrics };
use tiny_skia::{ Mask, Pixmap };

use crate::gles_render::{ BorrowedGlesTexture, GlesCanvas, GlesVersion };
use crate::theme::{ FontRegistry, FontStyle, InsetShadow, Paint as ThemePaint, Shadow };
use crate::types::{ Color, Corners, Rect };

pub( crate ) mod setup;
pub( crate ) mod clip;
pub( crate ) mod primitives;
pub( crate ) mod text;
pub( crate ) mod image;
pub( crate ) mod helpers;

// ─── Backend flag ────────────────────────────────────────────────────────────

thread_local!
{
	/// `true` when this thread's surfaces are rendered through the
	/// software (tiny-skia / SHM) path, `false` when they go through
	/// the GLES path. Set once at startup based on EGL availability
	/// and read by view code that needs to branch on backend (e.g. a
	/// layout that costs something specific to one path and isn't
	/// worth replicating on the other). Stays a thread-local so view
	/// code does not need to plumb a flag through every layout call.
	static SOFTWARE_RENDER: Cell<bool> = const { Cell::new( false ) };
}

/// Toggle the software-render flag for this thread. Consumers read
/// with [`is_software_render`].
pub fn set_software_render( on: bool )
{
	SOFTWARE_RENDER.with( | c | c.set( on ) );
}

/// `true` when the active surfaces on this thread render through the
/// software path. Used by view code that wants to avoid pipeline
/// effects the software backend doesn't implement.
pub fn is_software_render() -> bool
{
	SOFTWARE_RENDER.with( | c | c.get() )
}

// ─── Glyph cache ─────────────────────────────────────────────────────────────

/// Cache key for a rasterized glyph. `size_bits` is the f32 bit
/// pattern of `size * dpi_scale`; `font_id` is the address of the
/// `Arc<Font>` used for the rasterisation, so distinct weights /
/// families of the same `(char, size)` do not collide on the cache.
#[ derive( Hash, PartialEq, Eq, Clone, Copy ) ]
pub ( super ) struct GlyphKey
{
	pub ( super ) ch:        char,
	pub ( super ) size_bits: u32,
	pub ( super ) font_id:   usize,
}

/// Cached glyph bitmap and metrics. Fontdue's rasterize call is the
/// dominant per-frame CPU cost for text-heavy UIs; reusing across
/// frames avoids that work.
pub ( super ) struct GlyphEntry
{
	pub ( super ) metrics: Metrics,
	pub ( super ) bitmap:  Vec<u8>,
}

// ─── SoftwareCanvas ──────────────────────────────────────────────────────────

/// Software rendering backend backed by a tiny-skia [`Pixmap`] and a
/// fontdue [`Font`].
///
/// Wrapped by [`Canvas`] so the GPU backend can be slotted in by the
/// runtime without changing widget code. Widgets themselves never see
/// `SoftwareCanvas` directly.
pub struct SoftwareCanvas
{
	/// The pixel buffer drawn into each frame.
	pub pixmap:    Pixmap,
	/// The loaded system font used for all text rendering.
	///
	/// Kept as the default fallback so widgets that do not yet ask for a
	/// specific family through [`SoftwareCanvas::font_for`] keep
	/// working. Populated from
	/// [`crate::render::helpers::find_font`] at construction time.
	pub font:      Arc<Font>,
	/// Optional theme font registry. When present,
	/// [`SoftwareCanvas::font_for`] consults it before falling back
	/// to `font`. Populated by the caller once the theme's `fonts`
	/// block has been loaded.
	pub font_registry: Option<Arc<FontRegistry>>,
	/// DPI scale factor applied to font sizes.
	pub dpi_scale: f32,
	/// Global alpha multiplier for all drawing operations (0.0 =
	/// transparent, 1.0 = opaque).
	pub global_alpha: f32,
	/// Persistent cache of rasterized glyphs, indexed by (char, scaled size).
	/// Grows on demand; not LRU-bounded since typical UIs use few sizes.
	glyph_cache: std::collections::HashMap<GlyphKey, GlyphEntry>,
	/// Optional clip mask applied to all paint operations. Set via
	/// [`Canvas::set_clip_rects`] during a partial redraw so only
	/// pixels inside the dirty rects are touched. `None` means "draw
	/// everywhere".
	clip_mask:     Option<Mask>,
	/// Bounding boxes of the clip rects in physical pixels. Used by
	/// [`SoftwareCanvas::draw_text`] to do an early reject without
	/// poking the mask byte by byte (the Mask buffer is still
	/// authoritative inside the pixel loop).
	clip_bounds:   Vec<Rect>,
}

// ─── Canvas enum + dispatch ─────────────────────────────────────────────────

/// Per-frame rendering surface. Wraps a backend (software or GPU)
/// behind an enum so widgets can stay backend-agnostic.
///
/// All drawing methods are dispatched by `match self` — no `dyn`
/// indirection, so the backend branch stays predictable and
/// inlinable in the hot path.
pub enum Canvas
{
	/// CPU rasterisation via tiny-skia + fontdue, written to a
	/// `wl_shm` buffer.
	Software( SoftwareCanvas ),
	/// GPU rasterisation via EGL + GLES 2/3. Presents via
	/// `eglSwapBuffers`; [`Canvas::write_to_wayland_buf`] is a no-op
	/// for this variant.
	Gles( GlesCanvas ),
}

impl Canvas
{
	/// Build a software canvas. The GPU backend requires an EGL
	/// context — see [`Canvas::new_gles`].
	pub fn new( width: u32, height: u32 ) -> Self
	{
		Canvas::Software( SoftwareCanvas::new( width, height ) )
	}

	/// Build a GPU canvas on an already-current EGL context.
	pub fn new_gles(
		gl: Arc<glow::Context>, version: GlesVersion, width: u32, height: u32,
	) -> Self
	{
		Canvas::Gles( GlesCanvas::new( gl, version, width, height ) )
	}

	/// `(width, height)` of the underlying surface in physical pixels.
	pub fn size( &self ) -> ( u32, u32 )
	{
		match self
		{
			Canvas::Software( c ) => ( c.pixmap.width(), c.pixmap.height() ),
			Canvas::Gles( c )     => c.size(),
		}
	}

	/// Borrow the GLES texture backing this canvas, when the canvas
	/// is GPU-backed.
	pub fn borrowed_gles_texture( &self ) -> Option<BorrowedGlesTexture>
	{
		match self
		{
			Canvas::Software( _ ) => None,
			Canvas::Gles( c )     => Some( c.borrowed_texture() ),
		}
	}

	/// Read a GLES canvas into tightly packed RGBA8, top-left row
	/// first. Intentionally unavailable for software canvases because
	/// the software backend's canonical export path is
	/// [`Self::write_to_wayland_buf`].
	pub fn read_gles_rgba_pixels( &self, out: &mut [u8] ) -> Result<(), String>
	{
		match self
		{
			Canvas::Software( _ ) => Err( "read_gles_rgba_pixels requires Canvas::Gles".to_string() ),
			Canvas::Gles( c )     => c.read_rgba_pixels( out ),
		}
	}

	/// Composite an externally-owned GL texture into `dest`. No-op on
	/// the software backend (no GL state to sample from). Used by
	/// widgets that host content rendered by an external producer —
	/// the producer keeps ownership of the texture name; this call
	/// only samples it through the standard texture program.
	pub fn draw_external_texture( &mut self, texture: glow::Texture, dest: Rect, opacity: f32 )
	{
		match self
		{
			Canvas::Software( _ ) => {}
			Canvas::Gles( c )     => c.draw_external_texture( texture, dest, opacity ),
		}
	}

	pub fn dpi_scale( &self ) -> f32
	{
		match self
		{
			Canvas::Software( c ) => c.dpi_scale,
			Canvas::Gles( c )     => c.dpi_scale(),
		}
	}

	pub fn set_dpi_scale( &mut self, s: f32 )
	{
		match self
		{
			Canvas::Software( c ) => c.dpi_scale = s,
			Canvas::Gles( c )     => c.set_dpi_scale( s ),
		}
	}

	pub fn global_alpha( &self ) -> f32
	{
		match self
		{
			Canvas::Software( c ) => c.global_alpha,
			Canvas::Gles( c )     => c.global_alpha(),
		}
	}

	pub fn set_global_alpha( &mut self, a: f32 )
	{
		match self
		{
			Canvas::Software( c ) => c.global_alpha = a,
			Canvas::Gles( c )     => c.set_global_alpha( a ),
		}
	}

	/// Shared font handle. Exposed so widgets that need raw `fontdue`
	/// access (e.g. `Text` for ascent/descent) do not have to go
	/// through wrappers for every metric they read.
	pub fn font( &self ) -> &Font
	{
		match self
		{
			Canvas::Software( c ) => &c.font,
			Canvas::Gles( c )     => c.font(),
		}
	}

	/// Install a theme font registry on the active backend.
	pub fn set_font_registry( &mut self, registry: Arc<FontRegistry> )
	{
		match self
		{
			Canvas::Software( c ) => c.set_font_registry( registry ),
			Canvas::Gles( c )     => c.set_font_registry( registry ),
		}
	}

	/// Resolve a specific font via the theme registry, falling back
	/// to the system-default [`Self::font`] when no registry is
	/// installed or the triple cannot be satisfied.
	pub fn font_for( &self, family: &str, weight: u16, style: FontStyle ) -> Arc<Font>
	{
		match self
		{
			Canvas::Software( c ) => c.font_for( family, weight, style ),
			Canvas::Gles( c )     => c.font_for( family, weight, style ),
		}
	}

	/// Convenience wrapper around `font().metrics(...)` already
	/// pre-scaled by `dpi_scale`. Most callers want this rather than
	/// the raw font handle.
	pub fn font_metrics( &self, ch: char, size: f32 ) -> Metrics
	{
		self.font().metrics( ch, size * self.dpi_scale() )
	}

	/// Convenience wrapper around `font().horizontal_line_metrics(...)`.
	pub fn font_line_metrics( &self, size: f32 ) -> Option<LineMetrics>
	{
		self.font().horizontal_line_metrics( size )
	}

	pub fn resize( &mut self, width: u32, height: u32 )
	{
		match self
		{
			Canvas::Software( c ) => c.resize( width, height ),
			Canvas::Gles( c )     => c.resize( width, height ),
		}
	}

	pub fn sub_canvas( &self, width: u32, height: u32 ) -> Canvas
	{
		match self
		{
			Canvas::Software( c ) => Canvas::Software( c.sub_canvas( width, height ) ),
			Canvas::Gles( c )     => Canvas::Gles( c.sub_canvas( width, height ) ),
		}
	}

	pub fn blit( &mut self, src: &Canvas, dest_x: i32, dest_y: i32 )
	{
		self.blit_fade_bottom( src, dest_x, dest_y, 0.0 )
	}

	/// Like [`Self::blit`] but feathers the last `fade_bottom_px` source
	/// rows so the bottom edge fades to transparent. The software backend
	/// currently ignores `fade_bottom_px`, so the dissolve is GLES-only.
	pub fn blit_fade_bottom( &mut self, src: &Canvas, dest_x: i32, dest_y: i32, fade_bottom_px: f32 )
	{
		match ( self, src )
		{
			( Canvas::Software( dst ), Canvas::Software( s ) ) =>
			{
				let _ = fade_bottom_px;
				dst.blit( s, dest_x, dest_y );
			}
			( Canvas::Gles( dst ), Canvas::Gles( s ) ) =>
			{
				dst.blit_fade_bottom( s, dest_x, dest_y, fade_bottom_px );
			}
			// Cross-backend blits would need an SHM↔texture upload.
			// The toolkit only ever creates sub-canvases of the same
			// kind as their parent, so this is unreachable in practice.
			_ => unimplemented!( "cross-backend blit not supported" ),
		}
	}

	pub fn set_clip_rects( &mut self, rects: &[Rect] )
	{
		match self
		{
			Canvas::Software( c ) => c.set_clip_rects( rects ),
			Canvas::Gles( c )     => c.set_clip_rects( rects ),
		}
	}

	/// Snapshot the currently installed clip bounds (empty when no clip
	/// is active). Used by widgets that need to install a tighter clip
	/// for a single primitive and then restore whatever the outer
	/// partial-redraw or sub-canvas clip was — there is no stack
	/// internally, so round-tripping through
	/// [`Self::set_clip_rects`] with the snapshot is how to compose.
	pub fn clip_bounds( &self ) -> Vec<Rect>
	{
		match self
		{
			Canvas::Software( c ) => c.clip_bounds_snapshot(),
			Canvas::Gles( c )     => c.clip_bounds_snapshot(),
		}
	}

	pub fn clear_clip( &mut self )
	{
		match self
		{
			Canvas::Software( c ) => c.clear_clip(),
			Canvas::Gles( c )     => c.clear_clip(),
		}
	}

	pub fn clear( &mut self )
	{
		match self
		{
			Canvas::Software( c ) => c.clear(),
			Canvas::Gles( c )     => c.clear(),
		}
	}

	pub fn fill( &mut self, color: Color )
	{
		match self
		{
			Canvas::Software( c ) => c.fill( color ),
			Canvas::Gles( c )     => c.fill( color ),
		}
	}

	pub fn fill_rect( &mut self, rect: Rect, color: Color, corners: impl Into<Corners> )
	{
		let corners = corners.into();
		match self
		{
			Canvas::Software( c ) => c.fill_rect( rect, color, corners ),
			Canvas::Gles( c )     => c.fill_rect( rect, color, corners ),
		}
	}

	/// Paint-driven rectangle fill.
	///
	/// Dispatches on the [`crate::theme::Paint`] variant. Solid
	/// fills go straight through [`Self::fill_rect`]. Gradients
	/// (linear and radial) are routed to dedicated shaders on the
	/// GPU backend; on the Software backend they still collapse to a
	/// flat fill from the first stop — tiny-skia can render
	/// gradients natively, but wiring that up is left for a
	/// follow-up.
	pub fn fill_paint_rect( &mut self, rect: Rect, paint: &ThemePaint, corners: impl Into<Corners> )
	{
		let corners = corners.into();
		match paint
		{
			ThemePaint::Solid( c )  => self.fill_rect( rect, *c, corners ),
			ThemePaint::Linear( g ) =>
			{
				match self
				{
					Canvas::Software( sc ) =>
					{
						let c = g.stops.first().map( |s| s.color ).unwrap_or( Color::TRANSPARENT );
						sc.fill_rect( rect, c, corners );
					}
					Canvas::Gles( gc ) => gc.fill_linear_gradient_rect( rect, g, corners ),
				}
			}
			ThemePaint::Radial( g ) =>
			{
				match self
				{
					Canvas::Software( sc ) =>
					{
						let c = g.stops.first().map( |s| s.color ).unwrap_or( Color::TRANSPARENT );
						sc.fill_rect( rect, c, corners );
					}
					Canvas::Gles( gc ) => gc.fill_radial_gradient_rect( rect, g, corners ),
				}
			}
		}
	}

	pub fn stroke_rect( &mut self, rect: Rect, color: Color, width: f32, corners: impl Into<Corners> )
	{
		let corners = corners.into();
		match self
		{
			Canvas::Software( c ) => c.stroke_rect( rect, color, width, corners ),
			Canvas::Gles( c )     => c.stroke_rect( rect, color, width, corners ),
		}
	}

	/// Paint an outer drop shadow behind the rounded rect `target`.
	///
	/// On the GPU backend this runs an analytic soft-shadow shader
	/// in one draw call — no FBO, no cache, no readback. On the
	/// Software backend it is a no-op today.
	pub fn fill_shadow_outer( &mut self, target: Rect, shadow: &Shadow, corners: impl Into<Corners> )
	{
		let corners = corners.into();
		match self
		{
			Canvas::Software( _ ) => { /* TODO: tiny-skia BlurDropShadow */ }
			Canvas::Gles( c )     => c.fill_shadow_outer( target, shadow, corners ),
		}
	}

	/// Paint an inner (inset) shadow inside the rounded rect
	/// `target`.
	///
	/// On the GPU backend, uses a dedicated shader whose inner SDF
	/// encodes `shadow.offset` and `shadow.spread`. The blend state
	/// is switched per-call to honour `shadow.blend`: `Normal`,
	/// `PlusLighter`, `Multiply` and `Screen` map to fixed-function
	/// blend modes; `Overlay` routes through a dedicated shader that
	/// snapshots the FBO and computes the CSS Overlay formula
	/// in-shader.
	///
	/// On the Software backend this is a no-op today.
	pub fn fill_shadow_inset( &mut self, target: Rect, shadow: &InsetShadow, corners: impl Into<Corners> )
	{
		let corners = corners.into();
		match self
		{
			Canvas::Software( _ ) => { /* TODO: tiny-skia inner shadow */ }
			Canvas::Gles( c )     => c.fill_shadow_inset( target, shadow, corners ),
		}
	}

	/// Unified surface painter. Composes a themed surface in the canonical
	/// paint order: outer shadows → fill → insets.
	pub fn fill_surface
	(
		&mut self,
		rect:           Rect,
		fill:           &ThemePaint,
		outer_shadows:  &[Shadow],
		inset_shadows:  &[InsetShadow],
		corners:        impl Into<Corners>,
	)
	{
		let corners = corners.into();

		for shadow in outer_shadows
		{
			self.fill_shadow_outer( rect, shadow, corners );
		}

		self.fill_paint_rect( rect, fill, corners );

		for inset in inset_shadows
		{
			self.fill_shadow_inset( rect, inset, corners );
		}
	}

	pub fn draw_line( &mut self, x0: f32, y0: f32, x1: f32, y1: f32, color: Color, width: f32 )
	{
		match self
		{
			Canvas::Software( c ) => c.draw_line( x0, y0, x1, y1, color, width ),
			Canvas::Gles( c )     => c.draw_line( x0, y0, x1, y1, color, width ),
		}
	}

	pub fn draw_text( &mut self, text: &str, x: f32, y: f32, size: f32, color: Color )
	{
		match self
		{
			Canvas::Software( c ) => c.draw_text( text, x, y, size, color ),
			Canvas::Gles( c )     => c.draw_text( text, x, y, size, color ),
		}
	}

	/// Draw `text` with an explicitly supplied font instead of the
	/// canvas default. Use [`Self::font_for`] to resolve a `(family,
	/// weight, style)` triple from the active theme registry first.
	pub fn draw_text_with_font( &mut self, text: &str, x: f32, y: f32, size: f32, color: Color, font: &Arc<Font> )
	{
		match self
		{
			Canvas::Software( c ) => c.draw_text_with_font( text, x, y, size, color, font ),
			Canvas::Gles( c )     => c.draw_text_with_font( text, x, y, size, color, font ),
		}
	}

	pub fn measure_text( &self, text: &str, size: f32 ) -> f32
	{
		match self
		{
			Canvas::Software( c ) => c.measure_text( text, size ),
			Canvas::Gles( c )     => c.measure_text( text, size ),
		}
	}

	/// Width of `text` rendered with `font`. Mirrors
	/// [`Self::measure_text`] but bypasses the canvas default font so
	/// text laid out at one weight and drawn at another stays aligned.
	pub fn measure_text_with_font( &self, text: &str, size: f32, font: &Arc<Font> ) -> f32
	{
		match self
		{
			Canvas::Software( c ) => c.measure_text_with_font( text, size, font ),
			Canvas::Gles( c )     => c.measure_text_with_font( text, size, font ),
		}
	}

	pub fn draw_image_data( &mut self, rgba_data: &[u8], img_w: u32, img_h: u32, dest: Rect, opacity: f32 )
	{
		match self
		{
			Canvas::Software( c ) => c.draw_image_data( rgba_data, img_w, img_h, dest, opacity ),
			Canvas::Gles( c )     => c.draw_image_data( rgba_data, img_w, img_h, dest, opacity ),
		}
	}

	/// Zero pixels inside each rect — used by the partial-redraw
	/// path when the surface background is fully transparent.
	pub fn clear_rects_transparent( &mut self, rects: &[Rect] )
	{
		match self
		{
			Canvas::Software( c ) => c.clear_rects_transparent( rects ),
			Canvas::Gles( c )     => c.clear_rects_transparent( rects ),
		}
	}

	/// Copy / present the rendered frame. For software this fills a
	/// `wl_shm` buffer (with optional R/B swap for Argb8888). For
	/// GPU the commit happens via `eglSwapBuffers` elsewhere — this
	/// call is a no-op.
	pub fn write_to_wayland_buf( &self, buf: &mut [u8], swap_rb: bool )
	{
		match self
		{
			Canvas::Software( c ) => c.write_to_wayland_buf( buf, swap_rb ),
			Canvas::Gles( _ )     => {}
		}
	}

	/// Publish the in-progress GPU frame: blit the FBO onto the EGL
	/// window's default framebuffer. The follow-up `eglSwapBuffers`
	/// (done outside the canvas) is what actually commits to the
	/// compositor. No-op on software, where presentation is the SHM
	/// `attach_to`/`commit` pair.
	pub fn present( &mut self )
	{
		match self
		{
			Canvas::Software( _ ) => {}
			Canvas::Gles( c )     => c.present(),
		}
	}
}