Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -650,6 +650,9 @@ if(EUI_BUILD_TEST_FIXTURES)
target_compile_definitions(${probe_name} PRIVATE EUI_TEST_SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}")
add_test(NAME ${probe_name} COMMAND ${probe_name} --frames 3)
set_tests_properties(${probe_name} PROPERTIES LABELS "probe")
if(probe_name STREQUAL "markdown_viewport_probe")
set_tests_properties(${probe_name} PROPERTIES SKIP_RETURN_CODE 77)
endif()
if(probe_name STREQUAL "gpu_image_probe")
set_tests_properties(${probe_name} PROPERTIES FAIL_REGULAR_EXPRESSION "Validation Error;VUID-")
endif()
Expand Down
248 changes: 217 additions & 31 deletions components/markdown.h

Large diffs are not rendered by default.

8 changes: 8 additions & 0 deletions core/render/text.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -295,6 +295,11 @@ std::string firstExistingPath(std::initializer_list<const char*> paths) {
return {};
}

std::uint64_t& defaultFontConfigurationRevision() {
static std::uint64_t value = 0;
return value;
}

std::string& defaultUiFontFileOverride() {
static std::string value;
return value;
Expand Down Expand Up @@ -1450,6 +1455,7 @@ void TextPrimitive::Impl::setDefaultFontFiles(const std::string& textFontFile, c
defaultIconFontFileOverride() == iconFontFile) {
return;
}
++defaultFontConfigurationRevision();
defaultUiFontFileOverride() = textFontFile;
defaultIconFontFileOverride() = iconFontFile;
clearSharedFontStackCache();
Expand Down Expand Up @@ -2013,6 +2019,8 @@ TextPrimitive::TextMetrics TextPrimitive::measureTextMetrics(const std::string&
Vec2 TextPrimitive::measureTextSize(const TextStyle& style) {
return Impl::measureTextSize(style);
}
std::uint64_t TextPrimitive::fontConfigurationRevision() { return core::defaultFontConfigurationRevision(); }

void TextPrimitive::setDefaultFontFiles(const std::string& textFontFile, const std::string& iconFontFile) {
Impl::setDefaultFontFiles(textFontFile, iconFontFile);
}
Expand Down
2 changes: 2 additions & 0 deletions core/render/text.h
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,8 @@ class TextPrimitive {
float fontSize = 16.0f,
int fontWeight = 400);
static Vec2 measureTextSize(const TextStyle& style);
// Changes when the default font configuration changes; metric caches may key on it.
static std::uint64_t fontConfigurationRevision();
static void setDefaultFontFiles(const std::string& textFontFile, const std::string& iconFontFile);

void prepare();
Expand Down
1 change: 1 addition & 0 deletions docs/benchmarks/markdown-viewport-20261023.json

Large diffs are not rendered by default.

68 changes: 68 additions & 0 deletions docs/benchmarks/markdown-viewport-20261023.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Markdown viewport paired measurement (2026-10-23)

Ubuntu 24.04, Linux 7.0.0-38-generic, Intel Core Ultra 5 225H (14 CPUs),
30 GiB RAM, GCC 13.3.0, CMake 3.28.3, Ninja, GLFW/OpenGL Release
(`-O3 -DNDEBUG`, EUI's target `-Os -fno-exceptions -fno-rtti`). The CPU-only
component benchmark creates no window/GPU; actual viewer and pixel checks used
Xvfb/Mesa llvmpipe. Host desktop processes remained active; no frequency pinning.

The baseline is upstream dev **22f0ca35d19c06e989d64998ce18a27101ffd55c**'s
`markdown.h`; both benchmark executables link the identical current core library.
The core changes only add font-configuration invalidation and do not change
measurement metrics. This isolates the Markdown header algorithm. It is not a
comparison against another OS, renderer, font, or Release configuration.

Input: repeat `中文 English 😀 e\xCC\x81 ` until at least 18,000 UTF-8 bytes,
width 420, default MarkdownStyle, position (11,7), margin (3,5,7,9). Viewport:
top 500, height 180, overscan 32. Each process: five warmups, 60 timed builds,
layout, node counting and teardown. The geometry oracle's map-copying is excluded.
Steady uses the same paragraph; append adds the changing decimal sample index.
Three paired AB/BA/AB rounds per font/workload; table values are the median of
three per-run p50/p95 values, not a pooled percentile. RSS is per-process maximum
from `/usr/bin/time`, including startup, warmups and font loading.

| Font/workload | Baseline p50/p95 ms | Viewport p50/p95 ms | Nodes old/new | RSS old/new KiB |
| --- | --- | --- | --- | --- |
| Bundled TTF, steady | 88.246 / 90.208 | 0.693 / 0.842 | 9003 / 400 | 112060 / 14980 |
| Bundled TTF, append | 88.625 / 91.130 | 22.240 / 22.680 | 9005 / 400 | 112352 / 21600 |
| Noto Sans SC CFF, steady | 95.153 / 96.614 | 0.739 / 0.793 | 9003 / 432 | 111524 / 14668 |
| Noto Sans SC CFF, append | 94.791 / 96.608 | 25.253 / 25.700 | 9005 / 432 | 111788 / 20840 |

[Raw chronological samples and font/binary SHA256](markdown-viewport-20261023.json).
The TTF is the existing bundled JingNanJunJunTi asset; CFF is Noto Sans SC 2.004
regular OTF, SHA256 `faa6c9df652116dde789d351359f3d7e5d2285a2b2a1f04a2d7244df706d5ea9`.
No font/resource is added. Reproduce from a Release Ninja fixture build configured
with `CMAKE_EXPORT_COMPILE_COMMANDS=ON` (build `markdown_viewport` first):

```sh
python3 docs/benchmarks/markdown-viewport-pair.py --build /absolute/build/glfw-opengl \
--font assets/JingNanJunJunTi-JinNanJunJunTi-Bold-2.ttf > paired-ttf.json
python3 docs/benchmarks/markdown-viewport-pair.py --build /absolute/build/glfw-opengl \
--font /absolute/path/NotoSansSC-Regular.otf > paired-cff.json
```

The script uses that build's exact compiler/link argv, compiles baseline/current
headers against one core, then alternates processes without overlapping builds.
It only uses the Python standard library, Ninja and `/usr/bin/time`; these are
measurement tools, not new product dependencies. Appending still reparses and
lays out the changed paragraph: these results do not establish 60 FPS or GPU frame
time, and do not cover arbitrary documents, hardware GPUs, Windows or compositor input.

Independent local Release builds with fixtures enabled, apps/user apps/tray disabled:

| Backend | Full CTest | Installed SDK consumer | Viewer |
| --- | --- | --- | --- |
| GLFW/OpenGL | 38 passed | 1 passed | mapped, wheel-scrolled, closed |
| SDL2/OpenGL | 38 passed | 1 passed | mapped, wheel-scrolled, closed |
| GLFW/Vulkan | 37 passed, 1 explicit skip | 1 passed | mapped, wheel-scrolled, closed |
| SDL2/Vulkan | 37 passed, 1 explicit skip | 1 passed | mapped, wheel-scrolled, closed |

OpenGL pixel probes compare exact RGBA bytes for twelve light/dark × 1/1.5 DPI ×
scroll combinations. The OpenGL readback probe returns skip 77 on Vulkan;
geometry/ID tests and viewer interaction still run there. No Vulkan pixel-equality
claim. SDL was rerun with `WAYLAND_DISPLAY` unset and `SDL_VIDEODRIVER=x11` so the
final checks used a private X server. All four final viewport unit reruns passed.
The unit was also independently compiled with ASAN (leak detection enabled) and
UBSAN, both passed without a report; these two instrument the changed header,
while linking the same uninstrumented Release core. Full sanitizer library coverage
is left to the consuming application's instrumented build.
46 changes: 46 additions & 0 deletions docs/benchmarks/markdown-viewport-pair.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
#!/usr/bin/env python3
"""Build paired header benchmarks against one Release core; Ninja/compile_commands required."""
import argparse, json, os, shlex, statistics, subprocess, tempfile
from pathlib import Path
p = argparse.ArgumentParser()
p.add_argument('--build', type=Path, required=True)
p.add_argument('--font', type=Path, required=True)
p.add_argument('--rounds', type=int, default=3)
a = p.parse_args()
root = Path(__file__).resolve().parents[2]
build = a.build.resolve()
font = a.font.resolve()
unit = root / 'tests/unit/markdown_viewport.cpp'
helper = unit.read_text().split('int main(', 1)[0]
main = 'int main() {\n const auto* font=std::getenv("EUI_TEXT_TEST_FONT");\n core::TextPrimitive::setDefaultFontFiles(font ? font : "/tmp/mirage-eui-markdown-20261023/assets/JingNanJunJunTi-JinNanJunJunTi-Bold-2.ttf",{});\n const std::string mode=std::getenv("EUI_VIEWPORT_MODE") ? std::getenv("EUI_VIEWPORT_MODE") : "viewport";\n components::MarkdownStyle style;\n std::string paragraph;\n while(paragraph.size()<18000) paragraph += "中文 English 😀 e\\xcc\\x81 ";\n std::vector<double> values;\n for(int i=0;i<65;++i){\n const auto source=mode=="append" ? paragraph+std::to_string(i) : paragraph;\n const auto start=std::chrono::steady_clock::now();\n const auto result=build(source,420,style,mode!="full",500,180,false);\n if(i>=5)values.push_back(std::chrono::duration<double,std::milli>(std::chrono::steady_clock::now()-start).count());\n if(i==64)std::cout<<"{\\"mode\\":\\""<<mode<<"\\",\\"nodes\\":"<<result.nodes<<",";\n }\n const auto raw=values;std::sort(values.begin(),values.end());\n std::cout<<"\\"p50_ms\\":"<<values[30]<<",\\"p95_ms\\":"<<values[57]<<",\\"samples_ms\\":[";\n for(std::size_t i=0;i<raw.size();++i){if(i)std::cout<<",";std::cout<<raw[i];}\n std::cout<<"]}\\n";\n}\n'
entry = next(x for x in json.loads((build / 'compile_commands.json').read_text()) if Path(x['file']) == unit)
compile_args = shlex.split(entry['command'])
link = subprocess.check_output(['ninja', '-C', str(build), '-t', 'commands', 'markdown_viewport'], text=True).splitlines()[-1]
link_args = shlex.split(link.split('&&')[1])
runs = []
with tempfile.TemporaryDirectory(prefix='eui-viewport-pair-') as scratch:
temp = Path(scratch)
old = subprocess.check_output(['git', '-C', str(root), 'show', '22f0ca35d19c06e989d64998ce18a27101ffd55c:components/markdown.h'], text=True)
(temp / 'baseline.h').write_text(old)
for version in ['baseline', 'current']:
source = helper + main
if version == 'baseline':
source = source.replace('"components/markdown.h"', json.dumps(str(temp / 'baseline.h'))).replace('if (sliced) md.viewport(top, height);', '(void)sliced;')
cpp, obj, exe = [temp / (version + suffix) for suffix in ['.cpp', '.o', '']]
cpp.write_text(source)
command = compile_args[:]
command[command.index('-o') + 1] = str(obj)
command[command.index('-c') + 1] = str(cpp)
subprocess.run(command, cwd=entry['directory'], check=True)
command = [str(obj) if x.endswith('markdown_viewport.cpp.o') else x for x in link_args]
command[command.index('-o') + 1] = str(exe)
subprocess.run(command, cwd=build, check=True)
for workload in ['steady', 'append']:
for iteration in range(a.rounds):
for version in (['baseline', 'current'] if iteration % 2 == 0 else ['current', 'baseline']):
mode = 'append' if workload == 'append' else 'full' if version == 'baseline' else 'viewport'
env = dict(os.environ, EUI_TEXT_TEST_FONT=str(font), EUI_VIEWPORT_MODE=mode)
rss = temp / 'rss'
result = subprocess.check_output(['/usr/bin/time', '-f', '%M', '-o', str(rss), str(temp / version)], env=env, text=True)
runs.append(dict(workload=workload, iteration=iteration, version=version, rss_kib=int(rss.read_text()), **json.loads(result)))
print(json.dumps(dict(font=str(font), runs=runs), indent=2))
71 changes: 71 additions & 0 deletions docs/markdown-viewport.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Markdown viewport construction

`MarkdownBuilder::viewport(top, height, overscan = 32)` is an opt-in construction
limit for scrolling read-only documents. Coordinates are logical units relative
to the document content origin, after its outer margin; they are not window or
framebuffer coordinates. The caller still clips its scroll viewport.

```cpp
auto doc = components::markdown(ui, "document")
.width(contentWidth)
.markdown(source)
.theme(tokens);
doc.viewport(documentScrollOffset, viewportHeight).build();
```

Omit `viewport()` for the original complete tree. A zero/negative height builds
an empty tree with the full document bounds. Negative top values are valid;
non-finite arguments fall back to complete construction. Overscan is clamped to
zero or greater. The default includes adjacent lines for glyph overhang; increase
it when custom fonts or effects extend beyond their logical line boxes.

The component preserves full height and the original block/table/segment IDs.
Only nearby blocks, table rows and inline lines become DSL controls, including
when one paragraph contains thousands of segments. Added placement containers
are implementation details. Fixed component height and outer margins retain
their existing meaning. Rendering colors come from the current style, so color
transitions do not invalidate geometry.

For `ScrollView`, keep its height measurement in complete mode and use the actual
scroll root's offset for the real tree (see `tests/fixtures/markdown_viewer.cpp`).
Request recomposition when scrolling changes the offset; moving a previously
culled tree alone cannot reveal new content. Width, font configuration, source
replacement and metric style changes rebuild the layout automatically. Source
comparison is exact, not a hash used as an identity.

A shared UI-thread-local LRU holds at most eight viewport plans with an 8 MiB
accounted budget and a 4 MiB maximum entry. It retains parsed documents, inline
geometry and table row offsets; accounting includes source keys and retained
storage. Oversized plans remain usable for that build but are not retained.
Existing parser/inline caches keep their own bounds. No worker, timer, dependency,
font resource or scheduling facility is added. `TextPrimitive::fontConfigurationRevision()`
allows metric caches to notice a change to `setDefaultFontFiles()`; setting the
same paths is a no-op. Render segment metadata no longer duplicates source
strings for every glyph, avoiding quadratic storage for a single long run.

A viewport tree intentionally omits offscreen text controls. Consumers that derive
selection/copy information by walking controls must request a complete build on
selection start, or keep their own source-based selection mapping. Do not treat
the culled tree as the complete document. This option does not add text selection,
link activation, or an asynchronous parser.

## Validation and reproduction

`markdown_viewport` compares full versus viewport leaf text, stable IDs and frames
at fractional offsets, two widths, font sizes and themes, with CJK/Latin/emoji,
headings, quotes, lists, code, tables, a long single paragraph and a long table.
It checks edits, replacement, font configuration and cache churn. The optional
`--benchmark` reports build/layout/teardown time and node count for the same
18 KiB paragraph, five warmups and 60 samples. It excludes the geometry oracle's
map-copying work and does not report GPU frame time.

`markdown_viewport_probe` compares actual RGBA framebuffer bytes in OpenGL for
twelve theme/DPI/scroll combinations. It returns 77 on Vulkan, where the portable
geometry test and the Markdown viewer still run; the readback probe does not
claim Vulkan pixel equivalence. Run each backend's CTest suite and launch the
viewer in a real window or an isolated X server. Installed SDK consumers must
also compile the new public API.

Exact environment, paired results, four-backend checks and known limits are
recorded in [the paired measurement](benchmarks/markdown-viewport-20261023.md). Software rendering and component construction
measurements do not guarantee 60 FPS for arbitrary fonts, documents or devices.
10 changes: 9 additions & 1 deletion tests/consumers/find-package/public_header_companion.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,13 @@

bool publicHeaderCompanionIsLinked() {
const eui::Color color{0.0f, 1.0f, 0.0f, 1.0f};
return color.g > 0.5f;
eui::Ui ui;
ui.begin("installed-viewport");
components::markdown(ui, "document").width(200).markdown("Installed **viewport**")
.viewport(0, 80).build();
ui.end();
ui.layout(200, 100);
const auto revision = core::TextPrimitive::fontConfigurationRevision();
return color.g > 0.5f && ui.find("document") && ui.find("document")->frame.height > 0 &&
revision == core::TextPrimitive::fontConfigurationRevision();
}
9 changes: 6 additions & 3 deletions tests/fixtures/markdown_viewer.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -173,15 +173,18 @@ void compose(eui::Ui& ui, const eui::Screen& screen) {
.scrollbarGap(20.0f)
.onChange([&viewer](float value) {
viewer.scrollOffset = value;
app::requestUpdate();
})
.content([&](eui::Ui& contentUi, float contentWidth, float) {
components::markdown(contentUi, "markdown")
auto markdown = components::markdown(contentUi, "markdown")
.theme(tokens)
.width(contentWidth)
.wrapContentHeight()
.markdown(markdownSample())
.zIndex(1)
.build();
.zIndex(1);
if (const auto* viewport = contentUi.find("markdown.scroll"))
markdown.viewport(viewport->scrollOffset, viewportHeight);
markdown.build();
})
.build();
})
Expand Down
74 changes: 74 additions & 0 deletions tests/probes/markdown_viewport_probe.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
#include "components/markdown.h"
#include "core/dsl_runtime.h"
#include "core/render/render_backend.h"
#include "core/window/window_backend.h"
#if defined(EUI_RENDER_BACKEND_OPENGL)
#include <glad/glad.h>
#if defined(EUI_WINDOW_BACKEND_SDL2)
#define SDL_MAIN_HANDLED
#include <SDL.h>
#else
#define GLFW_INCLUDE_NONE
#include <GLFW/glfw3.h>
#endif
#include <iostream>
#include <vector>
int main() {
#if defined(EUI_WINDOW_BACKEND_SDL2)
SDL_SetMainReady();
if (SDL_Init(SDL_INIT_VIDEO) != 0) return 1;
#else
if (!glfwInit()) return 1;
#endif
core::window::WindowCreateRequest request;
request.width = 480; request.height = 300; request.title = "Markdown viewport pixel oracle";
auto window = core::window::createWindow(request);
core::render::initializeRenderBackendLoader();
auto backend = core::render::createRenderBackend(window);
if (!window || !backend || !backend->initialize()) return 1;
backend->makeCurrent();
core::render::ScopedRenderBackend scope(*backend);
core::TextPrimitive::setDefaultFontFiles(std::string(EUI_TEST_SOURCE_DIR) + "/assets/JingNanJunJunTi-JinNanJunJunTi-Bold-2.ttf", {});
core::dsl::Runtime runtime;
if (!runtime.initialize(window)) return 1;
std::string source;
for (int i = 0; i < 12; ++i)
source += "# Heading 中文\n\nLong **bold** paragraph, 中文 `inline` [link](https://example.com) ~~delete~~.\n\n"
"> Quoted text wraps across the viewport.\n\n- item with 中文 and English\n\n"
"| Left | Right |\n| :- | -: |\n| a long value wraps into rows | 中文字符 |\n\n"
"```cpp\nint x = 123;\n```\n\n---\n\n";
int failures = 0;
for (bool dark : {false, true}) for (float dpi : {1.0f, 1.5f}) for (float top : {0.0f, 113.5f, 430.0f}) {
std::vector<unsigned char> original;
for (bool sliced : {false, true}) {
runtime.compose("pixels", 480 / dpi, 300 / dpi, [&](auto& ui, const auto&) {
ui.stack("clip").position(8, 8).size(480 / dpi - 16, 300 / dpi - 16).clip().content([&] {
auto md = components::markdown(ui, "md").position(0, -top).width(480 / dpi - 16)
.markdown(source).theme(dark ? components::theme::dark() : components::theme::light());
if (sliced) md.viewport(top, 300 / dpi - 16);
md.build();
}).build();
});
runtime.update(window, 0, dpi, 1);
runtime.requestFullPaint();
runtime.render(480, 300, dpi, dark ? core::Color{0, 0, 0, 1} : core::Color{1, 1, 1, 1});
glFinish();
std::vector<unsigned char> pixels(480 * 300 * 4);
glPixelStorei(GL_PACK_ALIGNMENT, 1);
glReadPixels(0, 0, 480, 300, GL_RGBA, GL_UNSIGNED_BYTE, pixels.data());
if (!sliced) original = std::move(pixels);
else if (pixels != original) { std::cerr << "viewport pixels changed at " << top << " dpi " << dpi << '\n'; ++failures; }
}
}
runtime.shutdown(); backend.reset(); core::window::destroyWindow(window);
#if defined(EUI_WINDOW_BACKEND_SDL2)
SDL_Quit();
#else
glfwTerminate();
#endif
return failures ? 1 : 0;
}
#else
// GPU readback oracle is OpenGL-specific; geometry/ID coverage runs on all backends.
int main() { return 77; }
#endif
Loading
Loading