From a1974ef9e3cc51a98d9303d8b75a357a93a4fb01 Mon Sep 17 00:00:00 2001 From: Mattia Iavarone Date: Wed, 4 Sep 2019 20:33:45 +0200 Subject: [PATCH] Add documentation --- .../cameraview/CameraListener.java | 13 +- .../cameraview/CameraOptions.java | 2 +- .../otaliastudios/cameraview/CameraView.java | 15 +- .../cameraview/gesture/GestureAction.java | 2 +- docs/_posts/2018-12-20-changelog.md | 2 +- docs/_posts/2018-12-20-controls.md | 95 ----------- docs/_posts/2018-12-20-gestures.md | 4 +- docs/_posts/2019-09-04-metering.md | 148 ++++++++++++++++++ 8 files changed, 168 insertions(+), 113 deletions(-) diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/CameraListener.java b/cameraview/src/main/java/com/otaliastudios/cameraview/CameraListener.java index 0a1f774d..fcc76515 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/CameraListener.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/CameraListener.java @@ -81,8 +81,9 @@ public abstract class CameraListener { /** - * Notifies that user interacted with the screen and started focus with a gesture, - * and the autofocus is trying to focus around that area. This can be used to draw things on screen. + * Notifies that user interacted with the screen and started metering with a gesture, + * and touch metering routine is trying to focus around that area. + * This callback can be used to draw things on screen. * Can also be triggered by {@link CameraView#startAutoFocus(float, float)}. * * @param point coordinates with respect to CameraView.getWidth() and CameraView.getHeight() @@ -92,12 +93,12 @@ public abstract class CameraListener { /** - * Notifies that a gesture focus event just ended, and the camera converged - * to a new focus (and possibly exposure and white balance). + * Notifies that a touch metering event just ended, and the camera converged + * to a new focus, exposure and possibly white balance. * This might succeed or not. * Can also be triggered by {@link CameraView#startAutoFocus(float, float)}. * - * @param successful whether camera succeeded + * @param successful whether metering succeeded * @param point coordinates with respect to CameraView.getWidth() and CameraView.getHeight() */ @UiThread @@ -105,7 +106,7 @@ public abstract class CameraListener { /** - * Noitifies that a finger gesture just caused the camera zoom + * Notifies that a finger gesture just caused the camera zoom * to be changed. This can be used to draw, for example, a seek bar. * * @param newValue the new zoom value diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/CameraOptions.java b/cameraview/src/main/java/com/otaliastudios/cameraview/CameraOptions.java index 1e50ae4b..cde2f9b9 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/CameraOptions.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/CameraOptions.java @@ -427,7 +427,7 @@ public class CameraOptions { /** - * Whether auto focus (metering with respect to a specific region of the screen) is + * Whether touch metering (metering with respect to a specific region of the screen) is * supported. If it is, you can map gestures to {@link GestureAction#AUTO_FOCUS} * and metering will change on tap. * diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/CameraView.java b/cameraview/src/main/java/com/otaliastudios/cameraview/CameraView.java index ab69fa1b..b21cfd58 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/CameraView.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/CameraView.java @@ -1235,7 +1235,7 @@ public class CameraView extends FrameLayout implements LifecycleObserver { } /** - * Sets an {@link AutoFocusMarker} to be notified of autofocus start, end and fail events + * Sets an {@link AutoFocusMarker} to be notified of metering start, end and fail events * so that it can draw elements on screen. * * @param autoFocusMarker the marker, or null @@ -1246,25 +1246,26 @@ public class CameraView extends FrameLayout implements LifecycleObserver { } /** - * Sets the current delay in milliseconds to reset the focus after an autofocus process. + * Sets the current delay in milliseconds to reset the focus after a metering event. * - * @param delayMillis desired delay (in milliseconds). If the delay + * @param delayMillis desired delay (in milliseconds). If the delay * is less than or equal to 0 or equal to Long.MAX_VALUE, - * the autofocus will not be reset. + * the values will not be reset. */ public void setAutoFocusResetDelay(long delayMillis) { mCameraEngine.setAutoFocusResetDelay(delayMillis); } /** - * Returns the current delay in milliseconds to reset the focus after an autofocus process. - * @return the current autofocus reset delay in milliseconds. + * Returns the current delay in milliseconds to reset the focus after a metering event. + * + * @return the current reset delay in milliseconds */ @SuppressWarnings("unused") public long getAutoFocusResetDelay() { return mCameraEngine.getAutoFocusResetDelay(); } /** - * Starts an autofocus process at the given coordinates, with respect + * Starts a 3A touch metering process at the given coordinates, with respect * to the view width and height. * * @param x should be between 0 and getWidth() diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/gesture/GestureAction.java b/cameraview/src/main/java/com/otaliastudios/cameraview/gesture/GestureAction.java index b4fa3659..e384ad72 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/gesture/GestureAction.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/gesture/GestureAction.java @@ -23,7 +23,7 @@ public enum GestureAction { NONE(0, GestureType.ONE_SHOT), /** - * Auto focus control, typically assigned to the tap gesture. + * Touch metering control, typically assigned to the tap gesture. * This action can be mapped to one shot gestures: * * - {@link Gesture#TAP} diff --git a/docs/_posts/2018-12-20-changelog.md b/docs/_posts/2018-12-20-changelog.md index e1dcdfcf..2e8d729c 100644 --- a/docs/_posts/2018-12-20-changelog.md +++ b/docs/_posts/2018-12-20-changelog.md @@ -70,7 +70,7 @@ https://github.com/natario1/CameraView/compare/v2.0.0-beta06...v2.0.0-rc1 If you were using `focus`, just switch to `autoFocus`. -If you were using `focusWithMarker`, you can [add back the old marker](../docs/controls.html#cameraautofocusmarker). +If you were using `focusWithMarker`, you can [add back the old marker](../docs/metering.html#touch-metering-markers). https://github.com/natario1/CameraView/compare/v2.0.0-beta05...v2.0.0-beta06 diff --git a/docs/_posts/2018-12-20-controls.md b/docs/_posts/2018-12-20-controls.md index 535dc046..cf89d708 100644 --- a/docs/_posts/2018-12-20-controls.md +++ b/docs/_posts/2018-12-20-controls.md @@ -143,76 +143,6 @@ cameraView.setVideoBitRate(0); cameraView.setVideoBitRate(4000000); ``` -### Auto Focus - -There are many ways to focus a CameraView engine: - -- Continuous autofocus is activated by default, where present -- User can start focus with a [Gesture](gestures.html) -- The developer can start focus with the `startAutoFocus(float, float)` API. This action needs - the coordinates of a point to focus, with respect to the view width and height. - -The last two actions will trigger the focus callbacks: - -```java -cameraView.addCameraListener(new CameraListener() { - - @Override - public void onAutoFocusStart(@NonNull PointF point) { - // Auto focus was started by a gesture or by startAutoFocus(float, float). - // The camera is currently trying to focus around that area. - // This can be used to draw things on screen. - } - - @Override - public void onAutoFocusEnd(boolean successful, @NonNull PointF point) { - // Auto focus operation just ended. If successful, the camera will have converged - // to a new focus point, and possibly changed exposure and white balance as well. - // The point is the same that was passed to onAutoFocusStart. - } -}); -``` - -Auto focus is not guaranteed to be supported: check the `CameraOptions` to be sure. - -```xml - -``` - -##### cameraAutoFocusMarker - -Lets you set a marker for drawing on screen in response to auto focus events. -In XML, you should pass the qualified class name of your marker. - -```java -cameraView.setAutoFocusMarker(null); -cameraView.setAutoFocusMarker(marker); -``` - -We offer a default marker (similar to the old `focusWithMarker` attribute in v1), -which you can set in XML using the `@string/cameraview_default_autofocus_marker` resource, -or programmatically: - -```java -cameraView.setAutoFocusMarker(new DefaultAutoFocusMarker()); -``` - -##### cameraAutoFocusResetDelay - -Lets you control how an auto-focus operation is reset after completed. -Setting a value <= 0 or == Long.MAX_VALUE will not reset the auto-focus. -This is useful for low end devices that have slow auto-focus capabilities. -Defaults to 3 seconds. - -```java -cameraView.setCameraAutoFocusResetDelay(1000); // 1 second -cameraView.setCameraAutoFocusResetDelay(0); // NO reset -cameraView.setCameraAutoFocusResetDelay(-1); // NO reset -cameraView.setCameraAutoFocusResetDelay(Long.MAX_VALUE); // NO reset -``` - ### Zoom There are two ways to control the zoom value: @@ -235,28 +165,3 @@ cameraView.addCameraListener(new CameraListener() { ``` Zoom is not guaranteed to be supported: check the `CameraOptions` to be sure. - -### Exposure correction - -There are two ways to control the exposure correction value: - -- User can change the exposure correction with a [Gesture](gestures.html) -- The developer can change this value with the `setExposureCorrection(float)` API, passing in the EV - value, in camera stops. This value should be contained in the minimum and maximum supported values, - as returned by `CameraOptions`. - -Both actions will trigger the exposure correction callback, which can be used, for example, to draw a seek bar: - -```java -cameraView.addCameraListener(new CameraListener() { - - @UiThread - public void onExposureCorrectionChanged(float newValue, @NonNull float[] bounds, @Nullable PointF[] fingers) { - // newValue: the new correction value - // bounds: min and max bounds for newValue, as returned by CameraOptions - // fingers: finger positions that caused the event, null if not caused by touch - } -}); -``` - -EV correction is not guaranteed to be supported: check the `CameraOptions` to be sure. \ No newline at end of file diff --git a/docs/_posts/2018-12-20-gestures.md b/docs/_posts/2018-12-20-gestures.md index d790ec3c..43f88054 100644 --- a/docs/_posts/2018-12-20-gestures.md +++ b/docs/_posts/2018-12-20-gestures.md @@ -39,10 +39,10 @@ Looking at this from the other side: |Gesture action|Description|Can be mapped to| |--------------|-----------|----------------| |`NONE`|Disables this gesture.|`TAP` `LONG_TAP` `PINCH` `SCROLL_HORIZONTAL` `SCROLL_VERTICAL`| -|`AUTO_FOCUS`|Launches an [auto-focus operation](controls.html#auto-focus) on the finger position.|`TAP` `LONG_TAP`| +|`AUTO_FOCUS`|Launches a [touch metering operation](metering.html#touch-metering) on the finger position.|`TAP` `LONG_TAP`| |`TAKE_PICTURE`|Takes a picture using [takePicture](capturing-media.html).|`TAP` `LONG_TAP`| |`ZOOM`|[Zooms](controls.html#zoom) in or out.|`PINCH` `SCROLL_HORIZONTAL` `SCROLL_VERTICAL`| -|`EXPOSURE_CORRECTION`|Controls the [exposure correction](controls.html#exposure-correction).|`PINCH` `SCROLL_HORIZONTAL` `SCROLL_VERTICAL`| +|`EXPOSURE_CORRECTION`|Controls the [exposure correction](metering.html#exposure-correction).|`PINCH` `SCROLL_HORIZONTAL` `SCROLL_VERTICAL`| |`FILTER_CONTROL_1`|Controls the first parameter (if any) of a [real-time filter](filters.html).|`PINCH` `SCROLL_HORIZONTAL` `SCROLL_VERTICAL`| |`FILTER_CONTROL_2`|Controls the second parameter (if any) of a [real-time filter](filters.html).|`PINCH` `SCROLL_HORIZONTAL` `SCROLL_VERTICAL`| diff --git a/docs/_posts/2019-09-04-metering.md b/docs/_posts/2019-09-04-metering.md index f41cd422..123e1c6d 100644 --- a/docs/_posts/2019-09-04-metering.md +++ b/docs/_posts/2019-09-04-metering.md @@ -8,3 +8,151 @@ order: 4 date: 2019-09-04 19:39:03 disqus: 1 --- + +In CameraView grammar, metering is the act of measuring the scene brightness, colors and focus +distance in order to automatically adapt the camera exposure, focus and white balance (AE, AF and AWB, +often referred as 3A). + +We treat three different types on metering: [continuous metering](#continuous-metering), +[picture metering](#picture-metering) and [touch metering](#touch-metering). + +You can also apply adjustment to the metered exposure through the [exposure correction](#exposure-correction) control. + +### Continuous Metering + +By default, and if the device supports it, all three routines (AE, AF, AWB) are continuously metered +as the device moves or the scene changes. + +- For AE, this is always enabled if supported +- For AF, this is always enabled if supported +- For AWB, this is enabled if the `WhiteBalance` parameter is set to `AUTO` [[docs]](#controls.html#camerawhitebalance) + +### Picture Metering + +*In Camera1, picture metering is always enabled for pictures, and always disabled for picture snapshots. +The following applies to Camera2 only.* + +The camera engine will try to trigger metering when a picture is requested, either with `takePicture()` +or `takePictureSnapshot()`. This has two obvious consequences: + +- improves the picture quality +- increases the latency, because metering takes time + +For these reasons, picture metering is **enabled** by default for HQ pictures and **disabled** by +default for picture snapshots. However, the behavior can be changed with two flags and their +respective XML attributes: + +```java +cameraView.setPictureMetering(true); // Meter before takePicture() +cameraView.setPictureMetering(false); // Don't +cameraView.setPictureSnapshotMetering(true); // Meter before takePictureSnapshot() +cameraView.setPictureSnapshotMetering(false); // Don't +``` + +### Touch Metering + +Touch metering is triggered by either a [Gesture](gestures.html) or by the developer itself, which +can start touch metering on a specific point with the `startAutoFocus(float, float)` API. +This action needs the coordinates of a point computed with respect to the view width and height. + +In both cases, the metering callbacks will be triggered: + +```java +cameraView.addCameraListener(new CameraListener() { + + @Override + public void onAutoFocusStart(@NonNull PointF point) { + // Touch metering was started by a gesture or by startAutoFocus(float, float). + // The camera is currently trying to meter around that area. + // This can be used to draw things on screen. + } + + @Override + public void onAutoFocusEnd(boolean successful, @NonNull PointF point) { + // Touch metering operation just ended. If successful, the camera will have converged + // to a new focus point, and possibly new exposure and white balance as well. + // The point is the same that was passed to onAutoFocusStart. + } +}); +``` + +Touch metering is not guaranteed to be supported: check the `CameraOptions` to be sure. + +##### Touch Metering Markers + +You can set a marker for drawing on screen in response to touch metering events. +In XML, you should pass the qualified class name of your marker. + +```java +cameraView.setAutoFocusMarker(null); +cameraView.setAutoFocusMarker(marker); +``` + +We offer a default marker (similar to the old `focusWithMarker` attribute in v1), +which you can set in XML using the `@string/cameraview_default_autofocus_marker` resource, +or programmatically: + +```java +cameraView.setAutoFocusMarker(new DefaultAutoFocusMarker()); +``` + +##### Touch Metering Reset Delay + +You control control how a touch metering operation is reset after completed. +Setting a value <= 0 or == Long.MAX_VALUE will not reset the metering values. +This is useful for low end devices that have slow auto-focus capabilities. +Defaults to 3 seconds. + +```java +cameraView.setCameraAutoFocusResetDelay(1000); // 1 second +cameraView.setCameraAutoFocusResetDelay(0); // NO reset +cameraView.setCameraAutoFocusResetDelay(-1); // NO reset +cameraView.setCameraAutoFocusResetDelay(Long.MAX_VALUE); // NO reset +``` + +### Exposure correction + +There are two ways to control the exposure correction value: + +- User can change the exposure correction with a [Gesture](gestures.html) +- The developer can change this value with the `setExposureCorrection(float)` API, passing in the EV + value, in camera stops. This value should be contained in the minimum and maximum supported values, + as returned by `CameraOptions`. + +Both actions will trigger the exposure correction callback, which can be used, for example, to draw a seek bar: + +```java +cameraView.addCameraListener(new CameraListener() { + + @UiThread + public void onExposureCorrectionChanged(float newValue, @NonNull float[] bounds, @Nullable PointF[] fingers) { + // newValue: the new correction value + // bounds: min and max bounds for newValue, as returned by CameraOptions + // fingers: finger positions that caused the event, null if not caused by touch + } +}); +``` + +EV correction is not guaranteed to be supported: check the `CameraOptions` to be sure. + +### Related XML Attributes + +```xml + +``` + +### Related APIs + +|Method|Description| +|------|-----------| +|`setPictureMetering(boolean)`|Whether the engine should trigger 3A metering when a picture is requested. Defaults to true.| +|`setPictureSnapshotMetering(boolean)`|Whether the engine should trigger 3A metering when a picture snapshot is requested. Defaults to false.| +|`startAutoFocus(float, float)`|Starts the 3A touch metering routine at the given coordinates, with respect to the view system.| +|`CameraOptions.isAutoFocusSupported()`|Whether touch metering (metering with respect to a specific region of the screen) is supported.| +|`setExposureCorrection(float)`|Changes the exposure adjustment, in EV stops. A positive value means a brighter picture.| +|`CameraOptions.getExposureCorrectionMinValue()`|The minimum value of negative exposure correction, in EV stops.| +|`CameraOptions.getExposureCorrectionMaxValue()`|The maximum value of positive exposure correction, in EV stops.| \ No newline at end of file