dymokomi/luce-browser-render
Source of release 0.6.2
0.6.2 / docs / regions / r51a.md
# Region r51a: the display list (`display_list`) — what other regions need to know
Region r51a ports LibWeb's display list — AccumulatedVisualContext, BorderRadiiData, BordersData,
DisplayList (with DisplayListPlayer's command loop), DisplayListCommand, DisplayListRecorder,
ExternalContentSource, GradientData, PaintStyle, ScrollFrame, ScrollState, ShouldAntiAlias — and
replaces DisplayListPlayerSkia with **DisplayListPlayerCpu**, a CPU player over the `raster`
module (DESIGN.md §7.3). Each fragment's header describes it; `docs/namemap.tsv` lists every name.
The stub fragment `stub_r51a_display_list.lucb` and the generated
`types_display_list_player_skia.lucb` are gone.
## Fragments
| Fragment | Contents |
| --- | --- |
| `gfx_conversions` | the `to_type`/`to_rounded` template instantiations the display list uses |
| `accumulated_visual_context` | ClipData, EffectsData, AccumulatedVisualContextTree |
| `border_radii_data`, `borders_data` | CornerRadius/CornerRadii/BorderRadiusData/BorderRadiiData, BordersDataDevicePixels |
| `display_list` | DisplayList; DisplayListPlayer's `execute`, `execute_impl`, pure virtuals |
| `display_list_command` | the commands' `bounding_rect`, `is_clip` and `dump` |
| `cpu_canvas`, `cpu_blur` (now `cpu_mask_blur*`), `cpu_color_space` (gone), `cpu_gradient`, `cpu_shapes` | the canvas the CPU player draws on (new code: SkCanvas's behavior over `raster`) |
| `display_list_player_cpu`, `display_list_player_cpu_2` | DisplayListPlayerCpu, in DisplayListPlayerSkia.cpp's order |
| `display_list_recorder` | DisplayListRecorder, CommandCapture, DisplayListRecorderStateSaver |
| `external_content_source`, `initial_values`, `paint_style`, `scroll_state` | the rest |
| `tests_*` | the tests (below) |
## Signature and type changes against the skeleton
### Types filled or fixed by hand
- `DisplayListCommandListItem` (`context_index`, `command`), `DisplayListRecorderFillPathParams`,
`DisplayListRecorderStrokePathParams` (with the C++ defaults), `DisplayListRecorderCommandCapture`
(`m_recorder`) and `DisplayListRecorderMaskInfo` had no fields.
- `ShouldAntiAlias` is `as u8` with `yes = 0, no = 1` (the generator made `no = -1`).
- `ColorStop` (Painting) defaults its position to NaN, as the C++ does.
- The commands' `command_name` members are `pub let … : str` constants (they were `pub var
ak.StringView`s nothing initialized).
- **gfx (r08's types):** `FloatMatrix4X4.m_elements` is `f32[4][4]` (row-major, C++ `T
m_elements[N][N]`); it was `(f32*?)*?`.
- `types_display_list_player_cpu.lucb` (hand-written, generator form) declares DisplayListPlayerCpu
with class id 1, the Skia player's slot.
### Signatures of other regions' stubs, fixed (clearly wrong)
- r08: `extract_2d_affine_transform(m: const FloatMatrix4X4*) -> AffineTransform` (was a
template over `void*?`).
- r10: `calculate_gradient_length(gradient_size: FloatSize, gradient_angle: f32) -> f32` (was a
template over `void*?`); `painting_surface_write_from_bitmap(this, bitmap: const Bitmap*)` (was
a Bitmap by value).
- r09: `shape_text_f32(…, font: const Font*, …)` (was a Font by value).
### This region's signatures
- C++ `const&` returns and parameters that are kept or large are pointers:
`accumulated_visual_context_tree_node_at` → `const AccumulatedVisualContextNode*`,
`display_list_visual_context_tree` → `const AccumulatedVisualContextTree*`,
`display_list_commands` → `const ak.Vector[…]*`, `borders_data_device_pixels_for_edge_const` →
`const BorderDataDevicePixels*`, `scroll_state_frame_at_const` → `const ScrollFrame*`, the
ScrollStateSnapshot parameters, and the recorder's `glyph_run: const web_fonts.GlyphRun*`,
`font: const web_fonts.Font*`, `raw_text: const ak.Utf16String*`, `bitmap: const
gfx.ImmutableBitmap*`.
- `scroll_state_snapshot_create(scroll_frames: const ak.Vector[ScrollFrame]*, …)`.
- `scroll_state_for_each_scroll_frame(this)` and `scroll_state_for_each_sticky_frame(this)`
return a `ScrollFrameIterator` of `ScrollFrameEntry(index, frame)`: `for entry in …`.
- `command_nesting_level_change(command: const DisplayListCommand*)` (one function for the
template's instantiations).
- `display_list_recorder_draw_line`'s `alternate_color` defaults to `Color::Transparent`.
- Added: `display_list_recorder_new`, `display_list_recorder_state_saver_new` (the C++ stack
objects as values), `display_list_recorder_command_capture_take`/`_destroy` and
`display_list_recorder_state_saver_destroy` (call `_destroy` where the C++ object leaves
scope), `display_list_player_cpu_create`.
- Private members are module-private (`build_ancestor_chain`, `execute_impl`,
`execute_display_list_into_surface`, `surface`, `end_capture`, the constructors).
## For the engine
- `CSS::ScrollbarColorData` and `CSS::InitialValues::scrollbar_color()` moved into the display list
(DESIGN.md §4.1.3): `display_list.ScrollbarColorData`, `display_list.initial_values_scrollbar_color()`.
The engine's `CssScrollbarColorData` and `css_initial_values_scrollbar_color` should forward to
them.
- The PaintableBox-dependent members stay in the engine as designed: `ScrollFrame(PaintableBox
const&, …)`, `ScrollFrame::paintable_box`, `ScrollState::create_scroll_frame_for` /
`create_sticky_frame_for` (append to `m_scroll_frames`), `BorderRadiusData::as_corner`,
`BorderRadiiData::as_corners`, `BordersData::to_device_pixels`.
- Players: `display_list_player_cpu_create()` then `display_list_player_execute(player, list,
&snapshot, surface)`.
## The CPU player
DisplayListPlayerCpu implements the 32 virtuals in DisplayListPlayerSkia.cpp's order with the
same decisions, each Skia call replaced by a CpuCanvas call:
- **Canvas** (`cpu_canvas`): layers (saveLayer with opacity, blend mode, luminance color filter,
blur, image filter, plus-darker by hand, backdrop filters), states (affine transform; clip as
device bounds plus an anti-aliased coverage mask when it is not a whole-pixel rectangle; clip
differences), `quickReject` with Skia's one-pixel outset.
- **Gradients** (`cpu_gradient`, `cpu_color_space`): linear, radial, two-point conical and sweep
shaders with SkGradientBaseShader's stop normalization, tile modes, degenerate cases,
premultiplied or unpremultiplied interpolation in sRGB, sRGB-linear, Lab, OkLab, Display P3,
A98, ProPhoto, Rec2020, HSL, HWB, LCH and OkLCH with the four hue methods. No dithering.
*Replaced on fix/fidelity-3d by the raster module's Skia gradients (INTEGRATION.md,
"Gradients"); `cpu_color_space` is gone.*
- **Blur** (`cpu_blur`): three box blurs (the SVG window sizes); box shadows blur the shape's
coverage with the mask filter's sigma mapped by the transform.
*Replaced on fix/fidelity-3d by Skia's blur mask filter (INTEGRATION.md, "Box shadows").*
- **Surfaces**: the player draws on a canvas per PaintingSurface, made from
`painting_surface_read_into_bitmap` and written back with `write_from_bitmap` in `flush`
(only Ladybird's PaintingSurface API is used). Pattern tiles get a surface of their own
(`painting_surface_create_with_size`) whose canvas starts transparent.
- **Images**: `immutable_bitmap_bitmap` and the Bitmap's scanlines, converted to premultiplied
RGBA (BGRA/RGBA, x formats opaque).
### Seams to other regions
(Connected at integration: see INTEGRATION.md. The table below is the region's hand-off.)
Two functions in `display_list_player_cpu.lucb` trap with `unported: seam …` until their owner
fills them in (Ladybird has no API for either: the Skia player reaches into PathImplSkia and
FilterImpl through SkiaUtils):
| Seam | Owner | What it must do |
| --- | --- | --- |
| `to_raster_path(path) -> CpuPath?` | r10 (gfx.Path, PathImpl) | the Skia glue `to_skia_path`: the path's contours as a `raster.Path` with its fill type |
| `apply_gfx_filter(filter, pixmap)` | r10 (gfx.Filter, FilterImpl) | `to_skia_image_filter` applied to a pixmap in place |
Glyph runs are drawn from `Path::glyph_run`'s outlines (`text_blob_path`: web_fonts' stubs, then
`to_raster_path`). The text blob's scale lives in r09's CachedTextBlob; until the player can read
it, the outlines are drawn at scale 1, the test runner's only scale (FIXME in the code).
Text, paths, clip paths and filters draw once r09/r10 and these seams exist; everything else
draws today.
### Deviations from the Skia player
- Transforms are 2D: `apply_transform` uses the affine part of the 4x4 matrix (rows/columns 0,
1, 3); a perspective row is dropped (FIXME in the code). *Resolved by fix/fidelity-3d: see
INTEGRATION.md, "3D transforms".*
- Anti-aliased edges come from the raster module's 4x4 supersampling where Skia uses analytic
coverage: edge pixels of rounded rects, ellipses and lines differ by up to ~48 levels; interiors
match exactly. Rounded-rect corners are cubic arcs (Skia: conics).
- Gradients are not dithered; the mipmapped scaling mode samples bilinearly.
- The image filter of a layer is applied before its blur and luminance filter.
## Tests
`./test.sh` runs `luce-base test src/display_list --native` (70 tests).
- **The CPU player against Skia** (`tests_cpu_player`, data in `tests_skia_reference_data`): 23
scenes (rects, rounded rects and clips, fractional clips under a scale, opacity and multiply
layers, translate, rotation, radial/conic/linear gradients, outer and inner box shadows,
ellipses, rects, solid/dotted/dashed lines) compared with the pixels DisplayListPlayerSkia
renders for the same display list, under Ladybird's fuzzy rule. Gradients, shadows, layers and
clips under transforms are within 1–2 levels; only anti-aliased edges differ more.
- **Ported logic, pinned to the donor** (`tests_display_list`): tree building, dumps, hit testing,
the command loop's exact virtual-call sequence (with a recording player; also culled), command
dumps and bounds, the recorder's nesting, capture/replay and masks, spread adjustments and
`CornerRadii::contains`. The expected values were printed by the donor's own C++ compiled
locally.
- `tests_cpu_canvas`, `tests_cpu_gradient`, `tests_scroll_and_paint_style`: the canvas, blur,
gradient math and color spaces (against CSS Color 4's values), scroll state, paint styles,
external content, initial values.
### Gates
Regions r08 and r10 are ported in parallel; tests that reach their stubs return early while
`gfx_geometry_is_ported` / `gfx_paint_is_ported` (`tests_support.lucb`) are false. **Set both to
true after merging r08 and r10.** Every gated test (7 of them, including the linear-gradient and
dotted/dashed-line scenes and the donor's full recorded display list) was run locally against
scratch stand-ins of the gfx functions (never committed) and passed.
## Compiler issues
None new. `luce-base check -W` on `display_list` prints only the `raster` module's five
pre-existing unused-function warnings (`f8_round_int`, `i8_to_f8`, `f8_to_i8_bitcast`,
`highp_lerp`, `lowp_source_over_k`), because `display_list` imports `raster`.