Skip to content

ADR-0006: Reconcile built-in performance-mode terminology

Status

Accepted. The fixed-mode mapping was amended on 2026-09-11. The original adaptive-default decision was superseded by the amendment dated 2026-09-24.

Date

2026-08-09

Context

ADR-0004 and ADR-0005 record the validation and adaptive-policy decisions for Blur and Glass. They predate the unified built-in HazePerformanceMode API, so they describe built-in effects with the former HazeSampling vocabulary. That vocabulary is still correct for generic custom effects, but it no longer describes the public modifiers for built-in Blur and Glass.

The historical measurements remain useful evidence for the separate Blur and Glass resolver policies. Rewriting their tables would silently alter a record of the conditions, API, and metrics that were accepted at the time.

Original decision (superseded 2026-09-24)

Built-in Blur and Glass use HazePerformanceMode; custom effects retain HazeSampling as their generic input-sampling contract.

  • HazePerformanceMode.Default is Adaptive.
  • Quality replaces the former built-in full-resolution choice.
  • Quality, Balanced, and Performance are effect-owned named profiles. Their internal resolution mappings are not a cross-effect public contract.
  • Fixed(qualityFraction) is a normalized, effect-owned override. A previous built-in fixed input-pixel fraction has no direct equivalent and must be remeasured for the effect and layout in use.
  • The adaptive resolver thresholds, cadence handling, and hysteresis recorded in ADR-0004 and ADR-0005 remain unchanged. Changing them requires fresh paired physical-device evidence and representative visual review.

At adoption, the controlled Android Macrobenchmark suite ran every named built-in performance mode for both effects under stable and rapidly changing input workloads. It recorded frame-duration CPU and frame-overrun metrics; changing Glass workloads also recorded peak memory. Release documentation summarized the device, build, refresh rate, iteration count, scenarios, and accepted metrics rather than committing raw traces or JSON reports.

Validation

The compatibility and terminology change is covered by public API compilation, effect-specific resolver tests, deterministic controlled benchmark navigation, and representative screenshot coverage. The current physical-device reference measurements are recorded in the Blur and Glass performance guidance; raw Macrobenchmark artifacts remain local build outputs.

Consequences

  • Existing callers can choose a stable named profile without knowing a renderer's input-pixel calculation.
  • Existing custom effects keep their explicit HazeSampling behavior.
  • Documentation and migration guidance distinguish the two contracts and require remeasurement instead of presenting a speculative fixed-fraction conversion.
  • ADR-0004 and ADR-0005 retain their historical evidence and implementation-policy decisions, but their built-in public-API terminology is superseded by this ADR.

Amendment: continuous fixed quality (2026-09-11; superseded for built-in defaults below)

Fixed(qualityFraction) now interpolates the total input pixel fraction between the supported minimum and full resolution, replacing the three-bucket fixed selector above. The minimum is an internal implementation value, not a documented numeric guarantee. Interpolation is linear in total input pixels, rather than each dimension. The public name and finite 0f..1f validation remain unchanged. Renderer resource limits and whole-pixel rounding still apply.

Quality = Fixed(1f) and Performance = Fixed(0f) retain their previous scales. Balanced = Fixed(0.5f) requests the midpoint between minimum and full-resolution pixel counts. Adaptive retains its previous scales, workload thresholds, cadence handling, and hysteresis; its tiers are resolved independently from fixed quality.

The implementation preserves the existing minimum fixed resolution. It is not a newly measured visual quality threshold. Fresh paired visual and performance testing remains necessary before changing Adaptive's default behavior. Earlier benchmark tables describe the old fixed profiles and must not be interpreted as measurements of this new mapping.

Amendment: fixed built-in defaults (2026-09-24)

Built-in Blur and Glass now use the fixed Balanced profile through HazePerformanceMode.Default. HazePerformanceMode.Adaptive remains deprecated for binary compatibility and resolves exactly like Default. The cadence, workload thresholds, hysteresis, and adaptive tiers described above have been removed from built-in production rendering. HazeInputUpdateCadence has also been removed. HazeSampling.Adaptive remains unchanged for custom effects.

The prior built-in adaptive policy could not be supported as a technically reliable cross-effect contract. The public compatibility object therefore no longer promises adaptation. ADR-0004 and ADR-0005 remain the historical rationale and evidence for the removed policies. Their captured measurements and the earlier benchmark tables are preserved as history; active benchmark scenarios and current guidance cover fixed modes only. This change does not add new physical-device benchmark evidence.

References