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