Merge "Update CameraController document." into androidx-main
diff --git a/camera/camera-view/src/main/java/androidx/camera/view/CameraController.java b/camera/camera-view/src/main/java/androidx/camera/view/CameraController.java
index d9e25a4..a06b39d 100644
--- a/camera/camera-view/src/main/java/androidx/camera/view/CameraController.java
+++ b/camera/camera-view/src/main/java/androidx/camera/view/CameraController.java
@@ -125,13 +125,13 @@
* tap-to-focus and pinch-to-zoom features.
*
* <p> This class provides features of 4 {@link UseCase}s: {@link Preview}, {@link ImageCapture},
- * {@link ImageAnalysis} and an experimental video capture. {@link Preview} is required and always
- * enabled. {@link ImageCapture} and {@link ImageAnalysis} are enabled by default. The video
- * capture feature is experimental. It's disabled by default because it might conflict with other
- * use cases, especially on lower end devices. It might be necessary to disable {@link ImageCapture}
- * and/or {@link ImageAnalysis} before the video capture feature can be enabled. Disabling/enabling
- * {@link UseCase}s freezes the preview for a short period of time. To avoid the glitch, the
- * {@link UseCase}s need to be enabled/disabled before the controller is set on {@link PreviewView}.
+ * {@link ImageAnalysis} and {@link VideoCapture}. {@link Preview} is required and always enabled.
+ * {@link ImageCapture} and {@link ImageAnalysis} are enabled by default. The video capture is
+ * disabled by default because it might affect other use cases, especially on lower end devices.
+ * It might be necessary to disable {@link ImageCapture} and/or {@link ImageAnalysis} before the
+ * video capture feature can be enabled. Disabling/enabling {@link UseCase}s freezes the preview for
+ * a short period of time. To avoid the glitch, the {@link UseCase}s need to be enabled/disabled
+ * before the controller is set on {@link PreviewView}.
*/
public abstract class CameraController {
@@ -210,17 +210,20 @@
/**
* Bitmask option to enable {@link ImageCapture}. In {@link #setEnabledUseCases}, if
- * (enabledUseCases & IMAGE_CAPTURE) != 0, then controller will enable image capture features.
+ * {@code (enabledUseCases & IMAGE_CAPTURE) != 0}, then controller will enable image capture
+ * features.
*/
public static final int IMAGE_CAPTURE = 1;
/**
* Bitmask option to enable {@link ImageAnalysis}. In {@link #setEnabledUseCases}, if
- * (enabledUseCases & IMAGE_ANALYSIS) != 0, then controller will enable image analysis features.
+ * {@code (enabledUseCases & IMAGE_ANALYSIS) != 0}, then controller will enable image
+ * analysis features.
*/
public static final int IMAGE_ANALYSIS = 1 << 1;
/**
* Bitmask option to enable video capture use case. In {@link #setEnabledUseCases}, if
- * (enabledUseCases & VIDEO_CAPTURE) != 0, then controller will enable video capture features.
+ * {@code (enabledUseCases & VIDEO_CAPTURE) != 0}, then controller will enable video capture
+ * features.
*/
public static final int VIDEO_CAPTURE = 1 << 2;
@@ -403,16 +406,16 @@
/**
* Gets a {@link ListenableFuture} that completes when camera initialization completes.
*
- * <p> This future may fail with an {@link InitializationException} and associated cause that
+ * <p>This future may fail with an {@link InitializationException} and associated cause that
* can be retrieved by {@link Throwable#getCause()}. The cause will be a
* {@link CameraUnavailableException} if it fails to access any camera during initialization.
*
- * <p> In the rare case that the future fails with {@link CameraUnavailableException}, the
+ * <p>In the rare case that the future fails with {@link CameraUnavailableException}, the
* camera will become unusable. This could happen for various reasons, for example hardware
* failure or the camera being held by another process. If the failure is temporary, killing
* and restarting the app might fix the issue.
*
- * <p> The initialization also try to bind use cases before completing the
+ * <p>The initialization also try to bind use cases before completing the
* {@link ListenableFuture}. The {@link ListenableFuture} will complete successfully
* regardless of whether the use cases are ready to be bound, e.g. it will complete
* successfully even if the controller is not set on a {@link PreviewView}. However the
@@ -429,8 +432,8 @@
/**
* Implemented by children to refresh after {@link UseCase} is changed.
*
- * @throws IllegalStateException for invalid {@link UseCase} combinations.
- * @throws RuntimeException for invalid {@link CameraEffect} combinations.
+ * @throws IllegalStateException For invalid {@link UseCase} combinations.
+ * @throws RuntimeException For invalid {@link CameraEffect} combinations.
*/
@Nullable
abstract Camera startCamera();
@@ -450,15 +453,13 @@
/**
* Enables or disables use cases.
*
- * <p> Use cases need to be enabled before they can be used. By default, {@link #IMAGE_CAPTURE}
+ * <p>Use cases need to be enabled before they can be used. By default, {@link #IMAGE_CAPTURE}
* and {@link #IMAGE_ANALYSIS} are enabled, and {@link #VIDEO_CAPTURE} is disabled. This is
- * necessary because {@link #VIDEO_CAPTURE} is an experimental feature that might not work
- * with other use cases, especially on lower end devices. When that happens, this method will
- * fail with an {@link IllegalStateException}.
+ * necessary because {@link #VIDEO_CAPTURE} may affect the available resolutions for other use
+ * cases, especially on lower end devices.
*
- * <p> To make sure {@link #VIDEO_CAPTURE} works, {@link #IMAGE_CAPTURE} and
- * {@link #IMAGE_ANALYSIS} needs to be disabled when enabling {@link #VIDEO_CAPTURE}. For
- * example:
+ * <p>To make sure getting the maximum resolution, only enable {@link #VIDEO_CAPTURE} when
+ * shooting video. For example:
*
* <pre><code>
* // By default, image capture is enabled. Taking picture works.
@@ -475,10 +476,9 @@
* </code></pre>
*
* @param enabledUseCases one or more of the following use cases, bitwise-OR-ed together:
- * {@link #IMAGE_CAPTURE}, {@link #IMAGE_ANALYSIS} and/or
- * {@link #VIDEO_CAPTURE}.
- * @throws IllegalStateException If the current camera selector is unable to resolve a
- * camera to be used for the enabled use cases.
+ * {@link #IMAGE_CAPTURE}, {@link #IMAGE_ANALYSIS} and/or {@link #VIDEO_CAPTURE}.
+ * @throws IllegalStateException If the current camera selector is unable to resolve a camera
+ * to be used for the enabled use cases.
* @see UseCase
* @see ImageCapture
* @see ImageAnalysis
@@ -501,8 +501,8 @@
* Checks if the given use case mask is enabled.
*
* @param useCaseMask One of the {@link #IMAGE_CAPTURE}, {@link #IMAGE_ANALYSIS} or
- * {@link #VIDEO_CAPTURE}
- * @return true if the use case is enabled.
+ * {@link #VIDEO_CAPTURE}.
+ * @return {@code true} if the use case is enabled.
*/
private boolean isUseCaseEnabled(int useCaseMask) {
return (mEnabledUseCases & useCaseMask) != 0;
@@ -591,7 +591,7 @@
}
/**
- * Clear {@link PreviewView} to remove the UI reference.
+ * Clears {@link PreviewView} to remove the UI reference.
*/
@MainThread
void clearPreviewSurface() {
@@ -619,13 +619,14 @@
/**
* Sets the intended output size for {@link Preview}.
*
- * <p> The value is used as a hint when determining the resolution and aspect ratio of the
+ * <p>The value is used as a hint when determining the resolution and aspect ratio of the
* preview. The actual output may differ from the requested value due to device constraints.
*
- * <p> When set to null, the output will be based on the default config of {@link Preview}.
+ * <p>When set to {@code null}, the output will be based on the default config of
+ * {@link Preview}.
*
- * <p> Changing the value will reconfigure the camera which will cause additional latency.
- * To avoid this, set the value before controller is bound to lifecycle.
+ * <p>Changing the value will reconfigure the camera which will cause additional latency. To
+ * avoid this, set the value before controller is bound to lifecycle.
*
* @param targetSize the intended output size for {@link Preview}.
* @see Preview.Builder#setTargetAspectRatio(int)
@@ -646,7 +647,7 @@
/**
* Returns the intended output size for {@link Preview} set by
- * {@link #setPreviewTargetSize(OutputSize)}, or null if not set.
+ * {@link #setPreviewTargetSize(OutputSize)}, or {@code null} if not set.
*
* @deprecated Use {@link #getPreviewResolutionSelector()} instead.
*/
@@ -662,10 +663,10 @@
* Sets the {@link ResolutionSelector} for {@link Preview}.
*
* <p>CameraX uses this value as a hint to select the resolution for preview. The actual
- * output may differ from the requested value due to device constraints. When set to null,
- * CameraX will use the default config of {@link Preview}. By default, the selected resolution
- * will be limited by the {@code PREVIEW} size which is defined as the best size match to the
- * device's screen resolution, or to 1080p (1920x1080), whichever is smaller.
+ * output may differ from the requested value due to device constraints. When set to
+ * {@code null}, CameraX will use the default config of {@link Preview}. By default, the
+ * selected resolution will be limited by the {@code PREVIEW} size which is defined as the best
+ * size match to the device's screen resolution, or to 1080p (1920x1080), whichever is smaller.
*
* <p>Changing the value will reconfigure the camera which will cause additional latency. To
* avoid this, set the value before controller is bound to lifecycle.
@@ -704,7 +705,7 @@
* are displayed on a display. Some dynamic ranges will allow the preview to make full use of
* the extended range of brightness of a display.
*
- * <p> The supported dynamic ranges of the camera can be queried using
+ * <p>The supported dynamic ranges of the camera can be queried using
* {@link CameraInfo#querySupportedDynamicRanges(Set)}.
*
* <p>It is possible to choose a high dynamic range (HDR) with unspecified encoding by providing
@@ -765,7 +766,7 @@
/**
* Checks if {@link ImageCapture} is enabled.
*
- * <p> {@link ImageCapture} is enabled by default. It has to be enabled before
+ * <p>{@link ImageCapture} is enabled by default. It has to be enabled before
* {@link #takePicture} can be called.
*
* @see ImageCapture
@@ -804,8 +805,8 @@
* still set). Otherwise, {@code FLASH_MODE_OFF} will be set.
*
* @param flashMode the flash mode for {@link ImageCapture}.
- * @throws IllegalArgumentException If flash mode is invalid or FLASH_MODE_SCREEN is used
- * without a front camera.
+ * @throws IllegalArgumentException If flash mode is invalid or
+ * {@link ImageCapture#FLASH_MODE_SCREEN} is used without a front camera.
* @see PreviewView#setScreenFlashWindow(Window)
* @see ScreenFlashView#setScreenFlashWindow(Window)
*/
@@ -866,9 +867,10 @@
* Returns a {@link ScreenFlashUiInfo} by prioritizing {@link ScreenFlashView} over
* {@link PreviewView}.
*
- * <p> PreviewView always has a ScreenFlashView internally and does not know if user is
- * using another ScreenFlashView themselves. This API prioritizes user's ScreenFlashView over
- * the internal one in PreviewView and provides the ScreenFlashUiInfo accordingly.
+ * <p>{@link PreviewView} always has a {@link ScreenFlashView} internally and does not know
+ * if user is using another {@link ScreenFlashView} themselves. This API prioritizes user's
+ * {@link ScreenFlashView} over the internal one in {@link PreviewView} and provides the
+ * {@link ScreenFlashUiInfo} accordingly.
*/
@Nullable
@RestrictTo(RestrictTo.Scope.LIBRARY)
@@ -897,14 +899,13 @@
* {@link PreviewView}'s aspect ratio matches the max JPEG resolution supported by the camera.
*
* @param outputFileOptions Options to store the newly captured image.
- * @param executor The executor in which the callback methods will be run.
+ * @param executor The executor in which the callback methods will be run.
* @param imageSavedCallback Callback to be called for the newly captured image.
* @throws IllegalStateException If {@link ImageCapture#FLASH_MODE_SCREEN} is set to the
- * {@link CameraController}, but a non-null {@link Window}
- * instance has not been set with
- * {@link PreviewView#setScreenFlashWindow}.
+ * {@link CameraController}, but a non-null {@link Window} instance has not been set with
+ * {@link PreviewView#setScreenFlashWindow}.
* @see ImageCapture#takePicture(
- *ImageCapture.OutputFileOptions, Executor, ImageCapture.OnImageSavedCallback)
+ * ImageCapture.OutputFileOptions, Executor, ImageCapture.OnImageSavedCallback)
*/
@MainThread
public void takePicture(
@@ -922,9 +923,9 @@
}
/**
- * Update {@link ImageCapture.OutputFileOptions} based on config.
+ * Updates {@link ImageCapture.OutputFileOptions} based on config.
*
- * <p> Mirror the output image if front camera is used and if the flag is not set explicitly by
+ * <p>Mirror the output image if front camera is used and if the flag is not set explicitly by
* the app.
*/
@VisibleForTesting
@@ -946,9 +947,8 @@
* @param executor The executor in which the callback methods will be run.
* @param callback Callback to be invoked for the newly captured image
* @throws IllegalStateException If {@link ImageCapture#FLASH_MODE_SCREEN} is set to the
- * {@link CameraController}, but a non-null {@link Window}
- * instance has not been set with
- * {@link PreviewView#setScreenFlashWindow}.
+ * {@link CameraController}, but a non-null {@link Window} instance has not been set with
+ * {@link PreviewView#setScreenFlashWindow}.
* @see ImageCapture#takePicture(Executor, ImageCapture.OnImageCapturedCallback)
*/
@MainThread
@@ -983,10 +983,10 @@
* {@link ImageCapture.CaptureMode#CAPTURE_MODE_MAXIMIZE_QUALITY},
* which prioritizes image quality over latency.
*
- * <p> Changing the value will reconfigure the camera which will cause additional latency.
- * To avoid this, set the value before controller is bound to lifecycle.
+ * <p>Changing the value will reconfigure the camera which will cause additional latency. To
+ * avoid this, set the value before controller is bound to lifecycle.
*
- * @param captureMode the requested image capture mode.
+ * @param captureMode The requested image capture mode.
*/
@MainThread
public void setImageCaptureMode(@ImageCapture.CaptureMode int captureMode) {
@@ -1012,16 +1012,17 @@
/**
* Sets the intended image size for {@link ImageCapture}.
*
- * <p> The value is used as a hint when determining the resolution and aspect ratio of
- * the captured image. The actual output may differ from the requested value due to device
+ * <p>The value is used as a hint when determining the resolution and aspect ratio of the
+ * captured image. The actual output may differ from the requested value due to device
* constraints.
*
- * <p> When set to null, the output will be based on the default config of {@link ImageCapture}.
+ * <p>When set to {@code null}, the output will be based on the default config of
+ * {@link ImageCapture}.
*
- * <p> Changing the value will reconfigure the camera which will cause additional latency.
- * To avoid this, set the value before controller is bound to lifecycle.
+ * <p>Changing the value will reconfigure the camera which will cause additional latency. To
+ * avoid this, set the value before controller is bound to lifecycle.
*
- * @param targetSize the intended image size for {@link ImageCapture}.
+ * @param targetSize The intended image size for {@link ImageCapture}.
* @deprecated Use {@link #setImageCaptureResolutionSelector(ResolutionSelector)} instead.
*/
@MainThread
@@ -1038,7 +1039,7 @@
/**
* Returns the intended output size for {@link ImageCapture} set by
- * {@link #setImageCaptureTargetSize(OutputSize)}, or null if not set.
+ * {@link #setImageCaptureTargetSize(OutputSize)}, or {@code null} if not set.
*
* @deprecated Use {@link #getImageCaptureResolutionSelector()} instead.
*/
@@ -1054,10 +1055,11 @@
* Sets the {@link ResolutionSelector} for {@link ImageCapture}.
*
* <p>CameraX uses this value as a hint to select the resolution for captured images. The actual
- * output may differ from the requested value due to device constraints. When set to null,
- * CameraX will use the default config of {@link ImageCapture}. The default resolution
- * strategy for ImageCapture is {@link ResolutionStrategy#HIGHEST_AVAILABLE_STRATEGY}, which
- * will select the largest available resolution to use.
+ * output may differ from the requested value due to device constraints. When set to
+ * {@code null}, CameraX will use the default config of {@link ImageCapture}. The default
+ * resolution strategy for ImageCapture is
+ * {@link ResolutionStrategy#HIGHEST_AVAILABLE_STRATEGY}, which will select the largest
+ * available resolution to use.
*
* <p>Changing the value will reconfigure the camera which will cause additional latency. To
* avoid this, set the value before controller is bound to lifecycle.
@@ -1092,12 +1094,12 @@
/**
* Sets the default executor that will be used for {@link ImageCapture} IO tasks.
*
- * <p> This executor will be used for any IO tasks specifically for {@link ImageCapture},
+ * <p>This executor will be used for any IO tasks specifically for {@link ImageCapture},
* such as {@link #takePicture(ImageCapture.OutputFileOptions, Executor,
* ImageCapture.OnImageSavedCallback)}. If no executor is set, then a default Executor
* specifically for IO will be used instead.
*
- * <p> Changing the value will reconfigure the camera which will cause additional latency.
+ * <p>Changing the value will reconfigure the camera which will cause additional latency.
* To avoid this, set the value before controller is bound to lifecycle.
*
* @param executor The executor which will be used for IO tasks.
@@ -1180,12 +1182,12 @@
* coordinates from the {@link ImageAnalysis}'s coordinate system to the {@link PreviewView}'s
* coordinate system.
*
- * <p> If the {@link ImageAnalysis.Analyzer#getDefaultTargetResolution()} returns a non-null
+ * <p>If the {@link ImageAnalysis.Analyzer#getDefaultTargetResolution()} returns a non-null
* value, calling this method will reconfigure the camera which might cause additional
* latency. To avoid this, set the value before controller is bound to the lifecycle.
*
* @param executor The executor in which the
- * {@link ImageAnalysis.Analyzer#analyze(ImageProxy)} will be run.
+ * {@link ImageAnalysis.Analyzer#analyze(ImageProxy)} will be run.
* @param analyzer of the images.
* @see ImageAnalysis#setAnalyzer(Executor, ImageAnalysis.Analyzer)
*/
@@ -1208,7 +1210,7 @@
*
* <p>This will stop data from streaming to the {@link ImageAnalysis}.
*
- * <p> If the current {@link ImageAnalysis.Analyzer#getDefaultTargetResolution()} returns
+ * <p>If the current {@link ImageAnalysis.Analyzer#getDefaultTargetResolution()} returns
* non-null value, calling this method will reconfigure the camera which might cause additional
* latency. To avoid this, call this method when the lifecycle is not active.
*
@@ -1242,7 +1244,7 @@
/**
* Returns the mode with which images are acquired.
*
- * <p> If not set, it defaults to {@link ImageAnalysis#STRATEGY_KEEP_ONLY_LATEST}.
+ * <p>If not set, it defaults to {@link ImageAnalysis#STRATEGY_KEEP_ONLY_LATEST}.
*
* @return The backpressure strategy applied to the image producer.
* @see ImageAnalysis.Builder#getBackpressureStrategy()
@@ -1262,7 +1264,7 @@
* {@link ImageAnalysis#STRATEGY_KEEP_ONLY_LATEST}. If not set, the backpressure strategy
* will default to {@link ImageAnalysis#STRATEGY_KEEP_ONLY_LATEST}.
*
- * <p> Changing the value will reconfigure the camera which will cause additional latency. To
+ * <p>Changing the value will reconfigure the camera which will cause additional latency. To
* avoid this, set the value before controller is bound to lifecycle.
*
* @param strategy The strategy to use.
@@ -1284,11 +1286,11 @@
/**
* Sets the image queue depth of {@link ImageAnalysis}.
*
- * <p> This sets the number of images available in parallel to {@link ImageAnalysis.Analyzer}
- * . The value is only used if the backpressure strategy is
+ * <p>This sets the number of images available in parallel to {@link ImageAnalysis.Analyzer}.
+ * The value is only used if the backpressure strategy is
* {@link ImageAnalysis.BackpressureStrategy#STRATEGY_BLOCK_PRODUCER}.
*
- * <p> Changing the value will reconfigure the camera which will cause additional latency. To
+ * <p>Changing the value will reconfigure the camera which will cause additional latency. To
* avoid this, set the value before controller is bound to lifecycle.
*
* @param depth The total number of images available.
@@ -1319,17 +1321,17 @@
/**
* Sets the intended output size for {@link ImageAnalysis}.
*
- * <p> The value is used as a hint when determining the resolution and aspect ratio of
+ * <p>The value is used as a hint when determining the resolution and aspect ratio of
* the output buffer. The actual output may differ from the requested value due to device
* constraints.
*
- * <p> When set to null, the output will be based on the default config of
+ * <p>When set to {@code null}, the output will be based on the default config of
* {@link ImageAnalysis}.
*
- * <p> Changing the value will reconfigure the camera which will cause additional latency.
+ * <p>Changing the value will reconfigure the camera which will cause additional latency.
* To avoid this, set the value before controller is bound to lifecycle.
*
- * @param targetSize the intended output size for {@link ImageAnalysis}.
+ * @param targetSize The intended output size for {@link ImageAnalysis}.
* @see ImageAnalysis.Builder#setTargetAspectRatio(int)
* @see ImageAnalysis.Builder#setTargetResolution(Size)
* @deprecated Use {@link #setImageAnalysisResolutionSelector(ResolutionSelector)} instead.
@@ -1351,7 +1353,7 @@
/**
* Returns the intended output size for {@link ImageAnalysis} set by
- * {@link #setImageAnalysisTargetSize(OutputSize)}, or null if not set.
+ * {@link #setImageAnalysisTargetSize(OutputSize)}, or {@code null} if not set.
*
* @deprecated Use {@link #getImageAnalysisResolutionSelector()} instead.
*/
@@ -1367,9 +1369,9 @@
* Sets the {@link ResolutionSelector} for {@link ImageAnalysis}.
*
* <p>CameraX uses this value as a hint to select the resolution for images. The actual
- * output may differ from the requested value due to device constraints. When set to null,
- * CameraX will use the default config of {@link ImageAnalysis}. ImageAnalysis has a default
- * {@link ResolutionStrategy} with bound size as 640x480 and fallback rule of
+ * output may differ from the requested value due to device constraints. When set to
+ * {@code null}, CameraX will use the default config of {@link ImageAnalysis}. ImageAnalysis has
+ * a default {@link ResolutionStrategy} with bound size as 640x480 and fallback rule of
* {@link ResolutionStrategy#FALLBACK_RULE_CLOSEST_HIGHER_THEN_LOWER}.
*
* <p>Changing the value will reconfigure the camera which will cause additional latency. To
@@ -1412,10 +1414,10 @@
* <p>If not set, the background executor will default to an automatically generated
* {@link Executor}.
*
- * <p> Changing the value will reconfigure the camera, which will cause additional latency. To
+ * <p>Changing the value will reconfigure the camera, which will cause additional latency. To
* avoid this, set the value before controller is bound to lifecycle.
*
- * @param executor the executor for {@link ImageAnalysis} background tasks.
+ * @param executor The executor for {@link ImageAnalysis} background tasks.
* @see ImageAnalysis.Builder#setBackgroundExecutor(Executor)
*/
@MainThread
@@ -1550,8 +1552,8 @@
/**
* Checks if video capture is enabled.
*
- * <p> Video capture is disabled by default. It has to be enabled before
- * {@link #startRecording} can be called.
+ * <p>Video capture is disabled by default. It has to be enabled before {@link #startRecording}
+ * can be called.
*/
@MainThread
public boolean isVideoCaptureEnabled() {
@@ -1562,28 +1564,27 @@
/**
* Takes a video to a given file.
*
- * <p> Only a single recording can be active at a time, so if {@link #isRecording()} is true,
- * this will throw an {@link IllegalStateException}.
+ * <p>Only a single recording can be active at a time, so if {@link #isRecording()} is
+ * {@code true}, this will throw an {@link IllegalStateException}.
*
- * <p> Upon successfully starting the recording, a {@link VideoRecordEvent.Start} event will
+ * <p>Upon successfully starting the recording, a {@link VideoRecordEvent.Start} event will
* be the first event sent to the provided event listener.
*
- * <p> If errors occur while starting the recording, a {@link VideoRecordEvent.Finalize} event
+ * <p>If errors occur while starting the recording, a {@link VideoRecordEvent.Finalize} event
* will be the first event sent to the provided listener, and information about the error can
* be found in that event's {@link VideoRecordEvent.Finalize#getError()} method.
*
- * <p> Recording with audio requires the {@link android.Manifest.permission#RECORD_AUDIO}
+ * <p>Recording with audio requires the {@link android.Manifest.permission#RECORD_AUDIO}
* permission; without it, starting a recording will fail with a {@link SecurityException}.
*
- * @param outputOptions the options to store the newly captured video.
- * @param audioConfig the configuration of audio.
- * @param executor the executor that the event listener will be run on.
- * @param listener the event listener to handle video record events.
+ * @param outputOptions The options to store the newly captured video.
+ * @param audioConfig The configuration of audio.
+ * @param executor The executor that the event listener will be run on.
+ * @param listener The event listener to handle video record events.
* @return a {@link Recording} that provides controls for new active recordings.
* @throws IllegalStateException if there is an unfinished active recording.
- * @throws SecurityException if the audio config specifies audio should be enabled but the
- * {@link android.Manifest.permission#RECORD_AUDIO} permission
- * is denied.
+ * @throws SecurityException if the audio config specifies audio should be enabled but the
+ * {@link android.Manifest.permission#RECORD_AUDIO} permission is denied.
*/
@SuppressLint("MissingPermission")
@MainThread
@@ -1599,31 +1600,30 @@
/**
* Takes a video to a given file descriptor.
*
- * <p> Currently, file descriptors as output destinations are not supported on pre-Android O
+ * <p>Currently, file descriptors as output destinations are not supported on pre-Android O
* (API 26) devices.
*
- * <p> Only a single recording can be active at a time, so if {@link #isRecording()} is true,
+ * <p>Only a single recording can be active at a time, so if {@link #isRecording()} is true,
* this will throw an {@link IllegalStateException}.
*
- * <p> Upon successfully starting the recording, a {@link VideoRecordEvent.Start} event will
+ * <p>Upon successfully starting the recording, a {@link VideoRecordEvent.Start} event will
* be the first event sent to the provided event listener.
*
- * <p> If errors occur while starting the recording, a {@link VideoRecordEvent.Finalize} event
+ * <p>If errors occur while starting the recording, a {@link VideoRecordEvent.Finalize} event
* will be the first event sent to the provided listener, and information about the error can
* be found in that event's {@link VideoRecordEvent.Finalize#getError()} method.
*
- * <p> Recording with audio requires the {@link android.Manifest.permission#RECORD_AUDIO}
+ * <p>Recording with audio requires the {@link android.Manifest.permission#RECORD_AUDIO}
* permission; without it, starting a recording will fail with a {@link SecurityException}.
*
- * @param outputOptions the options to store the newly captured video.
- * @param audioConfig the configuration of audio.
- * @param executor the executor that the event listener will be run on.
- * @param listener the event listener to handle video record events.
+ * @param outputOptions The options to store the newly captured video.
+ * @param audioConfig The configuration of audio.
+ * @param executor The executor that the event listener will be run on.
+ * @param listener The event listener to handle video record events.
* @return a {@link Recording} that provides controls for new active recordings.
* @throws IllegalStateException if there is an unfinished active recording.
- * @throws SecurityException if the audio config specifies audio should be enabled but the
- * {@link android.Manifest.permission#RECORD_AUDIO} permission
- * is denied.
+ * @throws SecurityException if the audio config specifies audio should be enabled but the
+ * {@link android.Manifest.permission#RECORD_AUDIO} permission is denied.
*/
@SuppressLint("MissingPermission")
@RequiresApi(26)
@@ -1640,28 +1640,27 @@
/**
* Takes a video to MediaStore.
*
- * <p> Only a single recording can be active at a time, so if {@link #isRecording()} is true,
- * this will throw an {@link IllegalStateException}.
+ * <p>Only a single recording can be active at a time, so if {@link #isRecording()} is
+ * {@code true}, this will throw an {@link IllegalStateException}.
*
- * <p> Upon successfully starting the recording, a {@link VideoRecordEvent.Start} event will
+ * <p>Upon successfully starting the recording, a {@link VideoRecordEvent.Start} event will
* be the first event sent to the provided event listener.
*
- * <p> If errors occur while starting the recording, a {@link VideoRecordEvent.Finalize} event
+ * <p>If errors occur while starting the recording, a {@link VideoRecordEvent.Finalize} event
* will be the first event sent to the provided listener, and information about the error can
* be found in that event's {@link VideoRecordEvent.Finalize#getError()} method.
*
- * <p> Recording with audio requires the {@link android.Manifest.permission#RECORD_AUDIO}
+ * <p>Recording with audio requires the {@link android.Manifest.permission#RECORD_AUDIO}
* permission; without it, starting a recording will fail with a {@link SecurityException}.
*
- * @param outputOptions the options to store the newly captured video.
- * @param audioConfig the configuration of audio.
- * @param executor the executor that the event listener will be run on.
- * @param listener the event listener to handle video record events.
+ * @param outputOptions The options to store the newly captured video.
+ * @param audioConfig The configuration of audio.
+ * @param executor The executor that the event listener will be run on.
+ * @param listener The event listener to handle video record events.
* @return a {@link Recording} that provides controls for new active recordings.
* @throws IllegalStateException if there is an unfinished active recording.
- * @throws SecurityException if the audio config specifies audio should be enabled but the
- * {@link android.Manifest.permission#RECORD_AUDIO} permission
- * is denied.
+ * @throws SecurityException if the audio config specifies audio should be enabled but the
+ * {@link android.Manifest.permission#RECORD_AUDIO} permission is denied.
*/
@SuppressLint("MissingPermission")
@MainThread
@@ -1712,11 +1711,11 @@
/**
* Generates a {@link PendingRecording} instance for starting a recording.
*
- * <p> This method handles {@code prepareRecording()} methods for different output formats,
+ * <p>This method handles {@code prepareRecording()} methods for different output formats,
* and makes {@link #startRecordingInternal(OutputOptions, AudioConfig, Executor, Consumer)}
* only handle the general flow.
*
- * <p> This method uses the parent class {@link OutputOptions} as the parameter. On the other
+ * <p>This method uses the parent class {@link OutputOptions} as the parameter. On the other
* hand, the public {@code startRecording()} is overloaded with subclasses. The reason is to
* enforce compile-time check for API levels.
*/
@@ -1788,9 +1787,9 @@
/**
* Stops an in-progress video recording.
*
- * <p> Once the current recording has been stopped, the next recording can be started.
+ * <p>Once the current recording has been stopped, the next recording can be started.
*
- * <p> If the recording completes successfully, a {@link VideoRecordEvent.Finalize} event with
+ * <p>If the recording completes successfully, a {@link VideoRecordEvent.Finalize} event with
* {@link VideoRecordEvent.Finalize#ERROR_NONE} will be sent to the provided listener.
*/
@MainThread
@@ -1821,10 +1820,10 @@
* <p>If no quality selector is provided, the default is
* {@link Recorder#DEFAULT_QUALITY_SELECTOR}.
*
- * <p>Changing the value will reconfigure the camera which will cause video capture to stop.
- * To avoid this, set the value before controller is bound to lifecycle.
+ * <p>Changing the value will reconfigure the camera which will cause video capture to stop. To
+ * avoid this, set the value before controller is bound to lifecycle.
*
- * @param qualitySelector the quality selector for {@link #VIDEO_CAPTURE}.
+ * @param qualitySelector The quality selector for {@link #VIDEO_CAPTURE}.
* @see QualitySelector
*/
@MainThread
@@ -2037,15 +2036,15 @@
/**
* Sets the {@link CameraSelector}.
*
- * <p> Calling this method with a {@link CameraSelector} that resolves to a different camera
+ * <p>Calling this method with a {@link CameraSelector} that resolves to a different camera
* will change the camera being used by the controller. If camera initialization is complete,
* the controller will immediately rebind use cases with the new {@link CameraSelector};
* otherwise, the new {@link CameraSelector} will be used when the camera becomes ready.
*
* <p>The default value is {@link CameraSelector#DEFAULT_BACK_CAMERA}.
*
- * @throws IllegalStateException If the provided camera selector is unable to resolve a
- * camera to be used for the enabled use cases.
+ * @throws IllegalStateException If the provided camera selector is unable to resolve a camera
+ * to be used for the enabled use cases.
* @see CameraSelector
*/
@MainThread
@@ -2074,11 +2073,11 @@
/**
* Checks if the given {@link CameraSelector} can be resolved to a camera.
*
- * <p> Use this method to check if the device has the given camera.
+ * <p>Use this method to check if the device has the given camera.
*
- * <p> Only call this method after camera is initialized. e.g. after the
- * {@link ListenableFuture} from {@link #getInitializationFuture()} is finished. Calling it
- * prematurely throws {@link IllegalStateException}. Example:
+ * <p>Only call this method after camera is initialized. e.g. after the {@link ListenableFuture}
+ * from {@link #getInitializationFuture()} is finished. Calling it prematurely throws
+ * {@link IllegalStateException}. Example:
*
* <pre><code>
* controller.getInitializationFuture().addListener(() -> {
@@ -2092,7 +2091,7 @@
* }, ContextCompat.getMainExecutor(requireContext()));
* </code></pre>
*
- * @return true if the {@link CameraSelector} can be resolved to a camera.
+ * @return {@code true} if the {@link CameraSelector} can be resolved to a camera.
* @throws IllegalStateException if the camera is not initialized.
*/
@MainThread
@@ -2130,9 +2129,9 @@
/**
* Returns whether pinch-to-zoom is enabled.
*
- * <p> By default pinch-to-zoom is enabled.
+ * <p>By default pinch-to-zoom is enabled.
*
- * @return True if pinch-to-zoom is enabled.
+ * @return {@code true} if pinch-to-zoom is enabled.
*/
@MainThread
public boolean isPinchToZoomEnabled() {
@@ -2146,7 +2145,7 @@
* <p>Once enabled, end user can pinch on the {@link PreviewView} to zoom in/out if the bound
* camera supports zooming.
*
- * @param enabled True to enable pinch-to-zoom.
+ * @param enabled {@code true} to enable pinch-to-zoom.
*/
@MainThread
public void setPinchToZoomEnabled(boolean enabled) {
@@ -2237,9 +2236,9 @@
/**
* Returns whether tap-to-focus is enabled.
*
- * <p> By default tap-to-focus is enabled.
+ * <p>By default tap-to-focus is enabled.
*
- * @return True if tap-to-focus is enabled.
+ * @return {@code true} if tap-to-focus is enabled.
*/
@MainThread
public boolean isTapToFocusEnabled() {
@@ -2252,7 +2251,7 @@
*
* <p>Once enabled, end user can tap on the {@link PreviewView} to set focus point.
*
- * @param enabled True to enable tap-to-focus.
+ * @param enabled {@code true} to enable tap-to-focus.
*/
@MainThread
public void setTapToFocusEnabled(boolean enabled) {
@@ -2263,7 +2262,7 @@
/**
* Returns a {@link LiveData} with the latest tap-to-focus state.
*
- * <p> When tap-to-focus feature is enabled, the {@link LiveData} will receive updates of
+ * <p>When tap-to-focus feature is enabled, the {@link LiveData} will receive updates of
* focusing states. This happens when the end user taps on {@link PreviewView}, and then again
* when focusing is finished either successfully or unsuccessfully. The following table
* displays the states the {@link LiveData} can be in, and the possible transitions between
@@ -2340,13 +2339,14 @@
/**
* Gets the {@link CameraInfo} of the currently attached camera.
*
- * <p> For info available directly through CameraController as well as {@link CameraInfo},
- * it's recommended to use the ones with CameraController, e.g. {@link #getTorchState()} v.s.
- * {@link CameraInfo#getTorchState()}. {@link CameraInfo} is a lower-layer API and may
- * require more steps to achieve the same effect, and will not maintain values when switching
- * between cameras.
+ * <p>For info available directly through CameraController as well as {@link CameraInfo}, it's
+ * recommended to use the ones with CameraController, e.g. {@link #getTorchState()} v.s.
+ * {@link CameraInfo#getTorchState()}. {@link CameraInfo} is a lower-layer API and may require
+ * more steps to achieve the same effect, and will not maintain values when switching between
+ * cameras.
*
- * @return the {@link CameraInfo} of the current camera. Returns null if camera is not ready.
+ * @return The {@link CameraInfo} of the current camera. Returns {@code null} if camera is not
+ * ready.
* @see Camera#getCameraInfo()
*/
@Nullable
@@ -2359,13 +2359,14 @@
/**
* Gets the {@link CameraControl} of the currently attached camera.
*
- * <p> For controls available directly through CameraController as well as
+ * <p>For controls available directly through CameraController as well as
* {@link CameraControl}, it's recommended to use the ones with CameraController, e.g.
* {@link #setLinearZoom(float)} v.s. {@link CameraControl#setLinearZoom(float)}.
* CameraControl is a lower-layer API and may require more steps to achieve the same effect,
* and will not maintain control values when switching between cameras.
*
- * @return the {@link CameraControl} of the current camera. Returns null if camera is not ready.
+ * @return The {@link CameraControl} of the current camera. Returns {@code null} if camera is
+ * not ready.
* @see Camera#getCameraControl()
*/
@Nullable
@@ -2385,7 +2386,7 @@
* camera to be ready and then sets the zoom ratio.
*
* @param zoomRatio The requested zoom ratio.
- * @return a {@link ListenableFuture} which is finished when camera is set to the given ratio.
+ * @return A {@link ListenableFuture} which is finished when camera is set to the given ratio.
* It fails with {@link CameraControl.OperationCanceledException} if there is newer value
* being set or camera is closed. If the ratio is out of range, it fails with
* {@link IllegalArgumentException}. Cancellation of this future is a no-op.
@@ -2413,7 +2414,7 @@
* <p>If the value is set before the camera is ready, {@link CameraController} waits for the
* camera to be ready and then sets the linear zoom.
*
- * @return a {@link ListenableFuture} which is finished when camera is set to the given ratio.
+ * @return A {@link ListenableFuture} which is finished when camera is set to the given ratio.
* It fails with {@link CameraControl.OperationCanceledException} if there is newer value
* being set or camera is closed. If the ratio is out of range, it fails with
* {@link IllegalArgumentException}. Cancellation of this future is a no-op.
@@ -2432,10 +2433,10 @@
/**
* Returns a {@link LiveData} of current {@link TorchState}.
*
- * <p>The torch can be turned on and off via {@link #enableTorch(boolean)} which
- * will trigger the change event to the returned {@link LiveData}.
+ * <p>The torch can be turned on and off via {@link #enableTorch(boolean)} which will trigger
+ * the change event to the returned {@link LiveData}.
*
- * @return a {@link LiveData} containing current torch state.
+ * @return A {@link LiveData} containing current torch state.
* @see CameraInfo#getTorchState()
*/
@NonNull
@@ -2451,7 +2452,7 @@
* <p>If the value is set before the camera is ready, {@link CameraController} waits for the
* camera to be ready and then enables the torch.
*
- * @param torchEnabled true to turn on the torch, false to turn it off.
+ * @param torchEnabled {@code true} to turn on the torch, {@code false} to turn it off.
* @return A {@link ListenableFuture} which is successful when the torch was changed to the
* value specified. It fails when it is unable to change the torch state. Cancellation of
* this future is a no-op.
@@ -2483,7 +2484,7 @@
* supported by CameraX. Please see the Javadoc of {@link UseCaseGroup.Builder#addEffect} to
* see the supported effects combinations.
*
- * @param effects the effects applied to camera output.
+ * @param effects The effects applied to camera output.
* @throws IllegalArgumentException if the combination of effects is not supported by CameraX.
* @see UseCaseGroup.Builder#addEffect
*/
@@ -2531,10 +2532,10 @@
}
/**
- * @param restoreStateRunnable runnable to restore the controller to the previous good state if
- * the binding fails.
+ * @param restoreStateRunnable {@link Runnable} to restore the controller to the previous good
+ * state if the binding fails.
* @throws IllegalStateException for invalid {@link UseCase} combinations.
- * @throws RuntimeException for invalid {@link CameraEffect} combinations.
+ * @throws RuntimeException for invalid {@link CameraEffect} combinations.
*/
void startCameraAndTrackStates(@Nullable Runnable restoreStateRunnable) {
try {
@@ -2560,8 +2561,8 @@
/**
* Creates {@link UseCaseGroup} from all the use cases.
*
- * <p> Preview is required. If it is null, then controller is not ready. Return null and ignore
- * other use cases.
+ * <p>Preview is required. If it is {@code null}, then controller is not ready. Return
+ * {@code null} and ignore other use cases.
*/
@Nullable
@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
@@ -2606,7 +2607,7 @@
/**
* Represents the output size of a {@link UseCase}.
*
- * <p> This class is a preferred output size to be used with {@link CameraController}. The
+ * <p>This class is a preferred output size to be used with {@link CameraController}. The
* preferred output size can be based on either resolution or aspect ratio, but not both.
*
* @see #setImageAnalysisTargetSize(OutputSize)
@@ -2674,7 +2675,7 @@
/**
* Gets the value of resolution.
*
- * @return null if the size is not based on resolution.
+ * @return {@code null} if the size is not based on resolution.
*/
@Nullable
public Size getResolution() {
