[camerax] Clarify how CameraX uses preset resolution (#6022)

Improves documentation to clarify that CameraX uses the preset resolution to target for [UseCase]s and are not guaranteed.

Fixes flutter/flutter#141766.

Author: camsim99

packages/camera/camera_android_camerax/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.5.0+30
+
+* Adds documentation to clarify how the plugin uses resolution presets as target resolutions for CameraX.
+
 ## 0.5.0+29
 
 * Modifies `buildPreview` to return `Texture` that maps to camera preview, building in the assumption

packages/camera/camera_android_camerax/lib/src/android_camera_camerax.dart

@@ -232,6 +232,12 @@ class AndroidCameraCameraX extends CameraPlatform {
   /// uninitialized camera instance, this method retrieves a
   /// [ProcessCameraProvider] instance.
   ///
+  /// The specified [resolutionPreset] is the target resolution that CameraX
+  /// will attempt to select for the [UseCase]s constructed in this method
+  /// ([preview], [imageCapture], [imageAnalysis], [videoCapture]). If
+  /// unavailable, a fallback behavior of targeting the next highest resolution
+  /// will be attempted. See https://developer.android.com/media/camera/camerax/configuration#specify-resolution.
+  ///
   /// To return the camera ID, which is equivalent to the ID of the surface texture
   /// that a camera preview can be drawn to, a [Preview] instance is configured
   /// and bound to the [ProcessCameraProvider] instance.

packages/camera/camera_android_camerax/pubspec.yaml

@@ -2,7 +2,7 @@ name: camera_android_camerax
 description: Android implementation of the camera plugin using the CameraX library.
 repository: https://github.com/flutter/packages/tree/main/packages/camera/camera_android_camerax
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22
-version: 0.5.0+29
+version: 0.5.0+30
 
 environment:
   sdk: ">=3.0.0 <4.0.0"

packages/camera/camera_platform_interface/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.7.3
+
+* Adds documentation to clarify that platform implementations of the plugin use
+  resolution presets as target resolutions.
+
 ## 2.7.2
 
 * Updates minimum required plugin_platform_interface version to 2.1.7.

packages/camera/camera_platform_interface/lib/src/types/resolution_preset.dart

@@ -4,21 +4,23 @@
 
 /// Affect the quality of video recording and image capture:
 ///
-/// If a preset is not available on the camera being used a preset of lower quality will be selected automatically.
+/// A preset is treated as a target resolution, and exact values are not
+/// guaranteed. Platform implementations may fall back to a higher or lower
+/// resolution if a specific preset is not available.
 enum ResolutionPreset {
-  /// 352x288 on iOS, 240p (320x240) on Android and Web
+  /// 352x288 on iOS, ~240p on Android and Web
   low,
 
-  /// 480p (640x480 on iOS, 720x480 on Android and Web)
+  /// ~480p
   medium,
 
-  /// 720p (1280x720)
+  /// ~720p
   high,
 
-  /// 1080p (1920x1080)
+  /// ~1080p
   veryHigh,
 
-  /// 2160p (3840x2160 on Android and iOS, 4096x2160 on Web)
+  /// ~2160p
   ultraHigh,
 
   /// The highest resolution available.

packages/camera/camera_platform_interface/pubspec.yaml

@@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/camera/camera
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+camera%22
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 2.7.2
+version: 2.7.3
 
 environment:
   sdk: ">=3.0.0 <4.0.0"