Mirrors/eepp
1
0
Fork 0
mirror of https://github.com/SpartanJ/eepp.git synced 2026-10-02 03:00:23 +03:00
Code Issues Packages Projects Releases Wiki Activity

graphics: improve native system font fallback

Browse Source 
Initialize SystemFontResolver when enabled and make its lifecycle and font-list
population thread-safe.

Use native codepoint fallback matching through Fontconfig on Linux, BSD, and
Haiku, DirectWrite on Windows, and Core Text on macOS and iOS. Preserve the
cached FreeType scan as a fallback when native matching is unavailable.

Enable system fonts by default for UIApplication and warm the font database in
the background. Allow applications to override the policy and disable the
automatic default in the unit-test runner.

Fix glyph fallback checks to respect the resolver's enabled state and add
coverage for concurrent warm-up and shaped symbol fallback.

Update efsw.
This commit is contained in:
Martín Lucas Golini
2026-08-23 16:59:23 -03:00
parent 89487fec8b
commit 301b7458d2
15 changed files with 756 additions and 1461 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agent/plans/eepp_css_selector_optimization_plan.md
+123 -1011
View File
File diff suppressed because it is too large Load Diff
.agent/plans/eepp_superluminal_gui_html_optimization_plan.md
+33 -108
View File
@@ -1,5 +1,34 @@
# eepp Superluminal GUI/HTML Optimization Plan - 2026-07-09
## Status (updated 2026-08-23)
Implemented since this plan was written:
### Item 3 — Fast-parse common CSS lengths without allocations: DONE
`StyleSheetLength::fromString()` trims once, scans numeric prefixes directly from a
`std::string_view`, and converts through `String::fromString()` view overloads; the CSS parser
no longer builds number/unit strings or retries parsing by removing characters. Function
expressions retain the existing parser.
- Focused benchmark median for 320,000 mixed values: 13.67 ms → 10.10 ms, a 26.1% reduction.
- Post-change full release suite: 737 passed, one skipped.
### Item 10 — Broaden hot accessor/type-check inlining beyond selector code: DONE (core hierarchy)
Trivial `getType()` / `isType()` implementations for `Node`, `UINode`, `UIWidget`, `UILayout`,
`UIHTMLWidget`, and `UIRichText`, plus `Node::isLayout()`, are now inline.
- `UISceneNode::invalidateLayout()`: 86.1 ms inclusive / 41.5 ms exclusive → 26.3 ms total.
- Base type accessor symbols largely disappeared from the hot function list.
- `getEffectiveWhiteSpaceCollapse()`: 344.0 ms → 162.9 ms inclusive, partly from cheaper type checks.
- Unit-test process CPU time: 20.12 s → 19.88 s (~1.2%, directional only).
Further subclass inlining (table widgets) remains possible but is not an independent priority
here; it can be folded into other items if needed.
All remaining items (1, 2, 4–9, 11, 12) are **not started**.
## Goal
Use the Superluminal capture from `2026-07-09_19-52-19_eepp-unit_tests` to identify cheap, low-risk optimization work in eepp's GUI, text, and HTML compatibility layers. This plan intentionally ignores unit-test-specific hotspots such as `EE::Graphics::Image::diff()` and focuses on code paths likely to matter in real applications and `ecode`.
@@ -58,7 +87,6 @@ Approximate aggregate timings from the capture:
| White-space inheritance lookup | `getEffectiveWhiteSpaceCollapse`: ~406 ms inclusive, 3235 calls |
| Text width measurement | `Text::updateWidthCache`: ~142 ms inclusive, 916 calls |
| Font glyph/kerning lookup | `FontTrueType::getGlyphByIndex`: ~338 ms inclusive, 2189 calls; `getKerning`: ~72 ms inclusive, 525 calls |
| CSS length parsing | `StyleSheetLength::fromString`: ~44.7 ms exclusive / ~106.9 ms inclusive, 872 calls |
| CSS style selection | `StyleSheet::getElementStyles`: ~154 ms inclusive; `StyleSheetSelector::select`: ~116 ms inclusive; `StyleSheetSelectorRule::matches`: ~55 ms inclusive |
| HTML load/style reload | `UIHTML_KittyHomeSmallDoesNotHang` branch: `loadLayoutFromString` ~199 ms, recursive `reloadStyle` ~101 ms, `updateDirtyLayouts` ~185 ms |
@@ -121,58 +149,6 @@ Validation:
- Existing `UIHTML.*white*`, `UIRichText.*`, and text-transform tests.
- Add a nested span test with inherited `white-space`, local `white-space-collapse`, and nested text-transform override.
### 3. Fast-parse common CSS lengths without allocations
**Status: Implemented and measured**
`StyleSheetLength::fromString()` now trims once, scans scalar numeric prefixes directly from a
`std::string_view`, and converts the numeric subview through `String::fromString()`. The core string
API exposes `std::string_view` numeric overloads while retaining exact `std::string` forwarding
overloads for source and ABI compatibility with the implicitly constructible `EE::String` type.
The CSS parser no longer builds separate number/unit strings or retries parsing by removing
characters. Function expressions retain the existing parser, and position keywords map directly
to percentage lengths without recursive string construction.
Validation includes signed values, leading-dot decimals, scientific notation, surrounding
whitespace, position keywords, unitless and unknown units, `pxAsDp`, all existing CSS function
tests, and a dedicated release benchmark.
- Final focused benchmark median for 320,000 mixed values: 13.67 ms to 10.10 ms, a 26.1%
reduction.
- Before numeric conversion was centralized in `String`, the full-suite capture measured 105.4 ms
inclusive / 44.6 ms exclusive to 46.5 ms / 12.4 ms. A future full capture should refresh those
aggregate numbers for the final implementation.
- Post-change full release suite: 737 passed, one skipped.
Comparison capture:
```text
/tmp/eepp-unit-tests-length-fast-path-2026-07-10.linux
```
Files:
```text
src/eepp/ui/css/stylesheetlength.cpp
include/eepp/ui/css/stylesheetlength.hpp
```
Current hot section: `src/eepp/ui/css/stylesheetlength.cpp:391`.
`StyleSheetLength::fromString()` allocates `num`, allocates `unit` via `substr`, lower-hashes the whole string before knowing whether it is a keyword, and may repeatedly call `String::fromString()` while popping characters.
Proposed cheap path:
- First scan a trimmed `std::string_view`.
- If the first non-sign character is numeric or `.`, parse numeric prefix directly and pass the unit suffix as `std::string_view`.
- Add `unitFromString(std::string_view)` and avoid constructing `unit`.
- Only call `String::hashToLower()` for non-numeric keyword candidates.
- Keep the existing function-parser path for `calc()`, `min()`, `max()`, and `clamp()`.
Validation:
- CSS length parser tests for signed values, decimals, percentages, unitless `0`, `pxAsDp`, keywords, and function strings.
### 4. Avoid duplicate content-offset and size work in `UIRichText::rebuildRichText()`
Files:
@@ -345,57 +321,6 @@ Validation:
- Existing layout loading tests.
- HTML fixture tests involving inherited color/font/white-space and immediate layout after load.
### 10. Broaden hot accessor/type-check inlining beyond selector code
**Status: Core hierarchy implemented and measured**
The trivial `getType()` / `isType()` implementations for `Node`, `UINode`, `UIWidget`,
`UILayout`, `UIHTMLWidget`, and `UIRichText` are now inline, along with `Node::isLayout()`.
In the comparable full-suite captures:
- `UISceneNode::invalidateLayout()` decreased from 86.1 ms inclusive / 41.5 ms exclusive to
26.3 ms total.
- Base type accessor symbols largely disappeared from the hot function list.
- `getEffectiveWhiteSpaceCollapse()` decreased from 344.0 ms to 162.9 ms inclusive, partly
because its repeated type checks became cheaper.
- Unit-test process CPU time decreased from 20.12 s to 19.88 s, approximately 1.2%. Treat this
whole-process result as directional because the full suite contains rendering and image-diff
noise.
Further subclass inlining remains possible, especially table widgets, but the next independent
high-value target is CSS length parsing.
Files:
```text
include/eepp/scene/node.hpp
include/eepp/ui/uiwidget.hpp
include/eepp/ui/uinode.hpp
include/eepp/ui/uilayout.hpp
```
The selector optimization plan already lists some inlining work. This capture shows the same issue in rich-text and layout code:
```text
Node::getParent: ~37.7 ms exclusive
Node::getType: ~36.1 ms exclusive
UIWidget::isType: ~37.6 ms exclusive
UINode::isType: ~26.9 ms exclusive
UIHTMLWidget::isType / getType: ~32.0 ms combined
```
Proposed cheap path:
- Execute the accessor-inline phase from the CSS selector plan, but validate impact on rich-text/layout too.
- Include `getType()`/`isType()` candidates for `UINode`, `UIWidget`, `UILayout`, `UIHTMLWidget`, `UIRichText`, and table element subclasses where definitions are trivial.
- Keep ABI/ODR constraints in mind; remove matching out-of-line definitions where required.
Validation:
- Full build and unit test smoke.
- `git diff --check` and one focused HTML/rich-text filter.
### 11. Keep CSS selector optimization in the existing dedicated plan
Files:
@@ -415,11 +340,11 @@ StyleSheetSelector::select: ~116 ms inclusive
StyleSheetSelectorRule::matches: ~55 ms inclusive
```
Do not duplicate that work here. When executing this plan, treat selector indexing, sibling combinator correctness, and class/hash matching as owned by `eepp_css_selector_optimization_plan.md`.
Do not duplicate that work here. When executing this plan, treat selector instrumentation and any further selector work as owned by `eepp_css_selector_optimization_plan.md` (its Phases 1–3 and 5–8 are done; Phase 4 instrumentation plus optional Phases 9–10 remain).
Small complementary task:
- If a style reload batching change is implemented first, rerun the same capture or filtered HTML tests before starting selector indexing. Batching may reduce selector call volume and change the measured priority.
- If a style reload batching change is implemented first, rerun the same capture or filtered HTML tests before starting further selector work. Batching may reduce selector call volume and change the measured priority.
### 12. Add a repeatable profiling harness for these focused cases
@@ -451,12 +376,12 @@ The goal is not new product code, but a repeatable before/after measurement path
## Suggested Execution Order
1. Fast local wins: CSS length parsing, white-space collapse reuse, duplicate content-offset/size work.
1. Fast local wins: white-space collapse reuse, duplicate content-offset/size work.
2. Dirty layout invalidation coalescing.
3. RichText update-layout de-duplication and buffer reuse.
4. Text/glyph/kerning metrics helper.
5. Style reload batching.
6. Existing CSS selector optimization plan.
6. Remaining items of the CSS selector optimization plan (Phase 4 instrumentation first).
## Non-Goals For This Pass
.agent/plans/html_replaced_elements_auto_margin_plan.md
-280
View File
@@ -1,280 +0,0 @@
# HTML Replaced Elements and CSS Auto-Margin Plan
Status: proposed follow-up after the Asahi Linux async inline-image regression fix, 2026-08-02.
## Goal
Replace formatting-role inference with an explicit CSS used-value model for margins and make
`UIHTMLImage` a real `UIHTMLWidget` replaced element rather than a native `UIImage` with an HTML
flag.
The end state should provide:
- CSS `display`, positioning, float, intrinsic sizing, and used-margin behavior from
`UIHTMLWidget` for `<img>`;
- reusable image loading, drawable ownership, intrinsic dimensions, aspect ratio, and painting
shared with native `UIImage` through composition;
- formatting-context-specific auto-margin resolution based on the generated CSS box, not widget
type or `SizePolicy` heuristics;
- deterministic behavior across synchronous and asynchronous stylesheet/image loading;
- no image-specific exceptions in `BlockLayouter`, `UIRichText`, or `FlexLayouter`.
## Current State and Problem
`UIHTMLImage` currently derives from `UIImage`. It adds HTML identity, `alt`, and fallback text,
but it does not inherit the CSS layout state owned by `UIHTMLWidget`:
- `CSSDisplay` and blockification;
- `CSSPosition`, float, and clear;
- box sizing and CSS used-size helpers;
- layouter selection and formatting-context participation;
- normal-flow and out-of-flow classification;
- baseline behavior shared by other HTML boxes.
As a result, HTML layout infers an image's formatting role from combinations of:
- `UI_HTML_ELEMENT`;
- `SizePolicy`;
- concrete widget type;
- parent layout context.
That inference caused the Asahi regression. An inline `<img>` with `margin-left:auto` and
`margin-right:auto` was passed to the generic native block auto-margin calculator. During async
SVG loading, stale parent width was converted into large image margins, the inline anchor expanded
to include them, and repeated layout fed the expanded width back into the next pass.
The immediate fix centralizes formatting-context used margins, but still classifies some boxes
indirectly. This plan replaces that compatibility layer with explicit CSS box semantics.
## Standards Baseline
Implement against CSS used values, keeping these cases distinct:
1. Inline non-replaced and inline replaced boxes: horizontal `auto` margins use `0`.
2. Normal-flow inline-block boxes, replaced or non-replaced: horizontal `auto` margins use `0`.
3. Floats, replaced or non-replaced: horizontal `auto` margins use `0`.
4. Normal-flow block boxes: solve horizontal margins and width using the block constraint
equation; two auto margins center a definite-width box.
5. Absolutely/fixed positioned boxes: solve margins together with `left`, `right`, and `width`;
auto margins are not unconditionally zero.
6. Flex and grid items: use their module-specific auto-margin algorithms, not block formatting
rules.
7. Vertical auto margins: preserve the rules of the applicable formatting model. Do not fold them
into a horizontal-only shortcut.
Primary references:
- CSS 2.2 section 10.3, Calculating widths and margins.
- CSS 2.2 sections 10.3.1 through 10.3.10 for normal flow, replaced boxes, floats,
inline-blocks, and positioned boxes.
- CSS 2.2 section 10.6 for heights and vertical margins.
- CSS Display Level 3 for inner/outer display roles and blockification.
- CSS Flexbox section 8.1 and CSS Grid alignment rules for auto margins on flex/grid items.
- HTML rendering rules and replaced-element behavior for `img`.
## Design Direction
### Separate CSS box semantics from image mechanics
Change the inheritance direction to:
```text
UIWidget
├── UIImage native eepp image widget
└── UIHTMLWidget
└── UIHTMLImage HTML replaced element
```
Do not copy `UIImage` wholesale into `UIHTMLImage`. Extract reusable image mechanics into a
non-widget component or small set of helpers, tentatively named `UIImageContent`:
```text
UIImageContent
├── DrawablePtr and resource-change connection
├── local/remote/deferred source loading
├── intrinsic pixel size and aspect ratio
├── scale mode, tint, destination-size calculation
├── sprite scheduling support
└── drawable painting
```
Both `UIImage` and `UIHTMLImage` own an `UIImageContent` instance and provide narrow host callbacks
for scene/resource access, size changes, invalidation, and main-thread delivery.
The component must not own layout policy, CSS display, margins, padding, borders, position, or
parent geometry. Those remain widget responsibilities.
### Represent formatting role explicitly
Introduce a small formatting-role/used-value input derived from computed CSS state after
blockification, for example:
```cpp
enum class CSSFormattingRole {
Inline,
InlineBlock,
NormalFlowBlock,
Float,
Absolute,
Fixed,
FlexItem,
GridItem,
Table
};
```
The exact enum is an implementation decision; avoid exposing redundant public API if existing
computed display/position state can produce the same result cheaply. The important invariant is
that used-margin resolution receives an explicit role and never guesses from `SizePolicy` or
concrete widget class.
Keep role derivation centralized near `UILayouterManager` / `UIHTMLWidget`, including CSS
blockification. Do not derive it separately in RichText, block, flex, grid, and positioned layout.
### Separate computed, resolved, and used margins
Preserve three concepts:
- specified/computed margin value, including the `auto` bit;
- resolved length for non-auto values, including percentages;
- used margin for the current formatting context and containing block.
Do not mutate the stored resolved margin merely to obtain a used value for one layout pass. Return
a stack-local used-margin structure instead. This prevents stale block auto margins from being
reused when display, position, float, or parent formatting context changes asynchronously.
Suggested API shape:
```cpp
struct CSSUsedMargins {
Rectf value;
Uint8 autoSides;
};
CSSUsedMargins resolveUsedMargins(
const UIHTMLWidget& box,
CSSFormattingRole role,
const CSSContainingBlockMetrics& containingBlock );
```
The final API can be smaller, but it must not call the generic native `UIWidget::calculateAutoMargin()`
for HTML formatting.
## Implementation Stages
### Stage 1 - Lock Down Current Behavior
- Keep the real Asahi WebView fixture test with a thread pool and weighted native host layout.
- Assert the logo image is 130px, its inline anchor matches that width, and document overflow stays
within a reasonable viewport-derived bound.
- Add focused tests for:
- inline `<img style="margin: auto">`;
- inline-block non-replaced element with horizontal auto margins;
- fixed-width normal-flow block with horizontal auto margins;
- block-level replaced image with horizontal auto margins;
- floated image with auto margins;
- absolutely positioned replaced and non-replaced boxes for the relevant inset combinations;
- flex and grid items with auto margins;
- display changes before and after deferred CSS/image completion.
- Where practical, compare numeric invariants against a browser reference.
### Stage 2 - Introduce Formatting-Role-Aware Used Margins
- Add one centralized role derivation function based on computed display, position, float, and
parent flex/grid state.
- Introduce a non-mutating used-margin resolver.
- Route `BlockLayouter`, `UIRichText`, positioned layout, flex, and grid through the appropriate
role-specific solver.
- Keep flex/grid distribution in their existing layouters; the shared resolver should identify and
defer those roles rather than reimplementing their algorithms.
- Remove `UIHTMLWidget::getFormattingContextLayoutPixelsMargin()` once all callers use the explicit
role API.
- Audit `UIWidget::calculateAutoMargin()` callers and retain it only for native eepp layout.
### Stage 3 - Extract Reusable Image Content
- Inventory every `UIImage` responsibility and split it into:
- image resource/content behavior suitable for reuse;
- native widget layout and alignment behavior that remains in `UIImage`.
- Create `UIImageContent` or equivalent without adding a second scene/widget hierarchy.
- Move drawable loading, async lifetime guarding, resource-change subscription, destination-size
calculation, tint/scale settings, and drawing helpers behind the component.
- Preserve the current shared `DrawablePtr` ownership and scene-scoped resource resolution.
- Keep async callbacks generation/lifetime guarded and main-thread UI mutation explicit.
- Add unit tests for the component through both native and HTML hosts; avoid exposing internals
solely for testing.
### Stage 4 - Rebase `UIHTMLImage` on `UIHTMLWidget`
- Change `UIHTMLImage` to inherit from `UIHTMLWidget` and own shared image content.
- Implement it as a replaced element with:
- intrinsic width, height, and ratio from the decoded drawable/SVG;
- CSS width/height/min/max/box-sizing integration;
- default inline outer display and atomic inline participation;
- block, inline-block, float, flex/grid item, and positioned behavior from computed CSS;
- baseline fallback at the replaced element's bottom margin edge as required by the supported
inline formatting model;
- `alt` fallback sizing, painting, and accessibility/hit-box behavior;
- async intrinsic-size invalidation that dirties the correct ancestors exactly once.
- Ensure CSS `display` changes exchange layouters correctly and do not retain stale geometry.
- Keep the public `UIHTMLImage` API source-compatible where reasonable (`getDrawable`, `setAlt`,
`getAlt`, source properties), but do not preserve inheritance-based `UIImage*` conversion.
### Stage 5 - Migrate Callers and Remove Compatibility Inference
- Update callers that assume `UIHTMLImage` is a `UIImage`.
- Replace casts and shared behavior with explicit `UIHTMLImage` or image-content APIs.
- Audit type queries, inspector property reporting, serialization, widget creation, and tests.
- Remove `UI_HTML_ELEMENT` branches in `UIImage` that only exist to emulate HTML pixel/intrinsic
behavior.
- Remove image-specific checks and `SizePolicy` heuristics from RichText and layouters.
- Validate that `UISvg` remains a native image widget unless/until inline `<svg>` receives its own
explicit HTML/SVG replaced-element wrapper; do not accidentally fold that larger migration into
this work.
### Stage 6 - Conformance and Performance Validation
- Run focused HTML layout suites after each stage, then the full unit-test suite.
- Exercise synchronous and asynchronous image loading, repeated navigation, viewport resize,
device-pixel-ratio changes, and deferred stylesheets.
- Add a stress test that repeatedly loads/destroys image-heavy WebViews under ASan.
- Verify no layout oscillation: count dirty-layout iterations and assert convergence for the Asahi
fixture.
- Compare release-build layout/rebuild counters before and after the refactor.
- Audit every introduced allocation, string copy, shared ownership handoff, callback capture, and
per-frame branch. Image loading may allocate; steady-state layout and drawing must not add new
heap work.
## Compatibility and Migration Risks
- `UIHTMLImage*` will no longer convert to `UIImage*`. Search the complete repository and document
any external API compatibility impact before landing the inheritance change.
- Native `UIImage` alignment semantics are not CSS `object-position` or inline formatting
semantics. Keep those concepts separate during extraction.
- Replaced sizing must distinguish CSS pixels from physical raster pixels, especially for SVG and
HiDPI rendering.
- Async drawable completion must not apply geometry from an obsolete navigation or destroyed
document scene.
- `alt` text is not merely native image fallback drawing; its intrinsic sizing and line
participation need an explicit supported behavior and tests.
- Absolute-position auto margins require inset-aware equation solving. Treating all out-of-flow
auto margins as zero would be another compatibility shortcut.
- Tables, flex items, and grid items have formatting-model-specific used-size and auto-margin rules;
do not force them through the normal block equation.
## Exit Criteria
This follow-up is complete when:
- `UIHTMLImage` derives from `UIHTMLWidget`, not `UIImage`;
- native and HTML images share image mechanics without duplicated resource/drawing code;
- HTML used margins are resolved from explicit formatting roles without mutating stored margins;
- inline, block, float, positioned, flex, and grid auto-margin tests match supported CSS behavior;
- the Asahi async fixture converges with a 130px logo/anchor and bounded document overflow;
- deferred style/image completion and viewport resizing cannot feed stale margins or positions back
into intrinsic sizing;
- no `UI_HTML_ELEMENT` or `SizePolicy` heuristic remains as the source of an image's CSS display
role;
- focused and full test suites pass under the required wrapper, and the allocation/performance
audit finds no new steady-state heap work.