Skip to content

Commit 6b2bb92

Browse files
[web] Unify ui.Canvas behind a shared EngineCanvas frontend (flutter#196348)
Unifies `ui.Canvas` across CanvasKit and Skwasm behind a shared `EngineCanvas` frontend (`primitives/canvas.dart`) and stateless `BackendCanvas` boundary (`backend/canvas.dart`), turning `CkCanvas` and `SkwasmCanvas` into thin native translators. Centralizing argument validation, `PictureImageTracker` image retention, the per-draw `BackendPaint` lifecycle, point/atlas typed-array flattening, superellipse path emulation, `getLocalClipBounds`, and `WebParagraph` dispatch brings all web renderers onto a single implementation with consistent runtime behavior. Part of flutter#175630 ## Behavioral Changes - **Skwasm and Web Impeller now validate `Canvas` arguments identically to CanvasKit and native `dart:ui`:** - Before: Skwasm silently truncated, misread, or passed mismatched buffer lengths to native code when given a `transform` matrix without 16 entries, an odd-length `drawRawPoints` list, or mismatched `drawAtlas`/`drawRawAtlas` transform, rect, and color lengths. - After: Each throws the same `ArgumentError` and message as CanvasKit and native `dart:ui`, without mutating the save stack, transform, or tracked images. - **Consistent debug assertions across all web renderers:** - Skwasm and Web Impeller now assert on NaN rects, rounded rects, rounded superellipses, and offsets (including `clipRSuperellipse`/`drawRSuperellipse` on CanvasKit as well). - Drawing a disposed `Image`, `Picture`, `Paragraph`, `Vertices`, or atlas image, or calling `drawAtlas`/`drawRawAtlas` with colors and a `null` `blendMode`, now throws `AssertionError` across all web renderers (previously missing, or throwing `StateError` for disposed pictures on CanvasKit and disposed vertices). - **`drawAtlas(colors: [])` on Skwasm now treats an empty color list as "no colors":** - Before: Skwasm passed a zero-length buffer and native code read one uninitialized color per sprite. - After: Matches CanvasKit and native `dart:ui` by passing `null` when `colors` is empty. - **`drawParagraph` now supports `WebParagraph` on Skwasm:** - Before: `SkwasmCanvas.drawParagraph` threw a `TypeError` when given a `WebParagraph`; only CanvasKit routed it to `WebParagraph.paint`. - After: `EngineCanvas.drawParagraph` dispatches `WebParagraph` on every renderer. ## Where to focus - **`lib/src/engine/primitives/canvas.dart`**: Ordering invariant in `EngineCanvas`—all validation and throwing delegate unwraps (`backendPath`, `backendImage`, `EngineVertices.delegate`, `getBackendFilter`) run before `_tracker` recording and `createBackendPaint()`, so rejected calls never retain images or leak a native paint. Image and atlas draws pass `defaultBlurTileMode: ui.TileMode.clamp`; all other draws use the default decal mode. - **`lib/src/engine/canvaskit/canvas.dart` and `lib/src/engine/skwasm/skwasm_impl/canvas.dart`**: Stateless `BackendCanvas` translators preserving backend-specific conversions (CanvasKit degree conversion, Mitchell cubic sampling, and float nine-slice centers; Skwasm `StackScope` conversions, integer nine-slice centers, and `drawAtlas` `cullRect`). - **`lib/src/engine/canvaskit/{picture_recorder,picture,surface}.dart` and `lib/src/engine/skwasm/skwasm_impl/picture.dart`**: Recorders and internal raster canvases now wrap their backend canvas in `EngineCanvas`, and `LayerPicture` exposes `imageTracker` so `EngineCanvas.drawPicture` merges retained image sources in the frontend. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant in-code documentation (doc comments with `///`). - [x] If this PR introduces a new feature or capability, I created and linked a website documentation issue or PR in [flutter/website] (or verified none is needed). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/CONTRIBUTING.ai.md [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [flutter/website]: https://github.com/flutter/website [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
1 parent 627ac6e commit 6b2bb92

22 files changed

Lines changed: 2183 additions & 906 deletions

‎engine/src/flutter/lib/web_ui/lib/src/engine.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ library engine;
1818
export 'engine/alarm_clock.dart';
1919
export 'engine/app_bootstrap.dart';
2020
export 'engine/arena.dart';
21+
export 'engine/backend/canvas.dart';
2122
export 'engine/backend/codec.dart';
2223
export 'engine/backend/filter.dart';
2324
export 'engine/backend/font_collection.dart';
@@ -105,6 +106,7 @@ export 'engine/plugins.dart';
105106
export 'engine/pointer_binding.dart';
106107
export 'engine/pointer_binding/event_position_helper.dart';
107108
export 'engine/pointer_converter.dart';
109+
export 'engine/primitives/canvas.dart';
108110
export 'engine/primitives/codec.dart';
109111
export 'engine/primitives/color_filter.dart';
110112
export 'engine/primitives/font_collection.dart';
Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
// Copyright 2013 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'dart:typed_data';
6+
7+
import 'package:ui/ui.dart' as ui;
8+
9+
import 'filter.dart';
10+
import 'image.dart';
11+
import 'paint.dart';
12+
import 'paragraph.dart';
13+
import 'path.dart';
14+
import 'vertices.dart';
15+
16+
/// The backend side of a recording canvas: one method per native canvas
17+
/// operation.
18+
///
19+
/// A [BackendCanvas] is driven by `EngineCanvas`, the `ui.Canvas`
20+
/// implementation shared by all renderers. Implementations are stateless
21+
/// translators to native calls:
22+
///
23+
/// * They hold only their native canvas.
24+
/// * They take only backend delegates ([BackendPaint], [BackendPath],
25+
/// [BackendImage], ...), `dart:ui` value types and typed arrays. They never
26+
/// take frontend (`Engine*`) objects, FFI pointers or JS interop types.
27+
/// * They don't validate arguments, track images, or create or dispose
28+
/// paints. The caller owns every [BackendPaint] it passes in.
29+
///
30+
/// [drawPicture] is a temporary exception that takes a [ui.Picture], until
31+
/// `PictureRecorder` and `Picture` are unified.
32+
abstract class BackendCanvas {
33+
void save();
34+
35+
void saveLayer(ui.Rect? bounds, BackendPaint paint);
36+
37+
/// Saves a new layer that first applies [backdropFilter] to the content
38+
/// behind it, sampling past the backdrop edges with [backdropTileMode].
39+
void saveLayerWithFilter(
40+
ui.Rect? bounds,
41+
BackendPaint paint,
42+
BackendImageFilter backdropFilter,
43+
ui.TileMode backdropTileMode,
44+
);
45+
46+
void restore();
47+
48+
/// Pops the save stack until its depth is [count].
49+
void restoreToCount(int count);
50+
51+
/// The current save stack depth; a fresh canvas has a depth of 1.
52+
int getSaveCount();
53+
54+
void translate(double dx, double dy);
55+
56+
void scale(double sx, double sy);
57+
58+
/// Rotates the current transform clockwise by [radians].
59+
void rotate(double radians);
60+
61+
void skew(double sx, double sy);
62+
63+
/// Multiplies the current transform by [matrix4].
64+
///
65+
/// The caller has already checked that [matrix4] has 16 entries.
66+
void transform(Float64List matrix4);
67+
68+
/// The current transform as a 16-entry column-major matrix.
69+
Float64List getTransform();
70+
71+
void clipRect(ui.Rect rect, ui.ClipOp clipOp, bool doAntiAlias);
72+
73+
void clipRRect(ui.RRect rrect, bool doAntiAlias);
74+
75+
void clipPath(BackendPath path, bool doAntiAlias);
76+
77+
/// The current clip in device space, rounded out to whole pixels.
78+
ui.Rect getDestinationClipBounds();
79+
80+
/// Fills the current clip with [color], replacing the existing pixels.
81+
void clear(ui.Color color);
82+
83+
/// Whether [rect], in local coordinates, lies entirely outside the clip.
84+
bool quickReject(ui.Rect rect);
85+
86+
void drawColor(ui.Color color, ui.BlendMode blendMode);
87+
88+
void drawLine(ui.Offset p1, ui.Offset p2, BackendPaint paint);
89+
90+
void drawPaint(BackendPaint paint);
91+
92+
void drawRect(ui.Rect rect, BackendPaint paint);
93+
94+
void drawRRect(ui.RRect rrect, BackendPaint paint);
95+
96+
void drawDRRect(ui.RRect outer, ui.RRect inner, BackendPaint paint);
97+
98+
void drawOval(ui.Rect rect, BackendPaint paint);
99+
100+
void drawCircle(ui.Offset center, double radius, BackendPaint paint);
101+
102+
/// Draws an arc. [startAngle] and [sweepAngle] are in radians.
103+
void drawArc(
104+
ui.Rect rect,
105+
double startAngle,
106+
double sweepAngle,
107+
bool useCenter,
108+
BackendPaint paint,
109+
);
110+
111+
void drawPath(BackendPath path, BackendPaint paint);
112+
113+
void drawImage(
114+
BackendImage image,
115+
ui.Offset offset,
116+
BackendPaint paint,
117+
ui.FilterQuality filterQuality,
118+
);
119+
120+
void drawImageRect(
121+
BackendImage image,
122+
ui.Rect src,
123+
ui.Rect dst,
124+
BackendPaint paint,
125+
ui.FilterQuality filterQuality,
126+
);
127+
128+
/// Draws [image] as a nine-slice into [dst], where [center] is in image
129+
/// coordinates.
130+
void drawImageNine(
131+
BackendImage image,
132+
ui.Rect center,
133+
ui.Rect dst,
134+
BackendPaint paint,
135+
ui.FilterQuality filterQuality,
136+
);
137+
138+
/// Draws [picture], which must have been recorded by the same renderer.
139+
void drawPicture(ui.Picture picture);
140+
141+
void drawParagraph(BackendParagraph paragraph, ui.Offset offset);
142+
143+
/// Draws points from [points], a flat list of x, y pairs of even length.
144+
void drawPoints(ui.PointMode pointMode, Float32List points, BackendPaint paint);
145+
146+
void drawVertices(BackendVertices vertices, ui.BlendMode blendMode, BackendPaint paint);
147+
148+
/// Draws sprites from [atlas].
149+
///
150+
/// [rstTransforms] and [rects] have four values per sprite. [colors] is
151+
/// either null or has one value per sprite.
152+
void drawAtlas(
153+
BackendImage atlas,
154+
Float32List rstTransforms,
155+
Float32List rects,
156+
Uint32List? colors,
157+
ui.BlendMode blendMode,
158+
ui.Rect? cullRect,
159+
BackendPaint paint,
160+
ui.FilterQuality filterQuality,
161+
);
162+
163+
/// Draws the shadow of [path]. [devicePixelRatio] scales the light
164+
/// geometry from logical to physical pixels.
165+
void drawShadow(
166+
BackendPath path,
167+
ui.Color color,
168+
double elevation,
169+
bool transparentOccluder,
170+
double devicePixelRatio,
171+
);
172+
}

0 commit comments

Comments
 (0)