Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-render

Source of release 0.6.2

0.6.2 / docs / regions / r10.md

# Region r10: gfx paint model (`gfx`, part of `web_fonts`) — what other regions need to know

Region r10 ports LibGfx's paint model: Bitmap, BitmapSequence, ShareableBitmap, ImmutableBitmap,
PaintingSurface, Path, PaintStyle, Filter, Gradients, FourCC and Painter. Ladybird implements
these over Skia. In the port Skia is replaced by the `raster` module (the tiny-skia port,
DESIGN.md §7.3) and by ports of the few Skia pieces whose results LibWeb depends on. Each
fragment's header names the donor lines it ports or replaces, and `docs/namemap.tsv` lists every
name (kinds `ported`, `replaced`, `dropped`, `addition`).

## Fragments

`gfx/ORDER`, after the types and before the stubs:

- **Donor files:** `four_cc`, `gradient_painting`, `paint_style`, `bitmap`, `bitmap_sequence`,
  `shareable_bitmap`, `filter`, `immutable_bitmap`, `painting_surface`, `path`, `painter`.
- **Skia replacements:**
  - `raster_utils` (SkiaUtils);
  - `path_impl_raster` (PathSkia);
  - `painter_raster` (PainterSkia).
- **Skia ports** (m144, the pathref variant; see *Path* below): `sk_scalar`, `sk_matrix`,
  `sk_geometry`, `sk_conic`, `sk_path`, `sk_path_iter`, `sk_path_contains`, `sk_parse_path`,
  `sk_path_measure`.
- **Tests, last:** `tests_sk_path`, `tests_sk_path_cases`, `tests_sk_path_measure`,
  `tests_gfx_paint`, `tests_gfx_paint_export`, `tests_gfx_paint_draw`.

`web_fonts/ORDER`: `path` replaces `stub_r10_gfx_paint`. It holds the Path members that name
Font or GlyphRun, and the abstract PathImpl.

`gfx/module.lucb` gains these imports:

- `memory`, `math32`, `math`;
- `c as libc` (for snprintf, `%.8g`);
- `luce_browser_render.raster as raster`.

`web_fonts/module.lucb` gains `math32`.

## Path

- **The implementation.** `gfx.Path.m_impl` is a `PathImplRaster*?`. This replaces PathImplSkia,
  the donor's only PathImpl.
  - `none` is the empty path that C++'s default `m_impl { PathImpl::create() }` makes. A zero
    Path is therefore valid, and the first mutation creates the implementation.
  - **The C++ copy constructor is `path_clone`.** A Luce struct copy shares the implementation.
- **Virtual dispatch is flattened.** PathImpl's virtuals are not dispatched: the `gfx.path_*`
  functions call the `path_impl_raster_*` functions directly.
  - web_fonts' abstract `PathImpl` has no implementation. Its pure virtuals trap.
  - `path_impl`, `path_impl_const`, `path_construct` and `path_impl_create` trap as
    `replaced`. Nothing in LibWeb outside DisplayListPlayerSkia calls them.
- **Why an SkPath port.** PathImplRaster holds an `SkPath`, a port of the parts of Skia's SkPath
  that PathImplSkia uses:
  - verbs, points and conic weights, with Skia's editing rules: moves collapse, a close
    re-moves, and a move is injected where needed;
  - the SVG `arcTo` (arcs become conics);
  - `addPath`, `offset` and `transform` (SkMatrix with its type-mask dispatch);
  - `getBounds` (the bounds of all points);
  - `contains` (SkPathPriv::Contains with the winding and tangent tests);
  - `SkParsePath::ToSVGString` (`%.8g`, with conics written as quads within 1/1024);
  - `SkPathMeasure` / `SkContourMeasure`, for `place_text_along`.

  `to_svg_string` appears in dumps, and bounds, arcs and hit tests must match Skia. The
  rasterizer's own path type has none of these, so DESIGN.md §7.2's "implement on the
  rasterizer's path type" was not enough. The tests compare the results bit for bit with the
  donor's Gfx::Path.
- **For drawing,** `gfx.path_to_raster_path(&path) -> raster.Path?` (or
  `sk_path_to_raster_path`) converts the path.
  - Conics stay conics (since the raster-skia merge the raster module keeps and draws them as Skia does).
  - The caller releases the result (`memory.heap`). An empty path gives none.
  - The fill rule is passed to the raster module separately (`to_raster_fill_rule`).
- `gfx.path_sk_path(&path)` and `path_sk_path_const` give the SkPath (PathImplSkia::sk_path()).
- **Not supported:** `path_intersect`. It traps, because SkPathOps is not ported, and LibWeb
  never calls `Path::intersect`.
