Keep the GLES path when the scale arrives first, stop re-rendering what does not change, and let the compositor skip what the surface covers

Measured on a Librem 5 (Cortex-A53, GC7000Lite, 720×1440 at scale 2) with a frame trace on both sides of the socket: the shell's main surface repainted in 110 to 136 ms, quick settings drew at 20 fps with the GPU saturated, and every panel open uploaded its wallpaper and icons again. Most of it was the toolkit doing work the frame did not need.
Backend choice. When the compositor announces the output scale before the first `configure`, `scale_factor_changed` allocated an SHM pool for the surface and `on_configure` took that pool as the sign that the software path had been chosen, locking the surface to tiny-skia for its whole life. Every ltk main surface on a scale-2 phone ran in software while its overlays, which inherit the scale from the main and never receive that event, ran on the GPU. The scale handler now only reallocates a pool that already exists; before the first configure neither path is chosen.
Wallpapers. `WallpaperBundle::for_size` returned the crop at the source resolution, a 1103×2160 slice of a 4K image for a 720×1440 panel, 10 MB uploaded per texture and a hundred milliseconds each time. The crop is now downscaled to the surface (bilinear, once per size, cached), also for landscape surfaces smaller than the source.
Viewport. `Element::Viewport` created a fresh sub-canvas every frame, on GLES a framebuffer, a 2048² glyph atlas and empty image and glyph caches, so a panel clipped to a height that animates re-uploaded its wallpaper and re-rasterised every glyph on every frame. Without a bottom fade the clip is now a scissor on the parent canvas (a mask on the software backend): no offscreen pass, no blit, and the child's textures stay in the parent's caches. `local_viewport` is honoured through a temporary override of the layout viewport. Viewports with a fade keep their sub-canvas, which, like the scroll sub-canvases, is now kept across frames and resized in place instead of reallocated when its size changes.
Caches. The image texture cache moves from the canvas to the GL context: every canvas and sub-canvas shares one content-keyed LRU (32 MiB), so an overlay or subsurface that is destroyed and recreated finds its images resident. A GLES canvas dropped with an overlay is pooled in `AppData::canvas_pool` and handed to the next overlay, with its compiled programs and glyph atlas, which took 130 to 290 ms to build on that GPU. Subsurface slots keep their scroll and viewport sub-canvases between rasters.
Surfaces. A `container.surface()` with shadows costs a Gaussian drop-shadow pass, a fill and one pass per inset shadow, all full-quad fragment shaders; a dozen glass cards were 40 ms of GPU per frame for chrome that never changes. `Canvas::fill_surface` on GLES now renders the chrome once per size, corners and style into a texture held by the context cache (`gles_render/surface_cache.rs`, 16 MiB LRU) and blits it, drawing directly only for surfaces with `PlusLighter` or `Overlay` insets, which depend on the backdrop.
Opaque regions. ltk never called `wl_surface.set_opaque_region`, so the compositor blended every ltk surface and repainted everything underneath a full-screen homescreen. A surface whose `background_color` is opaque now declares itself opaque, and the new `App::overlay_opaque_region( id )` lets an overlay declare the physical rects it paints opaque, such as a panel column over an opaque wallpaper. `sync_opaque_region` sends the rects only when they change.
Frame pacing. `eglSwapBuffers` blocked 13 to 37 ms per frame waiting for Mesa's own throttle callback; ltk paces itself on `wl_surface.frame`, so `make_current` sets the swap interval to 0. A subsurface move is now applied only when its parent has no frame callback outstanding, and the parent commit that applies it requests the next callback: a drag commits once per vblank with the latest finger position instead of once per input sample, without the app throttling samples itself. While the app reports `subsurface_motion_only`, the main's callback, and the callback of an overlay that hosts a subsurface, no longer force a full repaint; they mark the surface and the reconcile keeps the cadence with a bare commit when nothing moved. Swipe releases arm a settle the same way instead of dirtying every cache. Two hooks, `on_overlay_frame_committed` and `on_subsurface_committed`, let an app hand a panel over between its host and a sliding subsurface on real commits rather than loop ticks.
Lines. A diagonal `draw_line` on GLES stamped one `fill_rect` per pixel of length, 190 draw calls for a spinner and over 2000 for a pattern-lock stroke; it is now a single rotated quad through the rect shader, with round caps and antialiased edges.
A pixel test covers the scissor viewport, `for_size` gets a downscale test, and `docs/architecture.md`, `docs/widgets.md` and `docs/backends.md` describe the new hook, the viewport paths, the shared caches and the line rasteriser.

src/event_loop/subsurface.rs

@@ -58,12 +58,26 @@ pub( crate ) struct SubsurfaceSlot
 	last_version: u64,
 	rastered:     bool,
 	parent:       SubsurfaceParent,
