Camera Feature Policy API

[Kimblebee]

Summary

Introduces CameraFeaturePolicy in :core:settings to allow developer options, embedding applications, and test harnesses to configure default camera settings and control UI option visibility.

This decouples the baseline camera session state (defaultValue) from Compose UI presentation (OptionVisibility), enabling controls to be shown normally, hidden entirely, or restricted to a specific whitelist of options with guaranteed domain safety and graceful fallbacks.

---

Key Changes

• Configuration & Models (core:settings):

  • Added CameraFeaturePolicy with nullable properties: captureMode, aspectRatio, flashMode, imageFormat, and dynamicRange.
  • Added generic, non-null bounded SettingConfig<T : Any>(defaultValue, visibility).
  • Defined the OptionVisibility<T : Any> sealed hierarchy:
    • OptionVisibility.Visible: All device-supported options are selectable (default).
    • OptionVisibility.Hidden: Setting is hidden/unavailable in the UI; camera runs with defaultValue.
    • OptionVisibility.Only(enabledOptions): Whitelists specific options in the UI (minimum 2 options; supports vararg construction).
    • OptionVisibility.from(options) / OptionVisibility.from(vararg options): Safe factory functions that automatically fall back to Hidden when fewer than 2 options are provided, preventing runtime crash traps during dynamic option resolution.
  • Enforced domain safety constraints:
    • defaultValue must be included in OptionVisibility.Only.
    • flashMode must default to OFF when Hidden and must include OFF when restricted.
    • Ultra HDR (JPEG_ULTRA_HDR) and HDR video (HLG10) are supported as defaults under Hidden (hardware fallbacks to SDR are handled gracefully at runtime if unsupported by the active camera).
  • Added CameraFeaturePolicy.toCameraAppSettings(defaultSettings) to map overrides cleanly over baseline settings.

• Settings Storage & Data Layer (data:settings, core:settings:datastore-prefs):

  • Updated LocalSettingsRepository and PrefsDataStoreSettingsDataSource to enforce CameraFeaturePolicy:
    • Utilizes enforceRestrictions(storedSetting, settingConfig) across all settings (captureMode, aspectRatio, flashMode, imageFormat, dynamicRange) to preserve valid user-selected preferences under OptionVisibility.Only rather than unconditionally overwriting them with defaultValue.

• Camera System Wiring (data:camera):

  • Injected CameraFeaturePolicy into CameraXCameraSystemRepository.
  • Applied CameraFeaturePolicy defaults during lazy camera initialization before use cases bind.
  • Preserved un-overridden settings from user preferences rather than hardcoded fallbacks.

• UI State & Adapters (ui:uistateadapter:capture):

  • Standardized developer restriction parameter naming to optionVisibility across all option adapters.
  • Integrated OptionVisibility policies into:
    • CaptureModeUiStateAdapter: Respects hidden capture mode, hides/disables toggle buttons or quick-settings rows appropriately, and provides clear disabled rationales. Documented the binary quick-toggle contract for CaptureModeToggleUiState (requiring 2 valid selectable states; directing custom layouts to CaptureModeUiState for disabled reasons).
    • FlashModeUiStateAdapter: Filters selectable flash modes or marks as Unavailable when hidden or unsupported.
    • AspectRatioUiStateAdapter: Restricts selectable aspect ratios and falls back deterministically to 3:4 if the currently stored selection is restricted.
    • HdrUiStateAdapter: Disables HDR options when dynamic range or image format are restricted. Fixed an issue where Low Light Boost disabled all HDR options instead of keeping "Off" selectable.
    • CaptureUiStateAdapter: Wires CameraFeaturePolicy into compound UI state generation with cameraFeaturePolicy: CameraFeaturePolicy? = null default parameter.

• Viewfinder & Quick Settings UI (feature:preview):

  • Verified quickSettingsState.value is QuickSettingsUiState.Available in isQuickSettingsVisible within PreviewScreen.kt so that the drop-down toggle button (ToggleQuickSettingsButton) is hidden whenever quick settings is Unavailable.

• Dependency Injection & App Integration (app):

  • Provided CameraFeaturePolicy via AppModule.providesCameraFeaturePolicy().
  • Added @Volatile @VisibleForTesting var testCameraFeaturePolicy: CameraFeaturePolicy? to enable isolated, deterministic device test overrides.

• Testing:

  • Unit Tests:
    • :core:settings: Comprehensive validation of CameraFeaturePolicy, SettingConfig, and OptionVisibility edge cases in CameraFeaturePolicyTest.
    • :data:camera: Verified lazy initialization and default overrides in CameraXCameraSystemRepositoryTest.
    • :data:settings: Validated preference persistence and restriction enforcement in LocalSettingsRepositoryTest.
    • :ui:uistateadapter:capture: Tested UI state adaptation, visibility restrictions, and fallback behavior across CaptureModeUiStateAdapterTest (including concurrent camera dual & HDR conflict scenarios), FlashModeUiStateAdapterTest, AspectRatioUiStateAdapterTest, HdrUiStateAdapterTest, and CaptureUiStateAdapterTest.
    • :feature:preview: Verified ViewModel integration with CameraFeaturePolicy in PreviewViewModelTest.
  • Device Instrumentation Tests (app):
    • Added end-to-end device tests validating Compose UI behavior under various CameraFeaturePolicy configurations:
      • CaptureModeFeaturePolicyDeviceTest (including photo and video capture execution)
      • FlashModeFeaturePolicyDeviceTest (including graceful fallback on devices without flash units)
      • AspectRatioFeaturePolicyDeviceTest
      • HdrFeaturePolicyDeviceTest
    • Isolated CaptureModeSettingsTest.hdr_supports_video_only() using testCameraFeaturePolicy for deterministic behavior across dual-HDR and single-HDR devices.

---

Usage Example

val policy = CameraFeaturePolicy(
    captureMode = SettingConfig(
        defaultValue = CaptureMode.IMAGE_ONLY,
        visibility = OptionVisibility.Hidden
    ),
    flashMode = SettingConfig(
        defaultValue = FlashMode.OFF,
        visibility = OptionVisibility.Only(FlashMode.OFF, FlashMode.AUTO)
    ),
    dynamicRange = SettingConfig(
        defaultValue = DynamicRange.SDR,
        visibility = OptionVisibility.Hidden
    )
)

---

Limitations & Future Work

1. Audio Configuration: audioEnabled configuration is deferred to a follow-up PR, pending visual UX design.
2. Aspect Ratio Preservation Across Mode Switches: Photo mode currently enforces 3:4 for external capture compatibility. We should consider if we want to preserve developer-configured aspect ratios (e.g., 1:1) for these scenarios.
3. Quick Settings Navigation Coordination: When all Quick Settings rows are unavailable, coordinate with onNavigateToSettings to determine whether the toggle button should navigate directly to full settings or remain hidden.

[gemini-code-assist]

Code Review

This pull request introduces a new DeveloperAppConfig API to allow overriding default camera settings and restricting UI options, which is integrated into the PreviewViewModel and navigation logic. Several issues were identified in the review: a compilation error in PreviewViewModelTest due to passing null to a non-nullable parameter, inconsistent Java toolchain versions in the new module, and incorrect test tags and string resources in the UI components. Additionally, the OptionRestrictionConfig validation was found to be overly restrictive, and a potential runtime crash was noted in the CaptureModeUiStateAdapter.