dymokomi/luce-browser-engine
Source of release 0.6.1
0.6.1 / tools / scroll_bench / module.lucb
#==============================================================================================
#
# scroll_bench - how fast a page scrolls and how much memory it takes, without a window
#
# DESCRIPTION:
# A measurement tool, not a test (docs: luce-browser-render docs/GPU.md):
#
# scroll_bench PAGE ... [--frames N] [--step PX] [--width W] [--height H] [--scale DPR]
# [--player cpu|gpu|both] [--png PREFIX] [--resources DIR]
#
# For each PAGE (a URL or a file path) it loads the page the way luced-browser does
# (webview_api, scripting disabled), waits for its first frame, then scrolls it by PX CSS
# pixels a frame (down, and back up at the end) for N frames. A frame is the wheel event,
# the engine's work until it presents the frame, and the frame reaching the GPU:
#
# cpu the CPU player rasterizes the frame and the application copies it out
# (webview_copy_frame), as luced-browser does without the GPU player;
# gpu the GPU player draws it into an offscreen texture of the view's size and the
# tool waits for the GPU to finish (a one-texel read);
# both as gpu, and at the first and every 16th frame the CPU player's frame is
# compared with the GPU's (pixels further apart than 2 in a channel).
#
# It prints one line per page: the load time, the frame time's average and 95th
# percentile (the main thread's work: idle waits for the engine's rendering timer are
# not counted), the GPU player's GPU time per frame (average/95th percentile, from
# luce-gpu's submission times; see presenter.lucb), the scrolled distance, the GPU player's tile counts, and the process's
# peak resident memory so far. --png PREFIX writes the last frame of each player;
# --layers lists the GPU player's layers of each page.
#
# Run from the repository's root:
#
# luce-base build tools/scroll_bench -o build/scroll_bench --release
# build/scroll_bench tests/scroll_bench/*.html
#
# Copyright (c) 2026 the luce-browser authors.
# SPDX-License-Identifier: BSD-2-Clause
#
#==============================================================================================
import c
import io
import memory
import strings
import thread
import time
import platform
from luce_std import files
from luce_browser_foundation import ak, gc
from luce_png import png
from luce_raster.binary import Buffer
from luce_gpu import gpu
from luce_browser_render import gpu_player
import webview
import webview_api
# mark: The command line ========================================================================
## Which player draws the frames.
enum Player as u8:
cpu = 0
gpu = 1
both = 2
## What the command line asked for.
struct Options:
var pages: ak.Vector[str]
var frames: usize = 120
var step: f64 = 40.0
var width: f64 = 1280.0
var height: f64 = 800.0
var scale: f64 = 2.0
var player: Player = Player.cpu
var png_prefix: str?
var resources: str = "build/scroll_bench_res"
## Whether to list the GPU player's layers of each page (--layers).
var layers: bool = false
## Whether to print each page's memory census after its run (--census).
var census: bool = false
## Prints the usage text; answers the exit status of a command line not understood.
func usage() -> i32:
io.stderr().write("usage: scroll_bench PAGE ... [--frames N] [--step PX] [--width W] [--height H] [--scale DPR]\n") catch failure: return 2
io.stderr().write(" [--player cpu|gpu|both] [--png PREFIX] [--resources DIR] [--layers] [--census]\n") catch failure: return 2
return 2
## The options of `arguments` (the program name first), or none when they are not understood.
func parse_options(arguments: const str[]) -> Options?:
var options = Options()
var index: usize = 1
while index < arguments.length:
let argument = arguments[index]
index += 1
if not strings.starts_with(argument, "-"):
ak.vector_append_t(&options.pages, argument)
continue
if argument == "--layers":
options.layers = true
continue
if argument == "--census":
options.census = true
continue
if index >= arguments.length:
return none
let value = arguments[index]
index += 1
if argument == "--frames":
options.frames = (usize)(strings.parse_u64(value) else return none)
elif argument == "--step":
options.step = strings.parse_f64(value) catch failure: return none
elif argument == "--width":
options.width = strings.parse_f64(value) catch failure: return none
elif argument == "--height":
options.height = strings.parse_f64(value) catch failure: return none
elif argument == "--scale":
options.scale = strings.parse_f64(value) catch failure: return none
elif argument == "--player":
if value == "cpu":
options.player = Player.cpu
elif value == "gpu":
options.player = Player.gpu
elif value == "both":
options.player = Player.both
else:
return none
elif argument == "--png":
options.png_prefix = value
elif argument == "--resources":
options.resources = value
else:
return none
if ak.vector_is_empty(&options.pages):
return none
return options
# mark: Process memory ==========================================================================
extern func getrusage(who: i32, usage: void*) -> i32
## The process's peak resident memory in bytes (getrusage's ru_maxrss: bytes on macOS,
## kilobytes on Linux).
func peak_resident() -> u64:
# struct rusage: two timevals (32 bytes), then ru_maxrss.
var record: i64[18]
if getrusage(0, (void*)&record[0]) != 0:
return 0
let value = (u64)record[4]
return value if platform.macos else value * 1024
# mark: Text ====================================================================================
## `text` as an owned string (at most 512 bytes).
func owned(text: fmt) -> str:
var buffer: u8[512] = ---
let written = strings.format(buffer, text) catch failure: return "?"
return strings.copy(written) catch failure: trap("out of memory")
## `value` in decimal.
func decimal(value: u64) -> str:
var buffer: u8[24] = ---
let text = strings.format_u64(value, buffer) catch failure: return "?"
return strings.copy(text) catch failure: trap("out of memory")
## `nanoseconds` as milliseconds with two decimals.
func milliseconds(nanoseconds: u64) -> str:
let hundredths = (nanoseconds + 5000) // 10000
let fraction = hundredths % 100
let pad = "0" if fraction < 10 else ""
return owned(f"{decimal(hundredths // 100)}.{pad}{decimal(fraction)}")
## `bytes` in MiB with one decimal.
func mebibytes(bytes: u64) -> str:
let tenths = (bytes * 10 + 524288) // 1048576
return owned(f"{decimal(tenths // 10)}.{decimal(tenths % 10)}")
# mark: main ====================================================================================
pub func main(arguments: str[]) -> i32:
let options = parse_options(arguments) else return usage()
webview_api.initialize(options.resources) catch failure:
print(f"scroll_bench: the engine did not initialize: {failure.message}")
return 1
print(f"scroll_bench: engine initialized, peak resident {mebibytes(peak_resident())} MiB")
print("page load ms frame avg ms frame p95 ms GPU avg/p95 ms scrolled px tiles r/c peak MiB check")
for page in ak.vector_span_const(&options.pages):
bench_page(page, &options)
return 0