+	scroll_canvases:   HashMap<usize, Canvas>,
+	viewport_canvases: HashMap<usize, Canvas>,
 }
 
 impl SubsurfaceSlot
 {
-	fn destroy( mut self )
+	pub( crate ) fn parent( &self ) -> SubsurfaceParent
 	{
+		self.parent
+	}
+
+	fn destroy( mut self, egl: Option<&Arc<EglContext>> )
+	{
+		// GLES sub-canvases free their objects on drop and need the context current.
+		if let ( Some( ctx ), Some( es ) ) = ( egl, self.egl_surface.as_ref() )
+		{
+			let _ = ctx.make_current( es );
+		}
+		self.scroll_canvases.clear();
+		self.viewport_canvases.clear();
 		// Drop the EGL surface before the wl_surface its wl_egl_window wraps.
 		self.egl_surface = None;
 		self.subsurface.destroy();
@@ -71,6 +85,56 @@ impl SubsurfaceSlot
 	}
 }
 
+fn focus_of( parent: SubsurfaceParent ) -> super::SurfaceFocus
+{
+	match parent
+	{
+		SubsurfaceParent::Main          => super::SurfaceFocus::Main,
+		SubsurfaceParent::Overlay( id ) => super::SurfaceFocus::Overlay( id ),
+	}
+}
+
+fn parent_frame_pending<A: App>( data: &AppData<A>, parent: SubsurfaceParent ) -> bool
+{
+	match parent
+	{
+		SubsurfaceParent::Main          => data.main.frame_pending,
+		SubsurfaceParent::Overlay( id ) => data.overlays.get( &id ).is_some_and( |ss| ss.frame_pending ),
+	}
+}
+
+/// Request a frame callback on `parent` ahead of the commit that applies a
+/// subsurface move, unless one is already outstanding.
+fn arm_parent_frame<A: App>( data: &mut AppData<A>, parent: SubsurfaceParent, wl: &WlSurface )
+{
+	let ss = match parent
+	{
+		SubsurfaceParent::Main          => &mut data.main,
+		SubsurfaceParent::Overlay( id ) => match data.overlays.get_mut( &id ) { Some( s ) => s, None => return },
+	};
+	ss.frame_tick_due = false;
+	if ss.frame_pending { return; }
+	let _ = wl.frame( &data.qh, focus_of( parent ) );
+	ss.frame_pending = true;
+}
+
+/// Keep the frame cadence on a parent whose callback fired while the app
+/// animates by subsurface motion only, when this pass moved nothing on it.
+fn keep_parent_cadence<A: App>( data: &mut AppData<A>, parent: SubsurfaceParent, animating: bool )
+{
+	let ss = match parent
+	{
+		SubsurfaceParent::Main          => &mut data.main,
+		SubsurfaceParent::Overlay( id ) => match data.overlays.get_mut( &id ) { Some( s ) => s, None => return },
+	};
+	if !std::mem::take( &mut ss.frame_tick_due ) { return; }
+	if ss.frame_pending || !animating { return; }
+	let Some( wl ) = ss.surface.try_wl_surface().cloned() else { return };
+	let _ = wl.frame( &data.qh, focus_of( parent ) );
+	wl.commit();
+	ss.frame_pending = true;
+}
+
 /// Resolve a subsurface's parent surface to `( wl_surface, phys_w, phys_h,
 /// scale )`. Returns `None` when an [`SubsurfaceParent::Overlay`] target is
 /// absent, not yet configured, or zero-sized — the caller skips the spec for
@@ -116,6 +180,7 @@ pub( crate ) fn reconcile_subsurfaces<A: App>( data: &mut AppData<A> )
 	// Parents touched this frame; each committed once at the end so the
 	// placement / mapping actually lands.
 	let mut dirty_parents: Vec<( SubsurfaceParent, WlSurface )> = Vec::new();
+	let mut committed: Vec<crate::app::SubsurfaceId> = Vec::new();
 
 	// Drop subsurfaces whose id disappeared from the spec list.
 	let present: std::collections::HashSet<crate::app::SubsurfaceId> =
@@ -129,7 +194,7 @@ pub( crate ) fn reconcile_subsurfaces<A: App>( data: &mut AppData<A> )
 		if let Some( slot ) = data.subsurfaces.remove( &id )
 		{
 			let parent = slot.parent;
-			slot.destroy();
+			slot.destroy( data.egl_context.as_ref() );
 			if let Some( ( wl, _, _, _ ) ) = resolve_parent( data, parent )
 			{
 				mark_parent_dirty( &mut dirty_parents, parent, &wl );
@@ -164,9 +229,12 @@ pub( crate ) fn reconcile_subsurfaces<A: App>( data: &mut AppData<A> )
 				last_version: u64::MAX,
 				rastered:     false,
 				parent:       spec.parent,
+				scroll_canvases:   HashMap::new(),
+				viewport_canvases: HashMap::new(),
 			} );
 			mark_parent_dirty( &mut dirty_parents, spec.parent, &parent_wl );
 		}
