Home / Engineering notes / Boot picture
Boot picture engineering notes
Short, actionable lessons from authoring the boot picture of ADR-152, for the next change to branding/boot in oblivios-platform.
Short, actionable lessons from authoring the boot picture of ADR-152, for the next change to branding/boot in oblivios-platform. The design and the renderer constraints are in 2026-10-11-boot-picture-design.md; the evidence rows are BOOT-* in the validation matrix.
- Simulate the renderer, do not read it once. The renderer draws only two copies of the scrolling texture, so a texture narrower than the right edge of the window leaves part of the bar blank at some offsets. The first simulation used the wrong composite mode (
-compose Src) and showed a full bar at every offset, so it hid the defect; a simulation needs a case that must fail before it is trusted. The package test now composes the renderer's drawing at twelve offsets and is mutation-checked with the narrow texture. - A test that passes first time is not yet a test. Mutate each assertion. Two of the checks here were too weak: the name check was met by the mint word alone, and the texture-width defect was caught by an earlier unrelated check. Both were found only by removing the thing under test.
- ImageMagick noise at this amplitude does nothing.
-attenuatewith+noise Uniformchanged no pixel for values up to 0.08 on an 8-bit image (maximum difference 0). Use-fxwith a function of the pixel position; it is deterministic, and the measured maximum difference is one 8-bit level.-fxrejects built-in single letters as user symbols (t,k); use a longer name. - Check a font generator against a known output. The glyph and kerning code reproduced the width of the old Aegis lockup exactly (242.3 px) before it was used for the new name.
- Headless Chromium captures animation phases.
--virtual-time-budgetadvances SVG animation time, so a still can be taken at any phase of a loop. - Author renderer-facing patches twice and compare. The package patches are based on the stock files; the build tree carries the earlier ADR-019 commits, so a delta commit is landed there. Compare
git rev-parse HEAD:<path>of both routes before landing. - Measure the geometry the simulation assumes. The first simulation put the loading texture at the top of the mask and the test passed; the renderer puts every texture on the bottom edge (
drawTexturedQuadmaps y upwards), so the bar was hidden and the picture still. A simulation counts only after one frame of it equals a frame captured from the real renderer on a device; this one was checked afterwards (5e-8 of the pixels differ on the bottom edge, 8e-5 on the top edge). - Replay the boot animation on a
userdebugdevice instead of building to look at it. Withadb root:setprop service.bootanim.exit 1and wait untilinit.svc.bootanimisstopped, thensetprop service.bootanim.exit 0andsetprop ctl.start bootanim, andscreencapframes 0.37 s apart. A service that still runs ignoresctl.start, which gave six identical frames and a false negative once. To try an asset without an image, bind-mount a copy offramework-res.apkover/system/framework/framework-res.apkfor the replay (rewrite the zip with the entry replaced and runzipalign -p 4), confirm in/proc/<pid>/mapsthat the process mapped the copy (the inode of the copy), andumountand compare the hash of the original afterwards.adb unrootwhen done. - A pixel equal to the clear colour is no evidence of a drawn texture. The edge colour of the loading texture equals the clear colour, so an empty window looked the same as a window that showed texture rows of the wrong place. Give a test texture a colour that cannot be the background (the track
#1A3B35is not). - Replay of the boot animation on a running phone (2026-11-03,
lynx2026110203,adb root):setprop service.bootanim.exit 1and wait untilgetprop init.svc.bootanimreadsstopped, thensetprop service.bootanim.exit 0andsetprop ctl.start bootanim;ctl.startdoes nothing while the previous replay still runs. The service stays up untilservice.bootanim.exitis set to 1 again.screencap -pof eight frames 0.37 s apart shows the segment (#4AC2A3, 34 pixels wide in the row 2154) in four frames and the track alone in the other four, so a check that needs the segment reads several frames. The replay is not the boot: 2.5 s after the start the process has 33 MB PSS (84 MB RSS, 71 MB of graphics indumpsys meminfo, 0.72 to 0.75 s of CPU), a figure for no comparison with the stock image until one is read the same way. - A
bootanimation.zipon the device hides the textures offramework-res.apk(2026-11-05,lynx2026110501, tag2026110200):BootAnimation.cppplays/product/media/bootanimation.zip(lookup: the apex, then/product/media/,/oem/media/,/system/media/) before it falls back to the built-in texturesandroid-logo-mask.pngandandroid-logo-shine.png, so a correctframework-res.apk(the two PNGs equal to the source, read withunzip -p framework-res.apk assets/images/<name> | sha256sum) can still boot with another picture. Tag2026110200added the upstream projectbranding, whosebootanimation_zip(a GrapheneOS logo, 540 frames of 433 x 586, 3615757 bytes)base_product.mkinstalls in every product (ADR-219). First read on a device:adb shell ls -l /product/mediaandunzip -lof the pulled zip; look at one frame (part2/00040.png). The replay of the service then shows the window pixels000000in every frame instead of the track1A3B35. Hide the zip for one replay withadb root,mount -t tmpfs tmpfs /product/media, the replay,umount /product/media, the hash of the zip read before and after,adb unroot: the same replay then showed the track in every frame and the segment4AC2A3in two of six. A check that reads onlyframework-res.apkpasses while the real boot is wrong (the replay ofBOOT-009does catch it); read/product/mediafirst on the first image of every new tag.
Read from docs/architecture/boot-engineering-notes.md.