Write down what the Android renderer change cost, and what else is owed

Three compromises were taken deliberately over the last few days and none of
them was written anywhere a future reader would look. So `docs/technical-debt.md`,
and two corrections to the architecture document that the Android change made
untrue the moment it landed.

**TD-1, the Android readback.** §12/6.1 says GPU results never round-trip
through the CPU, and the develop view on Android now does exactly that. That
is worth recording as a breach with reasons rather than quietly leaving a
constraint the code no longer honours — the next person to read §6.1 and then
`DevelopSession::render` would otherwise conclude one of them is a mistake.
The entry carries the device measurements that forced it, why setting
`preTransform` is not a fix available to us, and the three separate things any
one of which would remove it.

**TD-2 and TD-3**, the serial thumbnail fetch and the unbounded drain, were
found while chasing the tearing and are still outstanding. Both have a known
shape for the fix; neither is a bug, and neither should be discovered again
from scratch.

The architecture document said the app renders "through wgpu to Vulkan on both
Linux and Android", which stopped being true at 6267802, and §12/6.1 claimed a
constraint with no exceptions. Both now say what the code does and point at
the debt entry for why.

The numbers are labelled with what they are. TD-1's readback cost has *not*
been measured on the device and says so, and TD-3's figures are from a debug
build and say so — a documented measurement that quietly turns out to be the
wrong build is worse than no measurement.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-08-26 22:36:37 +02:00
co-authored by Claude Opus 5
parent e0cb968e04
commit 336a1fd296
2 changed files with 161 additions and 2 deletions
+11 -2
View File
@@ -10,8 +10,10 @@ and records the decisions and constraints behind the design.
## 1. Overview
DarkRoom is a Rust application with a Slint interface, rendering through wgpu to Vulkan on both
Linux and Android. The design is organised around four ideas, each of which the rest of this
DarkRoom is a Rust application with a Slint interface. On Linux it renders through wgpu to Vulkan.
On Android it renders through Skia to OpenGL — not by preference but because wgpu's Vulkan
swapchain cannot pre-rotate, which tears a portrait window on a landscape-mounted panel
([technical-debt.md TD-1](technical-debt.md)). The compute passes are wgpu on both. The design is organised around four ideas, each of which the rest of this
document elaborates:
1. **Pixels stay on the GPU.** From decode to display, image data never round-trips through the
@@ -980,6 +982,13 @@ At 4K the shader finishes in 0.28 ms and then 7.15 ms is spent moving pixels thr
26× overhead that scales with area, which is why an uncapped window resize falls off a cliff. The
constraint is not a stylistic preference; it is the dominant cost in the frame.
**One exception, on Android only, and it is debt rather than a revision.** The develop view there
reads the frame back rather than handing over a texture, because zero-copy requires Slint to draw
with wgpu and wgpu's Android swapchain tears a portrait window. The reasoning, the measurements
that forced it and what would remove it are in [technical-debt.md TD-1](technical-debt.md). The
constraint above still governs every other path, including the desktop develop view and the export
pipeline, and the Android exception is expected to be temporary.
### 6.2 Tiling from day one
Mobile GPUs have far less memory. Retrofitting tiling into a whole-image pipeline is a rewrite.