Skip to content

[camera_android_camerax] Improve documentation on cameraId parameter #10844

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
auto-submit merged 2 commits into from
Jan 28, 2026
Merged

[camera_android_camerax] Improve documentation on cameraId parameter #10844

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c9ff8b5
clarify cameraId
camsim99 Jan 21, 2026
709a504
Update android_camera_camerax.dart
camsim99 Jan 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 38 additions & 58 deletions packages/camera/camera_android_camerax/lib/src/android_camera_camerax.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ class AndroidCameraCameraX extends CameraPlatform {
final StreamController<CameraEvent> cameraEventStreamController =
StreamController<CameraEvent>.broadcast();

/// The stream of camera events.
/// The stream of camera events for the camera with ID cameraId.
Stream<CameraEvent> _cameraEvents(int cameraId) => cameraEventStreamController
.stream
.where((CameraEvent event) => event.cameraId == cameraId);
Expand Down Expand Up @@ -449,7 +449,7 @@ class AndroidCameraCameraX extends CameraPlatform {
return _flutterSurfaceTextureId;
}

/// Initializes the camera on the device.
/// Initializes the camera with ID [cameraId] on the device.
///
/// Specifically, this method:
/// * Configures the [ImageAnalysis] instance according to the specified
Expand Down Expand Up @@ -523,9 +523,7 @@ class AndroidCameraCameraX extends CameraPlatform {
);
}

