Add documentation

pull/580/head
Mattia Iavarone 6 years ago
parent e21cdc7ae1
commit a1974ef9e3
  1. 13
      cameraview/src/main/java/com/otaliastudios/cameraview/CameraListener.java
  2. 2
      cameraview/src/main/java/com/otaliastudios/cameraview/CameraOptions.java
  3. 15
      cameraview/src/main/java/com/otaliastudios/cameraview/CameraView.java
  4. 2
      cameraview/src/main/java/com/otaliastudios/cameraview/gesture/GestureAction.java
  5. 2
      docs/_posts/2018-12-20-changelog.md
  6. 95
      docs/_posts/2018-12-20-controls.md
  7. 4
      docs/_posts/2018-12-20-gestures.md
  8. 148
      docs/_posts/2019-09-04-metering.md

@ -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

@ -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.
*

@ -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()

@ -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}

@ -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

@ -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
<com.otaliastudios.cameraview.CameraView
app:cameraAutoFocusMarker="@string/cameraview_default_autofocus_marker"
app:cameraAutoFocusResetDelay="3000"/>
```
##### 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.

@ -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`|

@ -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
<com.otaliastudios.cameraview.CameraView
app:cameraPictureMetering="true|false"
app:cameraPictureSnapshotMetering="false|true"
app:cameraAutoFocusMarker="@string/cameraview_default_autofocus_marker"
app:cameraAutoFocusResetDelay="3000"/>
```
### 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.|
Loading…
Cancel
Save