Skip to content

TrailView on the iPhone: the terrain draws broken, the new roads do not start, and the first picture takes long #3656

Open
3 of 4 issues completed

Description

@timohueser

Status: approved

Part of #2747. Related: #2863 (the quality controller), #3096 (the road rebuild), #3651 (structures as ready-made parts), #3765 (the app spike), #3685 (the shader shrink of the new roads).

TL;DR

Goal: In the iOS app on the iPhone 13, TrailView shows the view about the eye within 4 s of a cold open, holds a steady 30 frames per second with a GPU median of at most 20 ms per frame (60 % of a frame), and never uses more than 896 MiB during a load or a session (GPU memory included). Its look has the owner's approval. It is the same engine as on the desktop, with a phone tier of values.

Problem: iOS stops a web page at about 1,408 MiB on the iPhone 13 (#3765). The lighter preset P of the lever measurement still uses 1,120 to 1,216 MiB after one walk load. The page and the engine with no data take about 256 MiB. The largest part of the rest, about 512 MiB, is the data that the workers keep after the load. Each CPU cache has a fixed byte cap, and the caps add up to more than one load fills, so a long session can grow past that: 10 minutes of driving added 96 MiB. With P, the GPU takes 21 to 22 ms per frame (median). A redraw of the far shadow map takes about 12 ms and makes the longest frames. After about 3 minutes of loads the phone is warm ("fair").

Decision:

  • One budget table in the engine. Each GPU pool, each CPU cache, each worker count and each count of loads in flight has one row with a desktop value and a phone value. Each module reads its size from the table, not from a constant of its own. A worker gets its values in its first message.
  • The tier is chosen once, at the start, as the render scale is. The iOS app opens TrailView with tier=phone in the address, on every iOS device, an iPad too. Every other host gets the desktop tier.
  • The budget is a sum. A unit test adds the phone's byte caps of the CPU caches, and fails above the sum that the Plan assumes. On the phone, a run proves the peak: each scene loads after the page takes 512 MiB of other memory first (1,408 − 512 = 896), and a 10-minute drive ends with at least 512 MiB of headroom.
  • Place before cutting. Phone runs that end one kind of worker at a time placed the memory before the Plan. The caches of the workers hold the most, so the Plan cuts them first.
  • The phone values: 30 fps, a coarser far terrain, smaller pools and caches, fewer workers, half the loads in flight. The render scale stays at the desktop's 0.7, and both shadow maps stay. Each value has its measured or expected saving in the Plan.
  • The look: each cut that the eye can see gets a before/after gallery, rendered on the M1 Pro at the phone's size. The owner approves the gallery before the cut merges.
  • The ground plan: it becomes the only path with TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110, so the table has its rows (records, masks, plan workers, mesh range). Until it compiles on the phone (TrailView parts P8: the old tunnel code of the new roads goes #3685), the phone runs measure today's path, and the plan's rows come from the M1 Pro at the phone's size.

Rejected:

  • A native renderer, or a second viewer for the phone (the owner, 2026-11-21). The memory is the loaded data, and a native renderer holds the same data.
  • A memory controller that changes the pools at run time. WebGPU reports no free memory, and iOS stops a page with no warning. Values chosen at the start can be tested; TrailView: fit the device: dynamic resolution for 60 fps, and memory tiers #2786 also chose its memory tiers once.
  • Dropping the far shadow map on the phone. Without it, a view more than 100 m above the ground has no object shadows (the gallery of 2026-11-21). The owner keeps it: a redraw of about 12 ms after 400 m of movement is an acceptable cost.
  • The tier from device signals (adapter limits, navigator.deviceMemory). WebKit has no deviceMemory, and the app knows that it is the app.
  • A dynamic render scale to hold the frame time on the phone. On the iPhone 13 the scales 0.5 and 0.7 give the same GPU time.
  • Cuts of the tree ranges, the small objects, the street lamps and the finest terrain level. On the phone each changed the GPU time and the memory by less than the noise, so they keep their desktop values.

Systems: trailview, trailview-page
Contracts: none
Size: L (set by explore; an epic of several pull requests)

Facts

On the phone (app host, iPhone 13, preset P, walk; comments of 2026-11-21):

  • After a walk load, P's footprint is 1,120 to 1,216 MiB (two sessions). The parts: the page and the engine with no data and no workers, about 256 MiB; the 11 workers with no data, about 64; the data of the workers, about 448; the pools, the JavaScript of the main page and the rest, about 352 (ending the engine gave back 128 of it within 10 s). The kinds of worker, ended one kind at a time, gave back 416 MiB in all; all workers at once gave back 512. One minute with the view still gives nothing back.
  • The peak of a load is above about 1,008 MiB: with 400 MiB taken first, iOS stopped the load.
  • GPU time, the median of each pass when it runs: main pass 13.4 ms, vegetation 5.9, near shadow casters 5.5, resolve 2.4, ground look 1.8, far shadow casters 11.8. The GPU median per frame is 21 to 22 ms. The render scales 0.5 and 0.7 give the same time.
  • Load, cold: eye ready 2.1 to 2.8 s (once 6.3 s), near ready 3.3 to 4.4 s, complete 11.7 to 17.7 s.
  • Levers against P: far shadows on add the longest frames (158 against 75 ms) and about 96 MiB. The terrain range × 0.8 saves 4.5 ms of GPU time and about 96 MiB, and the frames over 33 ms go from 64 % to 27 %. The tree ranges, the small objects, finest=17 and the loads in flight change the time and the memory by less than the noise.

On the M1 Pro (headless Chromium on Metal, the phone's canvas of 780 × 1688):

  • P's JavaScript after the flight is about 420 MiB: main page 104 + canvas 15, ground workers 2 × 80–85, stamp 64, road 49, houses 13, tree models 3 × 3, plants 1, terrain decode 2 × 1.
  • P's pools are 409 MiB, the same count as on the phone. With ground=plan they are 462 MiB: feature masks 82, records 32, plan pieces 20, and no road pool. The two plan workers hold 37 MiB each.
  • The ground look of P holds 64 pages; the walk wants 102. At the default of 192 pages it holds 138.

In the code (develop bddbbcf, paths under builder/web/src/lib/trailview/):

  • Worker caps: ground decode 96 MiB per worker, 2 workers (stream/ground-worker.ts:18); stamp 48 MiB (terrain/stamp-worker.ts:19); house 32 MiB, the default of tileBudget, which structures/house-worker.ts does not call; road 55 MiB and 9 decoded ground tiles of 1 MiB (roads/road-worker.ts:8, roads/ground.ts:23); plan 55 MiB per worker (HEAP_LIMIT of plan/plan.ts:27, checked in plan.ts and terrain/model.ts), 2 workers (WORKERS of terrain/model.ts, which src/trailview.ts gives to preload); tree models 3 workers (WORKERS of vegetation/tree-models.ts).
  • The caps are not hard limits. A worker's tile cache keeps the tiles that a view wants, and the newest one, past its cap (trim in stream/features.ts); on the phone the stamp worker gave back about 160 MiB against its cap of 48. A plan worker restarts above its heap limit only when no job waits (terrain/model.ts:259).
  • Main-page caps: stamped nodes 64 MiB (terrain/stamps.ts:12), road meshes 32 MiB (roads/roads.ts:30), plan records 32 MiB (plan/plan.ts:25), encoded terrain bodies 64 MiB (terrain/pages.ts:15): a page that comes back into the pool decodes its kept body again, the plan's records and cells read their tiles from it (pages.body), and a new device after a lost one gets its pages again without a request, feature bodies 32 MiB (stream/terrain.ts:13), ground bodies 16 MiB per archive, six archives: the ground, the four colour quarters and the snow (stream/ground.ts:24).
  • Pools: terrain pages 104 + 67 MiB, scaled by pool= (terrain/terrain.ts:34); feature masks of 128 pages, 32 MiB per texture, four textures with ground=plan (terrain/terrain.ts:41); ground look 192 pages (ground/ground.ts:14); records 32 MiB (RECORDS_MB of terrain/model.ts); shadow maps, 2 cascades of 2048 × 2048 (light/shadow.ts).
  • The near shadow map fades out between 50 and 100 m above the ground, the far map up to 1,638 m (above of CASCADES in light/shadow.ts). Above 100 m only the far map gives object shadows.
  • A shadow map draws again when the eye moves 50 m (near) or 400 m (far), when the sun turns, or when new casters arrive (Shadow.due in light/shadow.ts). A still view draws none.
  • The phone renders 1,182 rows: the canvas is 1,688 pixels high (the engine caps the pixel ratio at 2) and the render scale is 0.7. There bestRange gives 4.0 node sizes, below the least, so the terrain range is the least, 4.6 (RANGE in terrain/lod.ts:21, bestRange in terrain/terrain.ts:1085). Below it, neighbouring nodes can fail to meet.
  • The lever run's terrain range × 0.8 multiplied after that least: 3.7 node sizes. A least of 3.7 alone gives 4.0 on the phone, the value of bestRange. lod.test.ts at 3.7 finds 41 grid vertices outside their node's level at walk height. With the morph band at 0.15 levels in place of 0.3, the test passes at 3.7 from all four of its eyes. The morph band is MORPH of lod.ts; drawn-height.wgsl, plan/cells.wgsl, plan/pieces.ts and roads/corridor.wgsl use it too. The choice of the drawn nodes does not read it (split of cdlod).
  • scale, pool and finest come from the address once and go to TrailView.start (view.ts, engine.ts:241). A worker cannot read the address.
  • TrailView ground plan GP19: the ground plan becomes the only path, the old code goes, docs, budgets, merge into develop #3110 deletes the road worker, the road meshes and the road pool, and makes the plan path the only path.

Plan

The budget

The budget is the footprint of the page on the iPhone 13: 1,408 MiB minus the headroom that the kit's probe finds, in steps of 32 MiB. The kit measures a part by the headroom that the probe gains when that part ends (after= of phone-measure.js on the prototype branch). The column "P" is preset P on today's path (sessions of 2026-11-21). The phone tier stays at or under 896 MiB after 10 minutes of driving and at the peak of a load.

Part P Phone How
The page and the engine with no data and no workers 256 256 no change
Ground decode workers (2) 160 40 decoded images kept: 96 → 16 MiB per worker
Stamp worker 160 80 feature tiles kept: 48 → 24 MiB
Road worker 64 0 #3110 deletes it
Plan worker none (2 × 37 on the M1 Pro) 40 one worker; its heap limit 55 → 40 MiB
Terrain decode (2), house, tree model (3) and plant workers 32 16 the tree model workers end after 10 s with no job; house tiles kept: 32 → 16 MiB
Workers, not placed by kind 96 96 all workers at once gave back 512, the kinds one at a time 416; no cut assumed
Pools, the main page's data and the rest 352 about 314 the main page's caches about −100 (stamped nodes 64 → 24 MiB, plan records 32 → 16, encoded terrain bodies 64 → 16, feature bodies 32 → 8, ground bodies 6 × 16 → 6 × 2); coarser far terrain (T3): this budget counts −32, one run measured −96, within the noise; the far shadow map +11, which P did not have; the plan path's pools +53 (M1 Pro count)
After a walk load 1,120 to 1,216 about 842
Growth in 10 minutes of driving 96 not known; the smaller caps hold less valley drive, to and fro: 1,184 after the load, 1,280 after 10 minutes
After 10 minutes of driving 1,280 gate ≤ 896 the soak run (p-soak of the kit)
Peak of a load > 1,008 gate ≤ 896 each scene loads after 512 MiB of ballast

The worker rows are what the probe gains when that kind ends. On the phone the ground decode workers hold what Chromium reports. The stamp worker holds more, because for each tile that it keeps it also keeps the tile's shapes and their grid index, which its cap does not count (#3793). The pools allocate 409 MiB with P (462 with the plan path); iOS counts only the parts that a view has written, so a long session writes more of them.

The budget is at its limit: the phone column after 10 minutes is about 842 plus a growth that P had at 96. #3778 runs the soak at tier=phone as soon as it merges. If it is above 896 MiB, the next levers, in order:

  1. The stamp worker keeps less for each feature tile (TrailView phone tier: the stamp worker keeps less for each feature tile #3793): a smaller grid index, and coarse tiles keep only the lines that their nodes read. In a replay of the walk, its peak falls from 209 to 48 MiB.
  2. One ground decode worker on the phone: about −25 MiB, and the ground jobs of a load run one at a time.
  3. A placement session at tier=phone for the 96 MiB that no kind explains.

On the phone the new roads draw their ground mesh as on the desktop, with one plan worker in place of two. The device cache does not change: the app keeps what the workers make (the plan's cells, the stamped nodes, the house records, the tree models) in the page's Cache Storage, up to 296 MiB on the disk (CAPS of terrain/device-cache.ts). That is disk, not memory. The GPU time of the plan path on the phone is not known until #3685; the epic's last check measures it.

The cuts

Each cut against its desktop value. P has the cuts of T1 already, so they are in the column "Now" of the budget. P also had no far shadow map; the phone tier keeps it, which adds the map (about 11 MiB) and its redraws to the column "Phone".

Cut Frame Memory Load Look
Terrain pages × 0.5 (T1) – 32 MiB against the full pool (measured) – coarser far pages where the pool is short: gallery
Ground look 64 pages, from 192 (T1) – needed to load at all (measured) – coarser far ground; 38 of 102 pages short: gallery
Half the loads in flight (T1) – lower peak (expected) complete 17.7 against 24.7 s (measured, one session) none
30 fps (T1) the GPU idles between frames – – none
Worker and main-page caches (T2) – about 300 MiB (expected from the kind runs) tiles that leave a cache decode again when the eye comes back: expected under 1 s more to complete none
One plan worker (T2) – about 40 MiB (expected) the near mesh completes later: measured in T2 none
Tree model workers end when idle (T2, both tiers) – about 9 MiB (expected: 3 × 3 MiB on the M1 Pro) – none
Coarser far terrain: the least range 3.7 node sizes, from 4.6, and the morph band 0.15 levels, from 0.3 (T3) GPU −4.5 ms; frames over 33 ms 64 % → 27 % (measured with the range alone) 32 to 96 MiB (one run measured 96, within the noise) – coarser far terrain, and the near meshes of the new roads end at about 0.89 times the desktop's distance, where level 18 ends: gallery; the shorter morph shows only in motion: the owner watches a walk in one viewer window

The range alone does not work: below 4.6 node sizes, neighbouring terrain nodes do not meet (Facts). A narrower morph band lets them meet at 3.7. The choice of the drawn nodes does not read the morph band, so the measured GPU time holds.

The render scale (0.7), the tree ranges, the small objects, the street lamps and the finest level keep their desktop values: on the phone each changed the GPU time and the memory by less than the noise. The render targets are made for the largest scale in any case (MAX_SCALE of resolve/targets.ts). No object kind goes on the phone. The fixed values of the tier hold the frame rate, with no quality controller (#2863).

The galleries

Each sub-issue with a visible cut renders a gallery before its pull request merges: the desktop tier against the desktop tier with that one cut, and the desktop tier against the whole phone tier. The renders run on the M1 Pro (headless Chromium on Metal, shoot.mjs, a canvas of 780 × 1688), at the start of the four scenes of the kit (walk, valley drive, zoom-out, bridge and tunnel) and two far views, because the far views must stay the most similar. One local page shows each pair: with, without, and the difference, with a hover to flip. The owner approves in a comment on the sub-issue.

Sub-issues

Each sub-issue holds its plan steps.

Files

Paths under builder/web/src/lib/trailview/ unless they start with builder/.

#3777 (the phone tier):

  • budget.ts: create: the tiers and the values of each.
  • view.ts: change: tierOf in, poolOf out.
  • engine.ts: change: TrailView.start takes the tier and gives each part its values.
  • terrain/terrain.ts, ground/ground.ts, pacer.ts: change: the page bytes, the ground pages and the frame rate come from the budget.
  • terrain/pages.ts, ground/pages.ts, structures/houses.ts, terrain/stamps.ts, vegetation/canopy.ts: change: the loads in flight come from the budget.
  • builder/web/src/trailview.ts: change: reads the tier from the address.
  • README.md: change: tier in the table of address options.

#3778 (caches and workers):

  • stream/ground-worker.ts, stream/ground.ts, terrain/stamp-worker.ts, terrain/stamps.ts, structures/house-worker.ts, structures/houses.ts, plan/bridge.ts, terrain/model.ts: change: each worker gets its cap, heap limit or count from the budget.
  • plan/plan.ts, terrain/pages.ts, stream/terrain.ts: change: the main page's caches come from the budget.
  • vegetation/tree-models.ts: change: an idle worker ends.
  • budget.ts: change: PHONE_CAPS.
  • budget.test.ts: create: the phone's caps add up to at most PHONE_CAPS.

#3779 (far terrain):

  • terrain/lod.ts: change: cdlod takes the morph band; MORPH goes.
  • terrain/lod.test.ts: change: the selection test runs at the values of each tier.
  • terrain/terrain.ts: change: the least range and the morph band come from the budget; the morph band goes into the surface uniform; the comment of PROBE_ABOVE_M.
  • terrain/drawn-height.wgsl, plan/cells.wgsl, roads/corridor.wgsl: change: the morph band from the uniform.
  • plan/pieces.ts: change: the morph band from the rule.
  • budget.ts: change: the least range and the morph band of each tier.

Outside develop: the kit's variant p on the prototype branch becomes tier=phone. No guide page changes.

Done when

Each sub-issue, in builder/web:

The epic, after #3777, #3778, #3779, #3673, #3685 and #3110, in one phone session that the owner runs (about 35 minutes, iPhone 13, the app host of the prototype branch, tier=phone):

  • Each of the four scenes loads with 512 MiB of ballast.
  • The soak (10 minutes of the valley drive, to and fro) ends with at least 512 MiB of headroom.
  • On the walk, the GPU median is at most 20 ms, and the 95th percentile of the frame interval is at most 40 ms.
  • Eye ready within 4 s of a cold open, and within 8 s of the first open after an install.
  • The soak, run unplugged, ends at the thermal state "fair" or better.

Limits

The owner's words of 2026-11-18:

  • The phone gets the same TrailView, with almost all code shared. It is not a second viewer.
  • Settings can be lower on the phone: the render distance, the resolution.
  • Objects can go on the phone if they cost too much. His examples: street lamps, benches, signposts.
  • The look is similar to the desktop. The far views above all are very similar.
  • 30 frames per second on the phone is fine. More is better.
  • TrailView runs inside the iOS app, not in the browser of the phone.
  • The work is planned and done in order, not in a hurry.

From the earlier decisions: the target device is the iPhone 13. The two costs that count are the frame time and the time to the first complete picture.

Out of scope

  • The web planner on a phone browser. Phone browsers get "download the app".
  • Android.
  • Touch controls for walk and fly (the owner, 2026-11-21: an issue of their own).
  • The TrailView screen of the released iOS app. The measurements use the host of the prototype branch prototype/trailview-ios-app.

Requirements: none


Generated by Claude Code

Activity

  1. timohueser commented on Nov 18, 2026

    @timohueser
    OwnerAuthor

    Findings of the two fault-check runs on the iPhone 13 (2026-11-18)

    The fault check is a second page of the measuring kit (/phone/diagnose, branch claude/trailview-phone-measure). It sends the errors of each shader and pipeline, pictures of the canvas, and the heights at three stages. Sessions on the owner's PC: phone/results/20261118113457-d9e4 and 20261118195400-du5n; the same check on the PC is 20261118145602-d54s.

    Question Answer State
    Why is there no ground look and no forest? The ground worker tests the image decode of the browser at its start (probe() in stream/ground-worker.ts). WebKit multiplies the colour by the alpha when it decodes an image. The ground tiles hold data under a low alpha, so the test fails and the engine draws no ground. Proven: the worker's own error is in both sessions. A fix is on the branch claude/trailview-safari-faults (a WebP decode in WASM for browsers that fail the test). It is not built and not tested.
    Are the terrain heights correct? Yes. The stored pages are equal to those of the PC byte for byte. The pages that the GPU makes differ by 7.5 mm at most. In a 20 s walk flight the shape of the terrain is correct in each picture. Proven for a still view and for the walk flight.
    Where is the "spiky" terrain of the first run? Not found. It did not show in a still view or in the walk flight. The owner was asked if the flat green ground without its look is what he saw. Open
    Why does Safari refuse the shaders of the new roads? Hypothesis: the Metal compiler of the phone has not enough memory for the largest shaders. Each "out of memory" error came at the moment a compile failed (after 6 s for audit, after 41 s for stamp with the road model). No buffer and no texture failed. The same stamp module compiles without the road model (heights.wgsl). Not proven. A page that compiles the shaders in smaller sizes is in work.

    If the hypothesis is correct, the height rules of the new roads in the shader (terrain/heights.wgsl and what includes it) are too large for the phone as one program. The options are: smaller passes, a call of the heavy functions at one place only, or heights that the CPU or the bake makes for the phone. This is a question for the design of this issue, and it touches #3651, which removes the tunnel rules from these shaders.


    Generated by Claude Code

  2. timohueser commented on Nov 18, 2026

    @timohueser
    OwnerAuthor

    The size test confirms the hypothesis (iPhone 13, 2026-11-18, session 20261118201642-cgoe)

    The page /phone/compile of the measuring kit compiles the refused shaders in smaller sizes, each in a new page load. The size is the length of the code after each call is copied into its caller, which is what the Metal compiler does.

    Shader Size Result on the iPhone 13
    audit, whole 383 kB Refused after 9.8 s, with an "out of memory" error
    audit, 70 % 266 kB Compiles in 1.4 s
    audit, 45 % 120 kB Compiles in 0.8 s
    stamp without the road model, whole 258 kB Compiles in 0.8 s
    stamp with the road model, 25 % Compiles in 0.7 s
    stamp with the road model, 50 % Compiles in 2.4 s
    stamp with the road model, whole Refused after 6.5 s, with an "out of memory" error

    A small shader compiles directly after a refusal, in the same page load. So a refusal does not break the device for other shaders.

    Result: the Metal compiler of the phone has not enough memory for the largest shaders. The limit of audit lies between 266 kB and 383 kB. The size of stamp with the road model is not measured correctly by the page (it shows the size without the model), so its limit is known only as a share: between 50 % and 100 %. The shaders must become smaller by a part, not by a factor of ten.


    Generated by Claude Code

  3. timohueser commented on Nov 18, 2026

    @timohueser
    OwnerAuthor

    The "spiky" terrain of the first run did not show again in any later run on the iPhone 13 (two fault checks, one measurement with four flights). The owner confirms it (2026-11-18): the terrain is correct on screen, and with the ground fix of #3673 the view has its ground look and its forest. The cause of the spikes in the first run is not known. Numbers of the measurement with the fix (today's app, no stamp layer in the test data): first complete picture 9.3 s (walk), 11.6 s (valley), 31.1 s (zoom-out), 18.1 s (bridge and tunnel); frame median 29 ms, 49 ms, 29 ms, 35 ms; pools 616 MiB. The new roads still do not start (the shader size).


    Generated by Claude Code

  4. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    The owner's goals for TrailView on the phone (2026-11-21)

    The owner's words, in short:

    • Route planners are used mostly on phones, in the app. TrailView must run smoothly there. If it does not, the product is weak.
    • The main use on the phone is to look around at one place.
    • The resolution matches the size of the phone display. It does not have to be very high.
    • The frame rate does not have to be high, but it must be constant, so that touch interaction is smooth. Lag is not acceptable.
    • Close detail can be lower than on a computer. Objects such as signposts can go in the app.
    • Touch controls for movement (fly, walk) are an open question.
    • A CI check of the shader size comes after the shrink, when the shaders compile on the phone. It then makes sure that they always compile there. Not before.

    The iOS app spike #3765 comes first. It answers whether the web view of the app runs TrailView as well as Safari.


    Generated by Claude Code

  5. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    The owner's budgets for the phone tier (2026-11-21)

    After the app spike #3765, the owner set these targets for TrailView in the iOS app on the iPhone 13:

    What Target
    First open, also the first time in the app A view in a few seconds. 8 to 10 s is the most that is acceptable, and only if a shorter time is technically not possible.
    Memory Clearly less than 1 GB, with a good margin. Close to the limit is not acceptable, also with a native renderer that has more memory.
    Frame rate About 30 frames per second, smooth and constant.
    CPU and GPU Not near their limit while the view runs.
    Heat and battery The phone does not get hot, and the battery does not drain fast.
    Look Lower quality and fewer objects are acceptable, while the picture still looks good.

    The measurements that these targets apply to are in #3765. In short: one web page on the iPhone 13 has about 1.4 GB of memory, GPU memory included, and the load of today's TrailView goes over it. A native app has about 2.1 GB. When TrailView survives its load, the frame time is 41 to 71 ms, the GPU time is 28 to 33 ms, and the view is complete after 27 to 42 s.


    Generated by Claude Code

  6. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    Lever measurement on the iPhone 13 (2026-11-21)

    The app host of #3765, two sessions on the walk flight, the phone unplugged. Session A started "nominal" and ended "fair"; session B started "fair" and reached "serious" after 2.5 minutes, so its GPU times are about 3–5 ms higher. Build and data as in #3765. Branch prototype/trailview-ios-app (throwaway switches).

    The phone preset P: scale=0.5, terrain pool 0.5, ground-look pool 0.33, near shadows only, tree ranges ×0.5, no small objects and no street lamps, requests in flight ×0.5, 30 fps. "Headroom" is the memory that a probe could add after the flight before iOS stopped the page (steps of 32 MiB). A web page has about 1,408 MiB.

    Run Complete Eye ready Frame median / p95 / max GPU median Headroom
    Today's app, lighter (scale=0.5&pool=0.5), for comparison 32 s 9 s 42 / 86 / 244 ms 29 ms stopped in 1 of 4 loads
    P (A) 17.6 s 6.3 s 28 / 45 / 75 ms 22.3 ms 192 MiB
    P (B, warm) 17.7 s 3.8 s 37 / 59 / 147 ms 27.4 ms 192 MiB
    P, far shadows on 15.0 s 2.1 s 31 / 52 / 158 ms 23.4 ms 96 MiB
    P, no shadows 12.7 s 2.2 s 28 / 45 / 94 ms 21.7 ms 256 MiB
    P, full tree ranges 13.2 s 2.1 s 27 / 45 / 60 ms 21.4 ms 224 MiB
    P, full ground-look pool stopped by iOS in the load
    P, full terrain pool 15.0 s 2.0 s 27 / 40 / 65 ms 21.6 ms 160 MiB
    P, small objects on 18.4 s 2.4 s 29 / 49 / 95 ms 22.7 ms 192 MiB
    P, 400 MiB ballast before the load stopped by iOS in the load
    P, requests in flight ×1 (B) 24.7 s 2.9 s 33 / 52 / 120 ms 24.8 ms 192 MiB
    P, scale=0.7 (B) 26.1 s 2.4 s 36 / 59 / 140 ms 27.1 ms 160 MiB
    P, terrain range ×0.8 (B) 22.0 s 2.8 s 30 / 46 / 123 ms 22.9 ms 288 MiB
    P, finest=17 (B) 22.6 s 2.9 s 33 / 55 / 117 ms 25.5 ms 160 MiB
    P at 60 fps (B) 19.9 s 3.0 s 33 / 45 / 101 ms 25.2 ms 224 MiB
    P, valley drive (B) 15.6 s 3.0 s 34 / 60 / 115 ms 24.1 ms 192 MiB

    GPU passes of P (A, median of each pass when it runs): main pass ("terrain": the terrain, houses, roads and objects) 13.4 ms, vegetation 5.9 ms, near shadow casters 5.5 ms (when the near map is drawn), resolve 2.4 ms, ground look 1.8 ms. The far shadow casters cost 11.8 ms each time the far map is drawn.

    What the levers show:

    • P stops the kills of the load and halves the time to a complete view. The eye is ready after 2–6 s.
    • P still holds about 1.2 GB. Its GPU pools are 409 MiB. No lever moves the other ~800 MiB by more than 100 MiB. Where that memory goes is the first open question of the design. The 400 MiB ballast run confirms that the load's peak is above about 1 GB.
    • The far shadows cost the most per draw (about 12 ms, about 96 MiB), and they make the longest frames.
    • A coarser terrain (range ×0.8) is the largest frame lever: about −4.5 ms of GPU time, frames over 33 ms from 64 % to 27 %, and about 96 MiB less. Its look is not checked yet; a range below 4.6 can leave cracks (terrain/lod.ts).
    • The render scale does not change the GPU time (0.5 against 0.7). The main pass is not limited by pixels.
    • Tree ranges, small objects, finest=17 and requests in flight change the GPU time and the memory by less than the noise. They can stay at their desktop values.
    • The ground look needs its pool cut to load at all; at a third of the pool it reports pages short (groundShort 38 on the walk).
    • The phone cannot reach 60 fps (GPU 21–27 ms); a cap at 30 fps matters for power once the GPU work is smaller.
    • Even P warms the phone: "fair" after about 3 minutes of loads.

    Generated by Claude Code

  7. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    Where the memory of the phone preset goes (2026-11-21)

    Follow-up of the lever table above. Same preset P, same build and data. "Footprint" is about 1,408 MiB (the limit of a web page on the iPhone 13) minus the headroom that a probe could still fill.

    P on the iPhone 13 Headroom Footprint
    Started at a place without data (45° N, 2° E), after 30 s 1,088 MiB about 320 MiB
    After the walk loaded 192 MiB about 1,216 MiB

    So the engine's fixed cost is small: 11 workers, 60 pipelines from 30 shader modules (1 MB of WGSL), and the pools before they hold data. The load of one view adds about 900 MiB.

    What the load fills, measured as far as possible:

    Part Size How
    GPU buffers and textures about 410 MiB Every createBuffer and createTexture of the page, counted on the phone: the same as the pools. Nothing large is outside them.
    JavaScript, main page 75 MiB Chromium's measureUserAgentSpecificMemory after a full load of P (headless, SwiftShader). WebKit's numbers can differ.
    JavaScript, workers about 170 MiB Same: stamp 57, road 49, ground 43, houses 12, tree models 7 MiB
    WASM in the workers under 5 MiB Each worker posts its memories, on the phone
    Not placed about 250 MiB Candidates: decoded tiles in flight, request bodies, garbage that the JavaScript heap has not collected yet

    The empty pools cost little because iOS backs a GPU allocation only when it is written. They count fully once a view fills them.

    For the design:

    • The phone budget is a budget for the loaded data, not for the engine. A native renderer would not change this part.
    • The parts to cut: the pools (pages, ground look, instances, roads, features), the JavaScript data of the main page and of the stamp, road and ground workers, and the unplaced part of the load.
    • The tools on branch prototype/trailview-ios-app: phone-measure.js counts the GPU objects (memory.alloc), the variant p-empty measures the fixed cost, phone-wasm.js reports each worker's WASM, and the kit's local listener (--local) lets Chromium split the JavaScript memory by worker.

    Generated by Claude Code

  8. added a commit that references this issue on Nov 21, 2026
  9. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    Where the memory of the phone preset goes: the placement (2026-11-21)

    Follow-up of the comment "Where the memory of the phone preset goes". Same build, data and preset P. App host, iPhone 13 unplugged. Each run is a cold walk load with its 20 s flight, then the step of the run, then the memory probe in steps of 32 MiB. Session app-20261121144156-pr7c (results of the kit on the Mac). Kit: branch prototype/trailview-ios-app at 60acffe, address option after= of phone-measure.js.

    Run Step before the probe Headroom Given back against P
    P, walk none 288 MiB –
    P, walk 60 s with the view still 256 MiB none (−32, one step)
    P, walk the 11 workers end 800 MiB 512 MiB
    P, walk the engine ends (destroy() destroys every pool), and the workers end 928 MiB 640 MiB
    No data, after 30 s the 11 workers end 1,152 MiB (1,088 MiB with the workers, session of 14:05)

    The footprint of P in this session is about 1,120 MiB (1,408 − 288). In the session of 14:05 it was about 1,216 MiB: two sessions differ by up to 96 MiB.

    Part of P's footprint MiB From
    The page and the engine with no data, without workers about 256 1,408 − 1,152
    The 11 workers with no data about 64 1,152 − 1,088
    The data of the workers about 448 512 − 64
    What the end of the engine gives back besides the workers: the pools as iOS backs them. The main page still holds its JavaScript. about 128 928 − 800
    The rest: the JavaScript of the main page, and what the end of the engine does not give back about 224 1,120 − the rows above

    The same preset on the M1 Pro (headless Chromium on Metal, the phone's canvas of 780 × 1688, two runs): the JavaScript after the walk flight is 417–423 MiB, not 245 MiB. The earlier figure was read before the flight. Main page 104 + canvas 15, ground workers 2 × 80–85, stamp 64, road 49, houses 13, tree models 3 × 3, plants 1, terrain decode 2 × 1. With ground=plan, the GPU pools are 462 MiB (feature masks 82, records 32, plan pieces 20, no road pool), and the JavaScript is about the same: two plan workers of 37 MiB each take the place of the road worker.

    What this places:

    • None of it is garbage: 60 s with the view still gives nothing back.
    • The workers are the largest part: about 512 MiB of 1,120. On the phone they hold about 1.5 times what Chromium reports for them (448 against about 300). After one flight, each worker is near its byte cap (ground decode 96 MiB per worker, stamp 48, road 55 + 9).
    • The pools that iOS backs are smaller than the engine's count: the end of the engine gives back about 128 MiB against 409 MiB counted. iOS backs only the parts that the page writes.
    • So the part that the earlier comment did not place is JavaScript: the caches of the workers grow during the flight, and WebKit holds more for them than Chromium measures.

    Each kind of worker (session app-20261121160859-hhhi)

    P on the walk, then one kind of worker ends, then the probe. This session had no run of P alone; the table takes P's 288 MiB of the session before.

    Workers that end Headroom Given back Chromium on the M1 Pro, after the flight
    Ground decode (2) 448 MiB about 160 2 × 80–85
    Stamp 448 MiB about 160 64
    Road 352 MiB about 64 49
    Terrain decode (2), houses, tree models (3), plants 320 MiB about 32 about 23

    The kinds add up to about 416 MiB; all 11 workers at once gave back 512 MiB. The difference is within the noise between sessions (up to 96 MiB).

    • The ground decode workers hold on the phone what Chromium reports: their caches are image arrays.
    • The stamp worker holds about 2.5 times what Chromium reports. Its cache holds the decoded features as many small JavaScript objects, and WebKit stores them larger.

    Generated by Claude Code

  10. added a commit that references this issue on Nov 21, 2026
  11. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    Does a session grow? The soak of preset P

    Session app-20261121190117-jv6r (iPhone 13, the app host of prototype/trailview-ios-app, commit 20001fd), plugged in. Both runs fly the kit's valley drive; the probe fills memory in steps of 32 MiB until iOS stops the page.

    Run Flight Headroom Footprint
    p 20 s 224 MiB 1,184 MiB
    p-soak 600 s, to and fro 128 MiB 1,280 MiB

    Ten minutes of driving add 96 MiB (three probe steps). The engine counts the same pools at the start and at the end (409 MiB), so the growth is in what iOS counts: more written pool parts, fuller caches, or both. The ground jobs: 1,848 in the soak, none failed; the ground look was short of 17 pages at the end.

    The design now gates the soak at tier=phone (≤ 896 MiB, the owner's limit of 2026-11-21) and runs it as soon as #3778 merges.

    The shadow gallery of the same day (11 views at 780 × 1688, the near map against both maps) showed that without the far map, views more than 100 m above the ground lose every object shadow. The owner keeps the far map on the phone.

  12. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    Turn reuse prototype on the iPhone 13 (2026-11-21)

    The turn prototype (reuse=1, from the turn optimization session) ran once on the iPhone 13 in the prototype app. Preset P (pacer 30, scale 0.5), canvas 780 × 1688, eye at rest at the start of the walk, phone unplugged. Kit: commits 95c0651 and cbb09e6 on draft PR #3768.

    Variants: off; reuse (margin 1.25, 15 scene frames/s); margin (1.5 × 1.1, 8/s); lead (1.5 × 1.1 ahead of the turn, 5/s).

    Run Shown fps Scene / present-only frames GPU ms per shown frame (mean) Scene frame GPU (median) Interval median / p95 / max ms
    Turn 360° in 8 s, off 27.3 219 / 0 27.9 27.0 36 / 53 / 67
    Turn, reuse 18.6 105 / 44 33.0 44.7 52 / 91 / 305
    Turn, margin 16.6 62 / 72 32.4 67.0 41 / 126 / 172
    Turn, lead 20.0 39 / 121 18.5 70.0 34 / 117 / 193
    Look ±30° at 45°/s, off 25.3 136 / 0 28.6 27.2 36 / 61 / 74
    Look, reuse 19.7 71 / 35 30.5 45.3 51 / 82 / 118
    Look, margin 21.8 42 / 74 20.4 52.8 36 / 83 / 125
    Look, lead 23.1 28 / 95 15.1 61.5 34 / 91 / 127
    • A present-only frame costs 0.8–1.1 ms of GPU. A wide scene frame costs 45–70 ms, which is 1.7–2.6 × a normal frame. The GPU queue is serial, so each wide scene frame holds back the frames after it.
    • Result: with the lead, the GPU time per shown frame falls by 34 % (turn) and 47 % (look). But the turn shows fewer frames (20 against 27 a second), and the p95 interval doubles. As it is, the prototype does not make turning smooth on the phone.
    • Load with reuse off: idle after 12.7 s, 7.6 s of GPU time in the first 15 s. With reuse=1, iOS ended the page 10 s into the load. This is one sample, so the cause is open: the 27 MiB of wide targets on top of a load near the limit, or chance.
    • The wide targets add 27–29 MiB (textures 343 → 370–372 MiB).
    • Thermal state "nominal" until the last run (lead, look), which ended at "fair".

    For T3 (coarser far terrain): these runs do not remove the need for it. Turn reuse helps only if a turn's scene frame stays within one frame budget on the phone, for example with a lower render scale for the wide frames. That is not tested.

  13. added 3 commits that reference this issue on Nov 21, 2026
  14. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    Turn reuse, second iPhone 13 run: turn step cut for the phone, load step passes (2026-11-21)

    Setup as in the first run (preset P, canvas 780 × 1688, eye at rest, unplugged). Kit commit 5821c70 on draft PR #3768. The stop rule was agreed before the run between the turn session and the phone session.

    Turn step. The candidate is margin 1.1 × 1.02 ahead of the turn, at 15 scene frames/s. It had to pass all three checks on both scenes: fps within 1 of off, p95 interval within 10 % of off, and at least 25 % less GPU per shown frame.

    Run Shown fps GPU ms per shown frame Scene frame GPU (median) p95 interval ms
    Turn, off 23.9 29.6 28.9 59
    Turn, candidate 20.6 30.8 42.0 79
    Look, off 27.2 27.1 27.2 50
    Look, candidate 22.3 26.8 40.0 71

    The candidate fails all three checks on both scenes. The wide margin (1.5 × 1.1) at 15/s gave 46 ms scene frames, against 67–70 ms at 5–8/s in the first run. So the GPU clock adds cost at low rates, but the wider frame is also real work. The thermal state was "nominal" for the off runs and "fair" for the candidate runs.

    Load step (reuse=1&margin=1,1, no wide frames), two loads each:

    • GPU time in the first 15 s: 8,812 ms → 5,698 ms (−35 %).
    • Time to idle: 14.12 s → 13.56 s.
    • Both loads survived.
    • This passes the rule: at least 30 % less GPU, idle within 10 %.

    Verdict of the turn session (quoted): "the turn step is cut for the phone, and the load step passes." A normal frame already takes 27–30 ms of the 33 ms budget, so any scheme that makes some frames larger drops frames. The phone needs a cheaper normal frame first. The load step may come back as its own change. Whether the cut also ends the turn step on the desktop is the owner's decision.

  15. added a commit that references this issue on Nov 21, 2026
  16. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    #3778 on the iPhone 13: the caches at tier=phone (2026-11-21)

    The soak misses its gate: it ends with 416 MiB of headroom, and the gate is 512. The kind runs also miss their gates for the ground workers, the stamp worker and the small workers. The next lever is #3793.

    Setup: the iPhone 13 in the prototype app (draft PR #3768, kit commit f0d3d77, which holds PR #3789). The kit's variant p is now tier=phone. The tier keeps the far shadow map and the render scale 0.7, which preset P did not have. Each run is a cold load. A headroom is what the probe can still fill, in steps of 32 MiB. Two sessions: app-20261121205441-2vcb (6 runs) and app-20261121211443-k98l (the base run).

    Run Headroom MiB, tier=phone Headroom MiB, P (earlier sessions)
    No data, 30 s (p-empty) 1,088 1,088
    Walk, base (p) 448 192 to 288
    Walk, then the ground workers end 544 448
    Walk, then the stamp worker ends 640 448
    Walk, then the road worker ends 608 352
    Walk, then the small workers end 512 320
    Full turn at the walk 288 96
    Soak, 10 minutes of the valley drive (p-soak) 416 128

    The footprint (1,408 − headroom):

    • After a walk load: about 960 MiB (P: 1,120 to 1,216).
    • After 10 minutes of driving: about 992 MiB (P: 1,280). The gate is 896.

    What each kind gives back (its run minus the base of 448), against #3778's gate (the phone value plus 32):

    Kind Gives back P gave back Gate Result
    Ground decode workers (2) 96 160 72 miss by 24
    Stamp worker 192 160 112 miss by 80
    Road worker 160 64 32 (0 after #3110) #3110 deletes it
    Terrain decode, house, tree model and plant workers 64 32 48 miss by 16

    The noise is large. The road worker's cap did not change, but it gave back 160 MiB against 64 with P. There is only one base run, and P's base differed by 96 MiB between sessions. So each gain above can be off by about ±96 MiB. The ground and small-worker misses are within that noise. The stamp worker's is not: it holds more than its 24 MiB cap allows, and more than with P's cap of 48. Its cap does not bound it, because it keeps the tiles that a view wants, and WebKit holds its decoded features as many small objects.

    Load times show no change: eye ready 2.1 to 2.4 s (the first run of the session 6.5 s, a first open), near ready 3.4 to 5.4 s, complete 11.7 to 15.4 s. The full turn completed in 14.6 s (P: 13.4 and 13.6 s), one sample. Soak frames: interval median 31 ms, p95 49 ms. GPU median 23.6 ms (P: 22.8 ms with scale 0.5 and no far shadows).

    What is not in yet: #3110 deletes the road worker (about 64 MiB with P), and #3779 makes the far terrain coarser (32 to 96 MiB). With both, the soak lands at about 832 to 896 MiB, at the gate with no margin. So the next lever starts now: #3793, a compact form of the decoded features in the stamp worker.

    Time: the phone sessions took about 17 minutes, and the analysis about 10.

  17. timohueser commented on Nov 21, 2026

    @timohueser
    OwnerAuthor

    The load step of the turn prototype ships as #3790 (design #3784): a view at rest draws 10 frames a second while it loads. iPhone 13, 8 cold loads of the walk view in both orders: GPU time −20 % (median 8,612 → 6,880 ms), drawn frames about halved, time to idle 14.0 s median in both, all loads survived. The table is in the pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions