Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-browser-render

Source of release 0.6.2

0.6.2 / docs / regions / r08.md

# Region r08: gfx geometry (`gfx`) — what other regions need to know

Region r08 ports LibGfx's geometry and color value types and `LibWeb/PixelUnits`: Point, Size,
Rect, Quad, AffineTransform, Matrix<4, float> and the Matrix4x4 helpers, Color,
ColorConversion, ColorSpace, Cursor, Palette, TextAlignment, CSSPixels, CSSPixelFraction and
DevicePixels. Each fragment's header names the donor lines it ports, and `docs/namemap.tsv` lists
every name (kind `ported`, `dropped` or `addition`).

## Fragments

In `gfx/ORDER`, after the types: `pixel_units`, `point_int`, `point_float`, `point_css_pixels`,
`size_int`, `size_float`, `size_u32`, `size_css_pixels`, `rect_int_1`, `rect_int_2`,
`rect_float_1`, `rect_float_2`, `rect_css_pixels_1`, `rect_css_pixels_2`, `quad`,
`affine_transform`, `matrix`, `color_1`, `color_2`, `color_3`, `color_named`,
`color_conversion_1` to `_3`, `color_space`, `cursor`, `anonymous_buffer`, `palette_1`,
`palette_2`, `text_alignment`. The tests come last: `tests_css_pixels`, `tests_pixel_units`,
`tests_rect`, `tests_geometry`, `tests_quad`, `tests_affine_transform`, `tests_color_1` to `_4`.

## How the geometry reads

- **One set of functions per instantiation** (DESIGN.md §2.8), written out by hand from one
  instantiation: `int_point_*`, `float_point_*`, `css_pixel_point_*`; `int_size_*`,
  `float_size_*`, `size_of_u32_*`, `css_pixel_size_*`; `device_pixel_rect_*` (Rect<int>),
  `float_rect_*`, `css_pixel_rect_*`. There is no generator (`tools/gen_geometry` of DESIGN.md
  §2.8 was not needed): the three copies differ in their arithmetic.
- **DevicePixels is `i32`** in this port (the skeleton maps `AK::DistinctNumeric<int>` to its
  underlying type), so `DevicePixelRect` *is* Gfx::IntRect: use `device_pixel_rect_*` for
  IntRect too. DevicePixelPoint and DevicePixelSize are `IntPoint` and `IntSize`.
- **Values are built with the memberwise initializers**: `IntPoint(x, y)`,
  `FloatRect(FloatPoint(x, y), FloatSize(w, h))`,
  `CssPixelRect(CssPixelPoint(...), CssPixelSize(...))`. The `*_construct*` functions exist
  too, as the skeleton declared them.
- **CSSPixels arithmetic** is saturating fixed point. The C++ operators are free functions
  (`css_pixels_add_css_pixels(&a, b)`, ...) and also **one-line methods on the struct**
  (added by hand in `types_pixel_units.lucb`, DESIGN.md §2.8): `a.add(b)`, `sub`, `mul`,
  `mul_fraction`, `div` (answers a `CssPixelFraction`), `div_fraction`, `neg`, `abs`, `cmp`,
  `lt`, `le`, `gt`, `ge`, `to_float`, `to_double`, `to_int`, `raw_value`,
  `might_be_saturated`, and the statics `CssPixels.from_raw`, `from_int`, `from_f32`,
  `from_f64`. `CssPixels` conforms to `luce.Comparable` (`compare`), so `ak.min`, `ak.max` and
  `ak.clamp` take it. Structural `==` compares raw values, as the defaulted C++ `==` does.
- `CSSPixels(n)`: `css_pixels_from_int(i64)` (every signed Integral), `css_pixels_from_unsigned`,
  `css_pixels_from_f32` / `_f64` (the explicit float constructor = nearest_value_for).
  `CSSPixels(fraction)`: `css_pixel_fraction_to_css_pixels(&f)`.
- The `css_pixels_*` constants (`fixed_point_denominator`, `radix_mask`, `max_integer_value`,
  `min_integer_value`, `max_dimension_value`) are `let`s with their values (they were `var`s
  with the initializer in a comment).
- Mixed-type operators take the widest type of their kind: `eq_css_pixels_int(p, i64)`,
  `gt_css_pixels_int`, `lt_int`, `mul_css_pixels_int`, `mul_int_css_pixels`,
  `div_css_pixels_int`; the float/double overloads keep the skeleton's names
  (`eq_css_pixels_f32`, `lt_f64`, `mul_f32`, ...). The DevicePixels operators (`eq_i32`, `ne`,
  `gt_i32`, `lt_distinct_numeric`, `ge`, `le`: `(i32, i64)`; `mul_i32`, `mul_t_i32`, `div_i32`,
  `rem`: `(i32, i32)`) are plain integer operations.