- **Waiting for r09** (connected at integration, see INTEGRATION.md). `path_text_*`, `path_glyph_run` and `path_place_text_along_*` in
  web_fonts are ported around two seams that trap until region r09's font reader exposes
  them:
  - `path_glyph_outline(font, glyph_id) -> gfx.SkPath?` stands for SkFont::getPath at the
    font's pixel size: in pixels, y down, origin on the baseline.
  - `path_glyph_advance(font, glyph_id) -> f32` stands for SkFont::getWidths.

  Everything around the seams is ported: text to glyphs, positions, placement along the
  measured path, rotation, and the midpoint cut-off.

## Bitmaps and surfaces

- **Memory.** Bitmap pixels are atomic managed storage (`ak.kmalloc_atomic`, zeroed when C++
  uses `kcalloc`). There is no destructor, and `m_destruction_callback` is never run.
- **`raster_utils` replaces SkiaUtils.**
  - Type conversions: `to_raster_color`, `to_raster_transform`, `to_raster_fill_rule`,
    `to_raster_cap`, `to_raster_join`, `to_raster_filter_quality` and `to_raster_blend_mode`.
  - Pixel conversion: `raster_load_bitmap` / `raster_store_bitmap` convert between any Bitmap
    format or alpha type and the raster module's premultiplied RGBA. They behave as Skia reads
    and writes pixels of those color types.
  - Premultiplication: `raster_premultiply_row` / `raster_unpremultiply_row` are SkOpts'
    `RGBA_to_rgbA` / `rgbA_to_RGBA`, pinned to Skia.
- **PaintingSurface** always takes the donor's CPU path: its pixels are a Bitmap.
  - **Drawing:** bracket each draw with
    `painting_surface_begin_raster(surface) -> raster.PixmapMut` and
    `painting_surface_end_raster(surface)`, which replace the SkCanvas (PainterSkia's
    `with_canvas`).
    - A premultiplied RGBA8888 bitmap whose pitch is exactly four bytes per pixel is drawn
      into directly.
    - Any other bitmap is converted into a buffer at the outermost begin and back at the
      matching end.
    - The display-list player (r51a) should draw through this pair. It can make its surfaces
      RGBA8888 premultiplied to avoid the conversion.
  - **Snapshots:** `painting_surface_snapshot_bitmap(surface) -> Bitmap*` copies the surface
    and stands in for `sk_image_snapshot`.
  - **Trapping (`replaced`):** `canvas`, `sk_surface` and `sk_image_snapshot`.
  - **Not supported:** `create_from_shared_image_buffer` (Metal).
  - The lock and unlock functions assert that there is no GPU context.
- **ImmutableBitmap** always holds its Bitmap. `immutable_bitmap_bitmap` never reads pixels
  back, and width, height and alpha type come from the bitmap.
  - `sk_image()` traps, and `create_from_yuv` is not supported (YUVData is Rust code in the
    donor).
  - `export_to_byte_buffer` converts pixels with the raster pipeline's float math, as Skia's
    drawImageRect onto a surface of the export color type does. The whole of
    TestImmutableBitmap.cpp passes.
- **Bitmap**
  - `scaled()` draws through the raster module. For nearest sampling it uses Skia m144's
    "round down at integer" rule itself, since tiny-skia lacks it (see *Raster module* below).
  - `set_alpha_type_destructive` follows the donor's non-macOS path (Skia's SkConvertPixels).
    The macOS build uses vImage instead.

## Painter

`painter_create(bitmap)` answers a `PainterRaster`, the replacement of PainterSkia.

- `painter_class` now covers class ids 0 and 1, and PainterRaster has class id 1
  (`painter_raster_class`).
- It keeps SkCanvas's matrix and clip, as a coverage mask, and saves and restores them. That
  state belongs to the painter, where Skia keeps it on the surface.
- **Differences, reported with `dbgln` FIXMEs:**
  - blur mask filters (the `blur_radius` overloads draw unblurred);
  - image filters on paints;
  - pattern repetition other than repeat-both;
  - conic gradients, which PainterSkia does not support either.
- **plus-darker traps.** `to_raster_blend_mode(plus_darker)` traps: the donor uses an SkSL
  runtime blender there.

## Filter

A Filter's `FilterImpl.filter` is an `ImageFilter*?`: one node of the graph the donor builds out
of SkImageFilters.

- **The node types** are `ImageFilterNode`, `ImageFilterShader` and `ColorFilter` /
  `ColorFilterNode`, in `types_filter_impl`.
- **Each node** records the SkImageFilters factory and its arguments. The color matrices are
  computed exactly as the donor computes them, including SkColorMatrix::setSaturation.
- **Evaluating the graph** is the display-list player's job.
- **`filter_impl(&filter)`** answers `const FilterImpl*`.

## Signature and type changes against the skeleton

