Optimize cinematic rendering for integrated Android TVs

This commit is contained in:
Elijah Kuntz 2026-10-19 09:49:08 -07:00
parent dc5908cb3b
commit 1f69422354
15 changed files with 366 additions and 153 deletions

View file

@ -40,7 +40,7 @@ To return to the previous routing, turn off Luma's Home override, then open Proj
**App labels** offers Always, Focused only (default), and Never. Accessibility app names remain available in all modes. Other settings include 5/6/7 columns, background dimming, automatic or fixed accent colors, reduced motion, clock visibility, and 90-second scene rotation. Alpine uses the bundled original wallpaper; Aurora and Midnight are inexpensive procedural gradients.
Focus uses a 6.5% scale increase, a 160 ms transition, and an app-colored native shadow. Wallpaper/artwork crossfades last 320 ms. The launcher has no continuously rendered blur or background video. Optional screensaver video runs only while the screensaver is visible.
Focus uses a 6.5% scale increase, a 160 ms transition, and an app-colored native shadow. Background crossfades last 280 ms. The launcher has no continuously rendered blur or background video. Optional screensaver video runs only while the screensaver is visible.
The app grid uses one 260 ms scroll animation for remote focus movement. **App section text** can hide the heading, installed count, and customization hint; it is hidden by default without changing the original spacing.
@ -97,10 +97,10 @@ Android scheduling and installation behavior follow the [JobInfo API](https://de
## Performance design
- Platform Java/Android views and Canvas; no WebView, Compose runtime, playback engine, or third-party runtime dependencies.
- Single sampled RGB565 wallpaper (960 × 540 for the bundled 1920 × 1080 image).
- Single sampled RGB565 wallpaper (960 × 540 for the bundled 1920 × 1080 image). Cinematic gradients, dimming, and artwork are composed off the UI thread into an opaque texture capped at 960 × 540; navigation crossfades the finished textures instead of re-running several full-screen shaders every frame.
- App artwork is rasterized to 288 × 162. Icon cache is capped at 3 MiB; visible tiles also hold their displayed images.
- Plex image cache is capped at 3 MiB. Hero images are sampled to at most roughly 1280 × 720; rows and network response sizes are bounded.
- At most the current and previous artwork are retained during a short crossfade. A focus debounce avoids loading artwork for every passing selection.
- At most the current and previous composed backgrounds are displayed during a short crossfade. The compositor has one worker and one pending request; obsolete results are discarded. Its worker times out after two idle seconds. A focus debounce avoids loading Plex artwork for every passing selection. Only the focused tile casts an app-colored shadow, with no duplicate parent shadow.
- No boot receiver, alarms, or PowerManager wake locks. Update checks use one brief JobScheduler job, normally daily. The optional Home override is an event-driven accessibility service in a separate process; turning it off removes that bound service. The optional DreamService runs only when Android explicitly binds it as a system screensaver.
- Clock updates once per minute; optional scene rotation runs only while Luma is visible.
- On pause, networking and scene animations are canceled. On stop, queued work, image references, and caches are cleared. Worker threads time out after ten idle seconds.
@ -115,7 +115,7 @@ The signed APK is [output/Luma.apk](output/Luma.apk). Source is in `app/src/main
The current workspace already contains a local JDK 17 and Android SDK under `.tools`. Rebuild without Gradle:
```sh
scripts/build.sh
bash scripts/build.sh
.tools/platform-tools/adb -s 192.168.50.195:35635 install -r output/Luma.apk
```
@ -140,7 +140,7 @@ python3 scripts/device_smoke.py --part screensaver-timeout
The scripts operate the TV through ADB. Run one at a time with the TV awake. The customization checks expect the documented defaults. The Plex fixture requires `python3 scripts/plex_fixture.py` running on the host, followed by `python3 scripts/device_smoke.py --part plex`. It uses temporary ADB reverse forwarding to a loopback server and disconnects the fixture when finished.
The wake regression uses a separate test APK signed with the same development key, without adding any test interface to Luma. It replays interrupted background loading, a pause/resume without another start callback, memory trimming, and five stop/start cycles. The old 1.0.0 build fails the interrupted-wake case; 1.0.1 passes.
The wake regression uses a separate test APK signed with the same development key, without adding any test interface to Luma. It replays interrupted background loading, a pause/resume without another start callback, memory trimming, and five stop/start cycles. The old 1.0.0 build fails the interrupted-wake case; 1.0.1 passes. The current test also verifies nonblank composed backgrounds, their resolution limit, and cache release on stop.
```sh
bash scripts/build-wake-tests.sh
@ -152,4 +152,6 @@ bash scripts/build-wake-tests.sh
Successful output ends with `INSTRUMENTATION_CODE: -1` and PASS lines for all cases. The runner controls activity lifecycle callbacks and should be run with no other device tests in progress.
Android force-stops the target package during instrumentation and can mark its accessibility helper as stopped/crashed. After testing, check **Settings → Default launcher** and toggle **Luma Home button** off/on in Android Accessibility if needed, then reopen Luma. This is test-runner cleanup, not an action needed during normal TV wake.
The same test APK also includes `tv.luma.launcher.tests/.PerformanceInstrumentation` for the background/shadow A/B benchmark. It changes only runtime view state and writes a temporary `performance.txt` in Luma's external-files directory. Reopen Luma afterward and remove the diagnostic APK.
See [docs/ASSETS.md](docs/ASSETS.md) for the wallpaper generation prompt and asset provenance. Android TV intent handling follows [Android's TV app guidance](https://developer.android.com/training/tv/get-started/create); Plex integration follows the [official Plex Media Server API documentation](https://developer.plex.tv/pms/).