## Signature and type changes against the skeleton

### Member templates became concrete functions

| C++ | Luce |
| --- | --- |
| `Point(U x, U y)` | `css_pixel_point_construct_int`, `float_point_construct_i32`, `int_point_construct_f32` (same for Size and Rect: `*_construct_int` / `_i32` / `_f32`, `size_of_u32_construct_i32`) |
| `explicit Point(Point<U>)`, `to_type<U>()` (and Size, Rect, and Rect's `(Point<U>, Size<U>)` constructor) | `<type>_to_type_<target>` with target `i32`, `f32` or `css_pixels`: int → f32, css_pixels; float → i32, css_pixels; CSSPixels → i32, f32; `Size<u32>` → i32, css_pixels |
| `to_rounded<int>`, `to_ceiled<int>`, `to_floored<int>` | `float_point_to_rounded_i32` (C's roundf), `float_point_to_ceiled_i32`, `float_point_to_floored_i32`, `float_size_to_rounded_i32`, `float_rect_to_rounded_i32` (AK::round_to) |
| `CSSPixelRect::to_rounded<CSSPixels>` (PixelUnits.h) | `css_pixel_rect_to_rounded` |
| `operator==(Point<U>)`, `Size::contains(Size<U>)`, `operator==(Size<U>)`, `operator==(Rect<U>)` | take the same type by value: `int_point_eq(&a, b)` |
| `Rect::contains(Container)`, `intersects(Container)` | `..._t_container(&r, others: const DevicePixelRect[])` (a span) |
| `linear_interpolate`, `quadratic_interpolate`, `cubic_interpolate` | FloatPoint only (the only T they compile for) |
| `smallest_of`, `largest_of` (AffineTransform.cpp, static) | private, f32 |
| `Matrix4x4 * Vector4` (`mul_opaque`) | `mul_float_matrix4_x4_float_vector4(m, v)`; `transform_point`, `translation_matrix`, `scale_matrix`, `rotation_matrix`, `extract_2d_affine_transform` take FloatMatrix4X4 / FloatVector3 (`extract_2d_affine_transform` a `const FloatMatrix4X4*`, as r51a calls it) and stay public (they are header `static`s every includer can call) |
| `CSSPixels::nearest_value_for<F>`, `floored_value_for<F>` | `_f32`, `_f64` |
| `CSSPixelFraction(I, I)`, `<=>(I)` | `css_pixel_fraction_construct_int`, `css_pixel_fraction_cmp_int`; also `css_pixel_fraction_construct_f64` (the FloatingPoint constructor) |

### Return and parameter types fixed

- Size functions answered the opaque `Size`; they answer their own type (`IntSize`, ...).
- `affine_transform_map_to_quad` answers `FloatQuad` (was the opaque `Quad`).
- Matrix functions answered the opaque `Matrix`; they answer `FloatMatrix4X4`.
  `float_matrix4_x4_construct(this, elements: const f32[])` takes the 16 elements row-major;
  `float_matrix4_x4_at(this, row, col) -> f32*`, `_at_const -> f32`;
  `float_matrix4_x4_elements -> f32[4][4]*`, `_elements_const -> const (f32[4][4])*`.
- Color part (see below): `color_space_color_space_sk_sp -> SkSpSkColorSpace*`;
  `palette_impl_theme`, `palette_theme -> const SystemTheme*` and
  `palette_impl_const -> const PaletteImpl*` (C++ returns references).

### Dropped (the donor cannot call them either)

Members declared for every T but not usable for that T: for CSSPixelPoint `constrain`,
`constrained`, `end_point_for_aspect_ratio`, `to_byte_string` (defined in Point.cpp, which
instantiates only int and float; PixelUnits.h has its own `constrained`), `pixels_moved`,
`distance_from`, `absolute_relative_distance_to` (AK::abs / AK::hypot<float> reject CSSPixels),
`to_rounded`, `to_ceiled`, `to_floored`; IntPoint `to_rounded` / `to_ceiled` / `to_floored`;
CSSPixelRect `from_two_points` (AK::abs) and `to_byte_string`; CSSPixelSize and Size<u32>
`to_byte_string` and `to_rounded`, IntSize `to_rounded` (round_to takes a float); Size<u32>
`scale_by(Point<u32>)` / `scaled(Point<u32>)` (no Point<u32>). They are `dropped` in the
namemap. `to_type<double>` has no target (no Double* types in the skeleton).

### Types fixed or added by hand

- `types_pixel_units`: the constants, the CssPixels methods and `Comparable` (above).
- `types_traits`: `CssPixelsTraits` and `IntSizeTraits` are implemented (Traits<CSSPixels>,
  Traits<Size<T>>).
- `types_matrix`: `FloatMatrix4X4.m_elements` is `f32[4][4]` (was `(f32*?)*?`).
- `types_quad`: `FloatQuad` (Gfx::Quad<float>) with `m_p1`..`m_p4`.
- `types_vector_n` (new): `FloatVector3`, `FloatVector4` holding `m_data` (VectorN's
  `Array<T, N>`), for the Matrix4x4 helpers; VectorN's methods are not ported (phase 4 users).
- Color part: `types_color_conversion` (ColorComponents' C++ defaults), `types_color_space`
  (the Skia stand-ins `SkcmsTransferFunction`, `SkcmsMatrix3x3`, `SkColorSpacePrimaries`,
  `SkColorSpace`, `SkSpSkColorSpace`; `ColorSpaceImpl.color_space: SkSpSkColorSpace`),
  `types_coding_independent_code_points` (the Media enums and fields), `types_system_theme`
  (SystemTheme's arrays), `types_anonymous_buffer` (`CoreAnonymousBuffer.m_impl`,
  `CoreAnonymousBufferImpl`).
- `module.lucb` imports `luce`, `math`, `math32` and `memory` (C's libm calls — roundf, floorf,
  lroundf, pow, cbrtf ... — are luce-std's math/math32, which call the same entry points; AK's
  own math functions are ak's).

## Color, ColorSpace, Palette, Cursor, TextAlignment

- Constructor-shaped helpers for expressions: `color_new_u8_u8_u8`, `color_new_u8_u8_u8_u8`,
  `color_new_named_color`, `color_components_new`.
- Functions with internal linkage in C++ are private: `nth_digit`, `format_to_8bit_compatible`,
  `parse_rgb_color`, `parse_rgba_color`, `hex_string_to_color`, `color_from_linear_srgb`,
  `rectangular_to_polar`, `polar_to_rectangular`.
- **ColorSpace** wraps a stand-in for Skia's SkColorSpace (transfer function + toXYZD50).
  `from_cicp` ports the Skia/skcms code it needs (named primaries and transfer functions,
  `SkColorSpacePrimaries::toXYZD50`, `MakeRGB`'s checks and sRGB singletons), bit-exact with the
  donor's Skia. `load_from_icc_bytes` keeps the empty-profile path; a non-empty ICC profile fails
  with a FIXME (skcms_Parse is not ported; images are phase 2).
- **Core::AnonymousBuffer** (`anonymous_buffer.lucb`): LibCore is no region's, and PaletteImpl
  keeps its SystemTheme in one, so r08 ports `create_with_size`, `is_valid`, `size`, `data`
  over zeroed atomic managed memory with no file descriptor. **r10** (Bitmap's anonymous-buffer
  functions) should use these rather than add its own.
- Palette's setters always clone the PaletteImpl (C++ clones when the impl is shared; there are
  no reference counts here).
- The IPC encoders/decoders and AK `Formatter`s of these files are not ported.

## Tests

`./test.sh` runs `luce-base test src/gfx` (289 tests):

- Donor tests, every case: `Tests/LibWeb/TestCSSPixels.cpp` (14), `Tests/LibGfx/TestRect.cpp`
  (6), `TestQuad.cpp` (4; on Quad<float>, where the donor uses Quad<u8>/Quad<int>: every
  intermediate is a small exact integer), `TestColor.cpp` (8).
- Pinned to the donor: values computed by the donor's headers and libraries compiled locally
  (the drivers stay in `.donors`/scratch, not in the repository), compared exactly (floats by
  bits, CSSPixels by raw value): 80 PixelUnits cases, 112 Point/Size/Rect cases over every
  instantiation, 39 AffineTransform/Matrix/Matrix4x4 cases, and 24 Color/ColorConversion/
  ColorSpace/Palette/TextAlignment/Cursor groups (hundreds of values each).

## Deviations

- `CSSPixels::operator-()` and `abs()` of `CSSPixels::min()`, and `ceil` within 1px of the
  maximum, overflow `int` in C++ (undefined); the port wraps (`-%`, `+%`, ak.abs_i32), what the
  donor's machine code does outside constant folding.
- `CSSPixels::operator/=` multiplies in the donor; kept (`# donor bug:`), and so does
  `CSSPixelPoint::operator/=`.

## Compiler issue

`const T[N]*` lost its `const` (`const f32[4][4]*` was read as `f32[4][4]*`):
`.donors/luce-browser-tools/compiler-issues/const_array_pointer_drops_const.lucb`. Fixed in Luce
0.8.13; `float_matrix4_x4_elements_const` returns `const f32[4][4]*`.