ai-app/docs/TEXTURES.md

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<texture_2d<f32>>, 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) — 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) — 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<PrimitiveInstance>, 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<Mask> 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.