- **Parameters that are `const&` in C++ now take pointers:**
  - `bitmap_diff(this, other: const Bitmap*)`;
  - `get_metadata(bitmap: const Bitmap*)`, which is public because its callers, the IPC
    encoders, are not ported;
  - `painting_surface_write_from_bitmap(this, bitmap: const Bitmap*)`;
  - `path_append_path` / `path_intersect(this, other: const Path*)`;
  - `filter_image(bitmap: const ImmutableBitmap*, ...)`;
  - `filter_merge(inputs: const ak.Vector[Filter?]*)`;
  - in web_fonts: `path_text_*(…, font: const Font*)`, `path_place_text_along_*(…, font:
    const Font*)` and `path_glyph_run(this, glyph_run: const GlyphRun*)`.
- **`filter_impl`** returns `const FilterImpl*`, and `filter_impl_create` takes an
  `ImageFilter*?`.
- **`calculate_gradient_length` and `calculate_gradient_length_f32`** take a `FloatSize` and are
  not generic. Size<float> is the only instantiation.
- **Dropped:** `export_format_to_skia_color_type`, `to_skia_alpha_type` and
  `origin_to_sk_origin`, private conversions to Skia enums that the replaced code does not need.
- **Types filled in:**
  - `Path.m_impl`;
  - `FilterImpl.filter` and the ImageFilter and ColorFilter types;
  - `PaintingSurfaceImpl`'s fields;
  - `BitmapDiffResult`'s fields;
  - the ImmutableBitmapImpl comments and `export_flags_premultiply_alpha` /
    `export_flags_flip_y`;
  - `painter_class.last_id`;
  - `FourCcTraits` (hash = `to_u32`).

## Integration notes

- **r08 (geometry, Color):** r10 calls r08's functions, and they are stubs in this branch.
  - The tests that need them return early while `tests_gfx_paint_r08_is_ported` is false. Set
    it to true when merging.
  - All of them passed while porting against local implementations of those functions.
- **Core::AnonymousBuffer:** r08 ports it: `core_anonymous_buffer_create_with_size`,
  `is_valid`, `size` and `data`. This branch does not have those functions yet. At
  integration, restore the donor's bodies of:
  - `bitmap_create_shareable` (an anonymous buffer, rounded up to the page size);
  - `bitmap_create_with_anonymous_buffer` and `bitmap_construct_core_anonymous_buffer`
    (these trap here);
  - `bitmap_to_bitmap_backed_by_anonymous_buffer` (answer `this` when `m_buffer` is valid);

  all over those functions.
- **`tests_gfx_paint_raster_is_skia_m144`** gates the painter cases whose pixels depend on the
  raster-module differences below. It keeps the donor's pixels for them.

## Raster module against the donor's Skia (for the lead)

The donor's Skia is m144, while tiny-skia follows an older Skia. The painter tests found three
differences in the `raster` module:

1. **Anti-aliasing.** Skia m144 fills paths with analytic AA (SkScan_AAAPath); tiny-skia
   supersamples 4×4, with coverage in steps of 16. On an anti-aliased triangle, most edge
   pixels differ.
2. **Lowp blending.** Skia's lowp `div255` rounds differently from tiny-skia's `(v + 255) >> 8`.
   Blending a translucent color over an opaque one is off by one in a channel.
3. **Nearest sampling.** Skia m144's SkImageShader sets `roundDownAtInteger`, so an exact
   integer sample coordinate picks the pixel before it. tiny-skia does not. `Bitmap::scaled`
   works around it, but raster draws (draw_bitmap, patterns) do not.

## Tests

`./test.sh` now runs `luce-base test src/gfx`: 69 tests. While the r08 gate
is closed, the tests (or the parts of tests) that need r08's functions return early.

- **The Skia path port:** 47 tests, pinned to the donor's Gfx::Path and SkPathMeasure through
  local C++ drivers.
  - `to_svg_string`, bounds and last points bit for bit;
  - `contains` under both fill rules;
  - arcs, transforms, append, and `%.8g` edge cases;
  - SkMatrix and conic unit tests.
- **Tests/LibGfx/TestImmutableBitmap.cpp:** every subtest.
- **Pinned to the donor:**
  - color_stop_step and the Gradients.h helpers;
  - SVGGradientPaintStyle::set_gradient_transform;
  - Skia's premultiply and unpremultiply;
  - Bitmap: set and get in all four formats, crop, clone, diff, strip, alpha-type
    conversion, `scaled` (nearest, bilinear, and unpremultiplied);
  - PainterSkia's pixels for opaque fills, clear_rect, stroke, clip/save/restore/reset and
    draw_bitmap;
  - PaintingSurface read and snapshot;
  - gfx.Path through its C++ API;
  - Filter matrices;
  - FourCC and PaintStyle.
- The expected values came from local C++ programs over the donor build. They stay out of the
  repository.

## Donor quirks

- **`get_pixel` on a snapshot.** ImmutableBitmap::get_pixel dereferences `m_impl->bitmap`
  without calling bitmap() first, so in the donor it crashes on a surface snapshot. The port
  always has the bitmap and answers the pixel.