+		let parent_pending = parent_frame_pending( data, spec.parent );
 
 		// Tracked on the slot (not the canvas) because the GLES canvas lives
 		// in `data.subsurface_gles_canvas`, shared across all subsurfaces.
@@ -192,11 +260,15 @@ pub( crate ) fn reconcile_subsurfaces<A: App>( data: &mut AppData<A> )
 			slot.rastered     = true;
 			slot.last_version = spec.content_version;
 			slot.last_size    = ( pw, ph );
+			committed.push( spec.id );
 			mark_parent_dirty( &mut dirty_parents, spec.parent, &parent_wl );
 		}
 
+		// A move waits for the parent's outstanding frame callback, so a drag
+		// commits once per vblank with the latest position instead of once
+		// per input sample.
 		let slot = data.subsurfaces.get_mut( &spec.id ).unwrap();
-		if slot.last_pos != ( spec.x, spec.y )
+		if slot.last_pos != ( spec.x, spec.y ) && !parent_pending
 		{
 			let ( lx, ly ) = to_logical( spec.x, spec.y, scale );
 			slot.subsurface.set_position( lx, ly );
@@ -211,10 +283,24 @@ pub( crate ) fn reconcile_subsurfaces<A: App>( data: &mut AppData<A> )
 
 	// Applies pending subsurface placement / mapping without re-attaching the
 	// parent buffer — the cheap per-frame move.
-	for ( _, wl ) in dirty_parents
+	for ( parent, wl ) in dirty_parents
 	{
+		arm_parent_frame( data, parent, &wl );
 		wl.commit();
 	}
+
+	let animating = data.app.is_animating();
+	keep_parent_cadence( data, SubsurfaceParent::Main, animating );
+	let overlay_ids: Vec<crate::app::OverlayId> = data.overlays.keys().copied().collect();
+	for id in overlay_ids
+	{
+		keep_parent_cadence( data, SubsurfaceParent::Overlay( id ), animating );
+	}
+
+	for id in committed
+	{
+		data.app.on_subsurface_committed( id );
+	}
 }
 
 /// Input-transparent subsurfaces never carry focus / hover / scroll state,
@@ -233,6 +319,8 @@ fn empty_draw_ctx<Msg: Clone>() -> DrawCtx<Msg>
 		scroll_offsets:         HashMap::new(),
 		scroll_rects:           Vec::new(),
 		scroll_canvases:        HashMap::new(),
+		viewport_canvases:      HashMap::new(),
+		viewport_seq:           0,
 		scroll_navigable_items: HashMap::new(),
 		scroll_clipped:         Vec::new(),
 		previous_widget_rects:  Vec::new(),
@@ -241,6 +329,14 @@ fn empty_draw_ctx<Msg: Clone>() -> DrawCtx<Msg>
 	}
 }
 
+fn slot_draw_ctx<Msg: Clone>( scroll: &mut HashMap<usize, Canvas>, viewport: &mut HashMap<usize, Canvas> ) -> DrawCtx<Msg>
+{
+	let mut ctx = empty_draw_ctx::<Msg>();
+	ctx.scroll_canvases   = std::mem::take( scroll );
+	ctx.viewport_canvases = std::mem::take( viewport );
+	ctx
+}
+
 /// Raster a subsurface's content. Uses the GLES path when an [`EglContext`]
 /// is available — only there does the `surface-panel` backdrop blur render;
 /// the software fallback paints the same widgets without the blur.
@@ -320,9 +416,11 @@ fn render_slot_gpu<Msg: Clone>(
 	canvas.clear();
 
 	let screen_rect = Rect { x: 0.0, y: 0.0, width: pw as f32, height: ph as f32 };
-	let mut ctx = empty_draw_ctx::<Msg>();
+	let mut ctx = slot_draw_ctx::<Msg>( &mut slot.scroll_canvases, &mut slot.viewport_canvases );
 	layout_and_draw::<Msg>( view, canvas, screen_rect, &mut ctx, 0 );
 	canvas.present();
+	slot.scroll_canvases   = ctx.scroll_canvases;
+	slot.viewport_canvases = ctx.viewport_canvases;
 
 	let wl = &slot.surface;
 	wl.set_buffer_scale( scale as i32 );
@@ -382,8 +480,10 @@ fn render_slot_software<Msg: Clone>(
 	canvas.clear();
 
 	let screen_rect = Rect { x: 0.0, y: 0.0, width: pw as f32, height: ph as f32 };
-	let mut ctx = empty_draw_ctx::<Msg>();
+	let mut ctx = slot_draw_ctx::<Msg>( &mut slot.scroll_canvases, &mut slot.viewport_canvases );
 	layout_and_draw::<Msg>( view, canvas, screen_rect, &mut ctx, 0 );
+	slot.scroll_canvases   = ctx.scroll_canvases;
+	slot.viewport_canvases = ctx.viewport_canvases;
 
 	canvas.write_to_wayland_buf( canvas_buf, swap_rb );