/// Releases the resources of the accessed camera.
///
/// [cameraId] not used.
/// Releases the resources of the accessed camera with ID [cameraId].
@override
Future<void> dispose(int cameraId) async {
await preview?.releaseSurfaceProvider();
Expand All @@ -535,27 +533,27 @@ class AndroidCameraCameraX extends CameraPlatform {
await deviceOrientationManager.stopListeningForDeviceOrientationChange();
}

/// The camera has been initialized.
/// The camera with ID [cameraId] has been initialized.
@override
Stream<CameraInitializedEvent> onCameraInitialized(int cameraId) {
return _cameraEvents(cameraId).whereType<CameraInitializedEvent>();
}

/// The camera's resolution has changed.
/// The resolution of camera with ID [cameraId] has changed.
///
/// This stream currently has no events being added to it from this plugin.
@override
Stream<CameraResolutionChangedEvent> onCameraResolutionChanged(int cameraId) {
return _cameraEvents(cameraId).whereType<CameraResolutionChangedEvent>();
}

/// The camera started to close.
/// The camera with ID [cameraId] has started to close.
@override
Stream<CameraClosingEvent> onCameraClosing(int cameraId) {
return _cameraEvents(cameraId).whereType<CameraClosingEvent>();
}

/// The camera experienced an error.
/// The camera with ID [cameraId] experienced an error.
@override
Stream<CameraErrorEvent> onCameraError(int cameraId) {
return StreamGroup.mergeBroadcast<CameraErrorEvent>(
Expand All @@ -570,13 +568,13 @@ class AndroidCameraCameraX extends CameraPlatform {
);
}

/// The camera finished recording a video.
/// The camera with ID [cameraId] finished recording a video.
@override
Stream<VideoRecordedEvent> onVideoRecordedEvent(int cameraId) {
return _cameraEvents(cameraId).whereType<VideoRecordedEvent>();
}

/// Locks the capture orientation.
/// Locks the capture orientation of camera with ID [cameraId].
@override
Future<void> lockCaptureOrientation(
int cameraId,
Expand All @@ -599,22 +597,21 @@ class AndroidCameraCameraX extends CameraPlatform {
await videoCapture!.setTargetRotation(targetLockedRotation);
}

/// Unlocks the capture orientation.
/// Unlocks the capture orientation of camera with ID [cameraId].
@override
Future<void> unlockCaptureOrientation(int cameraId) async {
// Flag that default rotation should be set for UseCases as needed.
captureOrientationLocked = false;
}

/// Sets the exposure point for automatically determining the exposure values.
/// Sets the exposure point for automatically determining the exposure values for
/// camera with ID [cameraId].
///
/// Supplying `null` for the [point] argument will result in resetting to the
/// original exposure point value.
///
/// Supplied non-null point must be mapped to the entire un-altered preview
/// surface for the exposure point to be applied accurately.
///
/// [cameraId] is not used.
@override
Future<void> setExposurePoint(int cameraId, Point<double>? point) async {
// We lock the new focus and metering action if focus mode has been locked
Expand All @@ -629,27 +626,23 @@ class AndroidCameraCameraX extends CameraPlatform {
);
}

/// Gets the minimum supported exposure offset for the selected camera in EV units.
///
/// [cameraId] not used.
/// Gets the minimum supported exposure offset for the camera with ID [cameraId] in EV units.
@override
Future<double> getMinExposureOffset(int cameraId) async {
final ExposureState exposureState = cameraInfo!.exposureState;
return exposureState.exposureCompensationRange.lower *
exposureState.exposureCompensationStep;
}

/// Gets the maximum supported exposure offset for the selected camera in EV units.
///
/// [cameraId] not used.
/// Gets the maximum supported exposure offset for the camera with ID [cameraId] in EV units.
@override
Future<double> getMaxExposureOffset(int cameraId) async {
final ExposureState exposureState = cameraInfo!.exposureState;
return exposureState.exposureCompensationRange.upper *
exposureState.exposureCompensationStep;
}

/// Sets the focus mode for taking pictures.
/// Sets the focus mode for taking pictures with camera with ID [cameraId]
///
/// Setting [FocusMode.locked] will lock the current focus point if one exists
/// or the center of entire sensor area if not, and will stay locked until
Expand Down Expand Up @@ -730,11 +723,9 @@ class AndroidCameraCameraX extends CameraPlatform {
}
}

/// Gets the supported step size for exposure offset for the selected camera in EV units.
/// Gets the supported step size for exposure offset for the camera with ID [cameraId] in EV units.
///
/// Returns -1 if exposure compensation is not supported for the device.
///
/// [cameraId] not used.
@override
Future<double> getExposureOffsetStepSize(int cameraId) async {
final ExposureState exposureState = cameraInfo!.exposureState;
Expand All @@ -748,7 +739,7 @@ class AndroidCameraCameraX extends CameraPlatform {
return exposureOffsetStepSize;
}

/// Sets the exposure offset for the selected camera.
/// Sets the exposure offset for the camera with ID [cameraId].
///
/// The supplied [offset] value should be in EV units. 1 EV unit represents a
/// doubling in brightness. It should be between the minimum and maximum offsets
Expand Down Expand Up @@ -807,15 +798,14 @@ class AndroidCameraCameraX extends CameraPlatform {
}
}

/// Sets the focus point for automatically determining the focus values.
/// Sets the focus point for automatically determining the focus values for the
/// camera with ID [cameraId].
///
/// Supplying `null` for the [point] argument will result in resetting to the
/// original focus point value.
///
/// Supplied non-null point must be mapped to the entire un-altered preview
/// surface for the focus point to be applied accurately.
///
/// [cameraId] is not used.
@override
Future<void> setFocusPoint(int cameraId, Point<double>? point) async {
// We lock the new focus and metering action if focus mode has been locked
Expand All @@ -830,12 +820,10 @@ class AndroidCameraCameraX extends CameraPlatform {
);
}

/// Sets the exposure mode for taking pictures.
/// Sets the exposure mode for taking pictures with the camera with ID [cameraId].
///
/// Setting [ExposureMode.locked] will lock current exposure point until it
/// is unset by setting [ExposureMode.auto].
///
/// [cameraId] is not used.
@override
Future<void> setExposureMode(int cameraId, ExposureMode mode) async {
final camera2Control = Camera2CameraControl.from(
Expand All @@ -861,9 +849,7 @@ class AndroidCameraCameraX extends CameraPlatform {
_currentExposureMode = mode;
}

/// Gets the maximum supported zoom level for the selected camera.
///
/// [cameraId] not used.
/// Gets the maximum supported zoom level for the camera with ID [cameraId].
@override
Future<double> getMaxZoomLevel(int cameraId) async {
final LiveData<ZoomState> liveZoomState = await cameraInfo!.getZoomState();
Expand All @@ -878,9 +864,7 @@ class AndroidCameraCameraX extends CameraPlatform {
return zoomState.maxZoomRatio;
}

/// Gets the minimum supported zoom level for the selected camera.
///
/// [cameraId] not used.
/// Gets the minimum supported zoom level for the camera with ID [cameraId].
@override
Future<double> getMinZoomLevel(int cameraId) async {
final LiveData<ZoomState> liveZoomState = await cameraInfo!.getZoomState();
Expand All @@ -895,7 +879,7 @@ class AndroidCameraCameraX extends CameraPlatform {
return zoomState.minZoomRatio;
}

/// Set the zoom level for the selected camera.
/// Set the zoom level for the camera with ID [cameraId].
///
/// The supplied [zoom] value should be between the minimum and the maximum
/// supported zoom level returned by [getMinZoomLevel] and [getMaxZoomLevel].
Expand All @@ -918,9 +902,7 @@ class AndroidCameraCameraX extends CameraPlatform {
return deviceOrientationChangedStreamController.stream;
}

/// Pause the active preview on the current frame for the selected camera.
///
/// [cameraId] not used.
/// Pause the active preview on the current frame for the camera with ID [cameraId].
@override
Future<void> pausePreview(int cameraId) async {
_previewIsPaused = true;
Expand Down Expand Up @@ -975,18 +957,17 @@ class AndroidCameraCameraX extends CameraPlatform {
await _updateCameraInfoAndLiveCameraState(_flutterSurfaceTextureId);
}

/// Resume the paused preview for the selected camera.
///
/// [cameraId] not used.
/// Resume the paused preview for the camera with ID [cameraId].
@override
Future<void> resumePreview(int cameraId) async {
_previewIsPaused = false;
await _bindUseCaseToLifecycle(preview!, cameraId);
}

/// Returns a widget showing a live camera preview.
/// Returns a widget showing a live camera preview for the camera with ID [cameraId].
///
/// [createCamera] must be called before attempting to build this preview.
/// [createCamera] must be called before attempting to build this preview, and
/// [cameraId] can be retrieved from that call.
@override
Widget buildPreview(int cameraId) {
if (!previewInitiallyBound) {
Expand Down Expand Up @@ -1017,9 +998,7 @@ class AndroidCameraCameraX extends CameraPlatform {
);
}

/// Captures an image and returns the file where it was saved.
///
/// [cameraId] is not used.
/// Captures an image using the camera with ID [cameraId] and returns the file where it was saved.
@override
Future<XFile> takePicture(int cameraId) async {
await _bindUseCaseToLifecycle(imageCapture!, cameraId);
Expand All @@ -1044,7 +1023,7 @@ class AndroidCameraCameraX extends CameraPlatform {
return XFile(picturePath);
}

/// Sets the flash mode for the selected camera.
/// Sets the flash mode for the camera with ID [cameraId].
///
/// When the [FlashMode.torch] is enabled, any previously set [FlashMode] with
/// this method will be disabled, just as with any other [FlashMode]; while
Expand Down Expand Up @@ -1092,8 +1071,9 @@ class AndroidCameraCameraX extends CameraPlatform {
return Future<void>.value();
}

/// Configures and starts a video recording. Returns silently without doing
/// anything if there is currently an active recording.
/// Configures and starts a video recording with the camera with ID [cameraId].
/// Returns silently without doing anything if there is currently an active
/// recording.
///
/// Note that the preset resolution is used to configure the recording, but
/// 240p ([ResolutionPreset.low]) is unsupported and will fallback to
Expand Down Expand Up @@ -1246,15 +1226,15 @@ class AndroidCameraCameraX extends CameraPlatform {
return videoFile;
}

/// Pause the current video recording if it is not null.
/// Pause the current video recording of the camera with ID [cameraId] if it is not null.
@override
Future<void> pauseVideoRecording(int cameraId) async {
if (recording != null) {
await recording!.pause();
}
}

/// Resume the current video recording if it is not null.
/// Resume the current video recording of the camera with ID [cameraId] if it is not null.
@override
Future<void> resumeVideoRecording(int cameraId) async {
if (recording != null) {
Expand All @@ -1265,7 +1245,7 @@ class AndroidCameraCameraX extends CameraPlatform {
@override
bool supportsImageStreaming() => true;

/// A new streamed frame is available.
/// A new streamed frame is available from the camera with ID [cameraId].
///
/// Listening to this stream will start streaming, and canceling will stop.
/// To temporarily stop receiving frames, cancel, then listen again later.
Expand All @@ -1278,7 +1258,7 @@ class AndroidCameraCameraX extends CameraPlatform {
/// streamed images will still have format [ImageFormatGroup.yuv420], but
/// their image data will be formatted in NV21.
///
/// [cameraId] and [options] are not used.
/// [options] are not used.
@override
Stream<CameraImageData> onStreamedFrameAvailable(
int cameraId, {
Expand All @@ -1299,7 +1279,7 @@ class AndroidCameraCameraX extends CameraPlatform {
///
/// [cameraId] used to build [CameraEvent]s should you wish to filter
/// these based on a reference to a cameraId received from calling
/// `createCamera(...)`.
/// [createCamera].
Future<void> _bindUseCaseToLifecycle(UseCase useCase, int cameraId) async {
final bool useCaseIsBound = await processCameraProvider!.isBound(useCase);
final bool useCaseIsPausedPreview = useCase is Preview && _previewIsPaused;
Expand Down
Loading