dymokomi/luce-browser-engine
Source of release 0.6.0
0.6.0 / docs / regions / r51b.md
# Regions r51b + r52 (+ the engine half of r51a): paint recording and the painters — what other regions need to know
These regions port the context paintables record into and the painters they call, so a document now goes from
`Document::update_layout` through `ViewportPaintable::paint_all_phases` into a display list, which luce-browser-render's
`DisplayListPlayerCpu` rasterizes. The stub fragments `stub_r51a_display_list`, `stub_r51b_paint_recording` and
`stub_r52_paint_painters` are gone.
## Fragments (painting/)
| Fragment | Donor |
| --- | --- |
| `border_radii_data` | BorderRadiiData.cpp `as_corner`, BorderRadiiData.h `as_corners`, BordersData.cpp `to_device_pixels` (r51a's engine half) |
| `scroll_frame` | ScrollFrame.cpp, ScrollFrame.h `paintable_box`, ScrollState.h `create_scroll_frame_for` / `create_sticky_frame_for` (r51a's engine half) |
| `device_pixel_converter` | DevicePixelConverter.h |
| `chrome_metrics` | ChromeMetrics.h |
| `chrome_widget` | ChromeWidget.h (MouseAction's flag operators, the virtuals' defaults) |
| `display_list_recording_context` | DisplayListRecordingContext.cpp and .h |
| `border_radius_corner_clipper` | BorderRadiusCornerClipper.cpp and .h |
| `resize_handle`, `scrollbar` | ResizeHandle.cpp/.h, Scrollbar.cpp/.h |
| `background_painting` | BackgroundPainting.cpp and .h |
| `blending` | Blending.cpp (+ the ENUMERATE_MIX_BLEND_MODES list) |
| `border_painting_1`, `border_painting_2` | BorderPainting.cpp 1-249 (colors, double/groove/ridge, dotted/dashed), 251-694 (solid edges, `paint_all_borders`, outlines) |
| `box_model_metrics` | BoxModelMetrics.cpp |
| `gradient_painting` | GradientPainting.cpp |
| `input_colors` | InputColors.h |
| `resolved_css_filter` | ResolvedCSSFilter.cpp and .h |
| `shadow_data`, `shadow_painting` | ShadowData.h, ShadowPainting.cpp |
| `table_borders_painting` | TableBordersPainting.cpp |
| `tests_paint_recording_cases`, `tests_paint_recording` | tests (below) |
## What other regions must know
### Values and scopes
- C++ stack objects with a destructor are values plus a `_destruct` to run where the object leaves scope:
`paint_scoped_corner_radius_clip_new(context, rect, radii, corner_clip, do_apply)` +
`paint_scoped_corner_radius_clip_destruct(&clip)` (usually with `defer`). Also added:
`display_list_recording_context_new(recorder, palette, scale, metrics)` and `chrome_metrics_new(zoom)`.
- `DisplayListRecordingContext` holds its recorder as a pointer; `display_list_recording_context_clone(this, recorder)`
answers a value. Make recorders with `display_list.display_list_recorder_new(list)`:
`display_list_recorder_construct` only sets the list, so a `= ---` recorder had garbage capture state (fixed at
r28's `Document::record_display_list` and r50's mask recording).
### Signatures changed from the stubs (all module-private C++ statics)
- `paint_get_box(box_clip, border_box, paintable_box: PaintPaintableBox*)` (was the unmapped `auto const&`).
- `paint_resolve_color_stop_positions(node, color_stop_list: const ak.Vector[...]*, resolve_position_to_float: const
PaintGradientPositionResolver*, repeating)`: the C++ generic lambda is a resolver struct (linear / conic / radial and
its basis); the color stop list functions take `const ak.Vector[gfx.ColorStop]*`.
- Table borders: `paint_snap_cells_to_device_coordinates(map: const ak.HashMap[CellCoordinates, PaintPaintableBox*, …]*,
rows, columns, context: const DisplayListRecordingContext*)`, `paint_device_border_data_from_css_border_data(…,
context: const DisplayListRecordingContext*)`, `paint_paint_separate_cell_borders(cell, map: const …*, context)`,
`paint_row_index_for_element_kind` / `paint_column_index_for_element_kind` answer `u64?` (BorderEdgePaintingInfo's
fields).
- `paint_compute_input_colors` stays `pub` (static in its header) until r53's form-control paintables call it.
- `Scrollbar::mouse_down` is declared in the C++ header but never defined: no port.
### Types filled by hand
- `types_chrome_metrics`: the zoom-invariant constants are `let`s (`n << 6`).
- `generated/types_traits`: `CellCoordinatesTraits` hashes with `pair_int_hash(row, column)` and compares with
`cell_coordinates_eq`.
### Outside these regions (needed for first pixels)
- **Backing stores** (`painting/backing_store_manager`, coordinator's request): in phase 1 each backing store is a
plain BGRA8888 premultiplied bitmap wrapped in a painting surface (there is no SharedImageBuffer in
luce-browser-render); no shared image is published to the page client.
- **`FontFaceSetLoadEvent::create`** (`stubs/stub_closure`): a plain `DOM::Event` of the name and init (the class is
outside the phase-1 closure; only script reads `fontfaces`). `FontFaceSet` fires `loadingdone` before a test paints.
- **web_test** (`tests/web_test/worker_load`): the worker activates the test document without
`Navigable::activate_history_entry`'s step 6, so the document stayed `hidden` and was never rendered; it now sets the
initial visibility state from the traversable's system visibility state.
- The test PageClient (`page/tests_page`) answers a palette (`test_palette()`, WebContent's `setup_palette`).
- HANDOFF §5 item 4 (forward `ScrollbarColorData` / `scrollbar_color()` to display_list): already done by r40
(`CssScrollbarColorData` is `display_list.ScrollbarColorData`, `css_initial_values_scrollbar_color` forwards); the
painters pass the colors to `display_list_recorder_paint_scrollbar` unchanged.
### Where paths stop now
- r53's paintables (markers, images, fieldsets, SVG, form controls, canvas, video) still trap at creation.
- Collapsed table borders call r48's `TableFormattingContext::border_is_less_specific` (tables trap earlier, at
`TableWrapper`).
- Ref tests that differ by a few levels on text (`inline-nested-node`, `css-quotes`, the `float-nowrap-*` group, …):
the CPU player draws glyphs at their exact subpixel positions, where Skia quantizes glyph positions and caches a
mask per subpixel offset, so the same text at slightly different x renders differently (render follow-up; done on
fix/fidelity-text: the player draws FreeType's masks at Skia's quarter-pixel phases, render's INTEGRATION.md).
The perspective tests needed 3D transforms in the player: done on fix/fidelity-3d (render's INTEGRATION.md, "3D
transforms"): the 12 perspective Ref tests pass.
## Tests
- **Layout harness** (`layout/tests_layout_geometry`, `painting/tests_paintables`): the cases run the real
`Document::update_layout` (`test_layout_tree_parse_and_style` + `test_layout_geometry_update_layout`) instead of the
hand-run layout steps and commit; all pass (68 geometry, 340 inline, 22 paintables — the border radii case that
waited for r52 is enabled). The inline "lines" mode still runs the layout steps itself (it reads the layout state
before commit).
- **`painting/tests_paint_recording`** (oracle `luce-browser-tools/oracles/luce-browser-engine/paint_recording`):
- DevicePixelConverter / DisplayListRecordingContext / ChromeMetrics at scales 1, 1.5, 2, 0.75, 1.25: exact;
- `Document::dump_display_list` of 9 documents (backgrounds, borders of every style and width, border radii,
outer/inner box shadows, linear/radial/repeating gradients, outlines and background clips, text, text shadow,
opacity and z-index): **exact** (every command the painters record is Ladybird's);
- the same documents rendered as a screenshot (record with the overlay and canvas fill, CPU player into 800x600)
against the pixels Ladybird's Skia player renders, which `compare_headless.py` checked to be identical to
Ladybird's own `--headless=screenshot --test-mode` screenshots. Boxes, border styles, radii, outlines/clips and
layers are **pixel exact**; tolerances per case (max channel difference, differing pixels): gradients 2 / 40
(1 level on 14 pixels), shadows 4 / 3200 (blur: 2944 pixels within 3 levels), text 130 / 2000 and text-shadow
130 / 1400 (glyphs: FreeType's hinted masks vs unhinted outlines, 1849 and 1242 pixels; exact since
fix/fidelity-text).
- MouseAction's operators, BoxModelMetrics, mix-blend-mode mapping.
- **web_test** (after merging main with r46): Layout **427** pass (of 845), Ref **352** pass (of 587 run; both sides
through our rasterizer), Crash **23**; `tests/expected_failures` rewritten with `--update-failures`.