# How iris renders an unbounded number of images **Built 2026-09-04**, in `iris/core` and `iris/src/default/render.rs`. This file is the design and the measurements behind it; the deliberation that produced it -- the prior-art survey, the proposal and its review -- was deleted on 2026-09-08, having been carried out. What is kept is why the old approach could not stay (it is the reason the current one looks as it does), the numbers, and what actually landed. Iris (the person) asked whether iris's (the library's) approach to "draw however many images happen to be on screen" -- relevant here because a transcript can hold an unbounded number of attached screenshots -- works on mobile, her recollection being that it does not. It did not, and this is what replaced it. ## The problem Every texture iris ever creates — every `Image` widget (`iris/src/widget/image.rs`) and every glyph atlas page — gets a permanent slot in one array via `Textures::add` (`iris/core/src/primitive/texture.rs:65`). Both of iris's texture-sampling primitives (`TEXTURE` and `GLYPH`) read that array by index: `core/src/render/shader.wgsl:56` declares `var views: binding_array>`, sized by `UiLimits::default()` (`core/src/render/mod.rs:347`) at **100,000 textures, 1,000 samplers**. Getting a device to accept that layout needs three wgpu features — `TEXTURE_BINDING_ARRAY`, `SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING`, `PARTIALLY_BOUND_BINDING_ARRAY` — which correspond to Vulkan's `VK_EXT_descriptor_indexing` ("bindless"), promoted to Vulkan core at 1.2. A transcript with an unbounded number of image attachments is exactly the case that grows this array without bound: each attachment becomes its own `Image` widget, which takes its own permanent array slot until dropped. ## What was measured **A new rig, `rigs/gpu-probe`**, asks a device for exactly iris's features and limits with no window and no APK — a plain executable pushed with `adb push` and run from `/data/local/tmp`. It has two parts: `wgpu::Adapter::request_device` with iris's exact `Features`/`Limits` (`src/main.rs`), and a raw Vulkan query bypassing wgpu entirely via `ash` (`src/vk.rs`), to tell "the driver doesn't have it" apart from "wgpu didn't detect it." - **On this VM's own GPU** (Vulkan via Venus onto an RX 7900 XT): `IRIS DEVICE: ok`. Not the case that matters — nobody's phone is a discrete desktop GPU — but it is why the design was never checked before now: it always worked in the one place it was tried. - **On the Android emulator's guest Vulkan**, both ICDs it ships (`vk_swiftshader_icd.json` and, cold-booted, `lvp_icd.json`/lavapipe): `request_device` **fails** — `Unsupported features were requested: TEXTURE_BINDING_ARRAY | SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING | PARTIALLY_BOUND_BINDING_ARRAY`. The raw `ash` query on lavapipe shows the driver itself reporting all seven descriptor-indexing sub-features as `true` at device API version 1.3 — so wgpu-hal's own feature detection is being more conservative than the driver here, for a reason not chased further (a likely instance-version negotiation gap, since the extension only promoted to core at 1.2). That part is a wgpu-hal/emulator question, not the finding that matters, and is **not** why this design is rejected. **The finding that matters is about real phones, sourced rather than recalled:** - The **Android Vulkan Profile 2025** — Google and Khronos's current baseline, covering **80.1% of active Vulkan-capable Android devices** as of October 2025 ([developer.android.com/ndk/guides/graphics/android-vulkan-profile](https://developer.android.com/ndk/guides/graphics/android-vulkan-profile)) — does **not** require `VK_EXT_descriptor_indexing` or any descriptor- indexing feature. It requires `shaderSampledImageArrayDynamicIndexing` (indexing by a value uniform across the invocation — Vulkan 1.0 baseline, unrelated to bindless) and stops there; true of the 2021 and 2022 profiles as well. - Arm's own developer documentation states **"`VK_EXT_descriptor_indexing` is supported on all Valhall and 5th Gen GPUs"** ([developer.arm.com/mobile-graphics-and-gaming/vulkan-api-best-practices-on-arm-gpus](https://developer.arm.com/mobile-graphics-and-gaming/vulkan-api-best-practices-on-arm-gpus)) — Mali generations from roughly 2019 (Mali-G77) onward, with no claim made for Bifrost, Midgard or Utgard, which are still common in budget and older Android phones that are still in daily use. - A search engine's summarized claim of "1% support on Android" for this extension was checked against its cited source (an Arm blog post from 2021) and **was not actually there** — that number does not appear in any primary source found and should not be repeated. The baseline- profile finding above is the one with an attributable source; use it instead. So this is not a software-renderer artifact. A real, currently-shipping share of the Android fleet lacks the feature iris's texture pipeline asks for unconditionally, and neither the emulator's failure nor the current official hardware baseline gives any reason to expect that to change soon. ## Implemented, 2026-09-04 The shape above, built as proposed with one structural addition the proposal didn't need to spell out and one bug it predicted made moot rather than literally fixed. Files: `core/src/primitive/texture.rs` (`Textures`, `TextureHandle`), `core/src/render/texture.rs` (`GpuTextures`), `core/src/render/primitive.rs` (`Primitives`, `GlyphPrimitive`), `core/src/render/atlas.rs`, `core/src/ui/painter.rs`, `core/src/render/mod.rs` (`UiRenderNode`, `UiLimits` removed), `core/src/render/shader.wgsl`, `src/default/render.rs`, and `rigs/gpu-probe/src/main.rs`. **1. Atlas pages as array layers.** `GpuTextures` owns one `texture_2d_array` (`array_texture`/`array_view`), grown by doubling (`grow_array`): a new texture is created at twice the layer capacity, the old layers are copied across with `copy_texture_to_texture` (GPU-side, no readback), and every bind group that referenced the old view — the main one and every live standalone image's — is rebuilt, since the view's identity changed. `GlyphPrimitive` carries `layer: u32` instead of `view_idx`/`sampler_idx`; the layer number is assigned synchronously in `Textures::add_page` (a plain counter, `next_page_layer`), not by the renderer, because `GlyphAtlas::insert` needs it in the same call, before any GPU sync happens — the renderer only finds out later, when it processes the queued `Push`. **2. Standalone images, one bind group each.** `TextureKind` on `TextureHandle`/`Textures` distinguishes `Image` (a plain bind-group index, `slot`) from `Page { layer }`. `Primitives` gained a second per-layer list — `images: Vec`, tagged `IMAGE_BINDING` — separate from `instances` (rects and glyphs), written by `Painter::write_image` rather than through the generic `Primitive` trait, since an image has nowhere in `PrimitiveData` to put a per-instance entry once the bind group already picks the texture. `UiRenderNode::draw` draws a layer's `instance` buffer once as before, then walks `image_instance` one entry at a time, binding that texture's `BindGroup` (`GpuTextures::image_bind_group`) and issuing `draw(0..4, k..k+1)` per image. Group 2's layout is exactly the proposed `{atlas array, one image texture, sampler, masks}`; the main draw binds a 1x1 null view in the image slot. **The one addition beyond the proposal**: the masks storage buffer lives in every per-image bind group (group 2, binding 3), and `ArrBuf` recreates its buffer whenever the mask count changes size (`render/util/mod.rs`'s `ArrBuf::update` now returns whether it resized). A resize invalidates every bind group holding the old buffer, not just the main one, so `GpuTextures::update` takes a `masks_resized: bool` and calls `rebuild_image_bind_groups` when it's set, alongside the same rebuild the array-growth path already needed. This wasn't a design question the proposal had to answer (it treated bind-group construction as a given), but it's exactly the shape of trap layer growth already had, so it uses the same fix. **3. No thumbnail atlas.** Not built, as proposed. **4. Removed**: `TEXTURE_BINDING_ARRAY`, `PARTIALLY_BOUND_BINDING_ARRAY`, `SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING` from `src/default/render.rs`'s `request_device`, and `UiLimits` (the type itself, not just its binding-array methods — once its two fields were gone there was nothing left in it, and `UiRenderNode::new` no longer takes a limits parameter). `binding_array` no longer appears anywhere in `shader.wgsl`. **5. Sampling** is still `NonFiltering`, unchanged, per the proposal's own note that this is a separate decision for whenever the image widget itself is touched. **The `changed = false` bug is structurally gone, not patched.** The old `GpuTextures::update` held one `changed: bool` that a `Patch` reset unconditionally, which could erase an earlier `Push` in the same batch (a new atlas page's `Push` immediately followed by `GlyphAtlas::insert`'s `Patch`, both queued before the renderer ever runs). The new `update` computes the rebuild signal by OR-ing each event's own answer (`rebuild_main |= self.push(...)`), and `Patch`'s arm simply never contributes to it — there is no shared mutable flag left for a `Patch` to stomp on. Documented at the call site (`core/src/render/texture.rs`, `GpuTextures::update`'s doc comment and the `Patch` match arm's comment) rather than fixed as a one-line diff, since the mechanism that could go wrong no longer exists. **In-layer draw order is an explicit invariant now, not just a fact about `swap_remove`.** `UiRenderNode::draw` draws every layer's images after its rects and glyphs, and `Primitives::apply_free`'s doc comment states directly that both of a layer's lists (`instances` and `images`) free with `swap_remove` and that nothing may assume adjacency survives a free — recorded there because `apply_free` is the one place a change to either list's ordering would have to be reconciled. **Verified:** - `cargo fmt --all -- --check`, `cargo build --workspace --all-targets`, `cargo clippy --all-targets`, `cargo test --workspace` all clean in `iris/`, on the pinned `nightly-2026-09-03` toolchain. 14 tests pass (unchanged from I1; nothing here is pure-logic enough to add a unit test to — it's all GPU resource wiring). - `iris/run-headless.sh minimal --shot /tmp/minimal.png` and `iris/run-headless.sh tabs --shot /tmp/tabs.png`: both render correctly on this VM's GPU (Venus) — `tabs`'s glyph-atlas text renders in every panel, confirming `GlyphPrimitive.layer` addresses the array correctly. - The standalone-image path specifically: a throwaway example (not committed) with an `image(...)` widget as part of the root, run the same way, rendered the image next to glyph-atlas text in one frame — confirming a live `BindGroup` built by `GpuTextures::create_image` and bound per-`draw()` call actually samples the right texture. `tabs`'s own "image span" tab exercises the same widget but needs a click to reach, which the headless compositor can't deliver (no seat devices, per I1's own note on this file) — the throwaway example is what stood in for it. - **Exercised, 2026-09-04: `grow_array` under real load, on `tabs`.** Rather than building a purpose-made glyph flood, `PAGE` (`core/src/render/atlas.rs`) was temporarily dropped from 1024 to 64 — small enough that `tabs`'s ordinary mix of sizes and families (nothing exotic: a handful of `Text` widgets at a few sizes, one at `Family::Monospace`) already exceeds one page's worth of distinct glyphs. A one-line `eprintln!` in `grow_array` confirmed two real grows in a single run (`GROW_ARRAY: 1 -> 2` then `GROW_ARRAY: 2 -> 4`, i.e. glyphs landed on at least a third layer), and `iris/run-headless.sh tabs --shot` showed every tab's text rendering correctly with no corruption or missing glyphs — confirming the `copy_texture_to_texture` grow-and-relocate path and cross-layer sampling (`GlyphPrimitive.layer` addressing a layer beyond the first) both work. Command: `sed -i 's/PAGE: u32 = 1024/PAGE: u32 = 64/' core/src/render/atlas.rs`, rebuild, `./run-headless.sh tabs --shot /tmp/x.png`, then `git checkout -- core/src/render/atlas.rs` to revert — this is a throwaway diagnostic value, never a committed change, since a real 1024px page holding only a handful of glyphs at a time would be mostly wasted space in normal use. Confirmed the revert left `tabs` and `minimal` byte-identical to the pre-check screenshots afterward. - **The decisive check**, `rigs/gpu-probe` rewritten to request iris's new (empty) feature/limit set and run on this checkout's own emulator (`ai-app-2`, via `emu`), booted with `EMU_GPU=software` so the guest gets a real Vulkan device (SwiftShader) rather than the `-gpu host` default, which disables Vulkan in this VM entirely (`-feature -Vulkan`, because gfxstream can't pair Venus with the real GPU here — worth remembering, since the *default* `emu up` gives a device with **no** Vulkan adapter at all, which reads exactly like the old bindless failure if you don't know to ask for `EMU_GPU=software`): cd rigs/gpu-probe ANDROID_NDK_HOME=$HOME/Android/Sdk/ndk/29.0.14206865 \ cargo ndk -t arm64-v8a -P 26 build --release EMU_GPU=software emu up # from ~/repos/emulator-tools adb push target/aarch64-linux-android/release/gpu-probe /data/local/tmp/ adb shell chmod 755 /data/local/tmp/gpu-probe adb shell /data/local/tmp/gpu-probe Output: `adapters: 1 — Vulkan SwiftShader Device (Subzero) (Cpu)`, `features iris requires:` (none listed — the set is empty), `max_buffer_size … ok`, and **`IRIS DEVICE: ok`**. This is the fix measured working, on the exact rig that first measured it failing. Emulator stopped afterward (`emu down`); nothing was left running.