From 9d9de4bc438080987b06f516daf6ba89f2082e33 Mon Sep 17 00:00:00 2001 From: Mattia Iavarone Date: Fri, 21 Dec 2018 13:01:22 +0100 Subject: [PATCH] Missing docs about exposure, zoom and location --- docs/_posts/2018-12-20-controls.md | 80 +++++++++++++++++++++++++ docs/_posts/2018-12-20-more-features.md | 40 +++++++++---- 2 files changed, 108 insertions(+), 12 deletions(-) diff --git a/docs/_posts/2018-12-20-controls.md b/docs/_posts/2018-12-20-controls.md index 31a38cf9..76de7d01 100644 --- a/docs/_posts/2018-12-20-controls.md +++ b/docs/_posts/2018-12-20-controls.md @@ -137,3 +137,83 @@ Use 0 or a negative value to fallback to the encoder default. Defaults to 0. cameraView.setVideoBitRate(0); cameraView.setVideoBitRate(4000000); ``` + +### Manual 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 onFocusStart(@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 onFocusEnd(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 onFocusStart. + } +}); +``` + +Auto focus is not guaranteed to be supported: check the `CameraOptions` to be sure. + +### Zoom + +There are two ways to control the zoom value: + +- User can zoom in or out with a [Gesture](gestures.html) +- The developer can start manual zoom with the `setZoom(float)` API, passing in a value between 0 and 1. + +Both actions will trigger the zoom callback, which can be used, for example, to draw a seek bar: + +```java +cameraView.addCameraListener(new CameraListener() { + + @Override + public void onZoomChanged(float newValue, @NonNull float[] bounds, @Nullable PointF[] fingers) { + // newValue: the new zoom value + // bounds: this is always [0, 1] + // fingers: if caused by touch gestures, these is the fingers position + } +}); +``` + +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 {@link 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-more-features.md b/docs/_posts/2018-12-20-more-features.md index 3e7a0bf3..32831f18 100644 --- a/docs/_posts/2018-12-20-more-features.md +++ b/docs/_posts/2018-12-20-more-features.md @@ -16,7 +16,7 @@ date: 2018-12-20 20:41:20 app:cameraGridColor="@color/black"/> ``` -#### cameraPlaySounds +##### cameraPlaySounds Controls whether we should play platform-provided sounds during certain events (shutter click, focus completed). Please note that: @@ -31,7 +31,7 @@ cameraView.setPlaySounds(true); cameraView.setPlaySounds(false); ``` -#### cameraGrid +##### cameraGrid Lets you draw grids over the camera preview. Supported values are `off`, `draw3x3` and `draw4x4` for regular grids, and `drawPhi` for a grid based on the golden ratio constant, often used in photography. @@ -44,7 +44,7 @@ cameraView.setGrid(Grid.DRAW_4X4); cameraView.setGrid(Grid.DRAW_PHI); ``` -#### cameraGridColor +##### cameraGridColor Lets you choose the color for grid lines. Defaults to a shade of grey. @@ -54,24 +54,40 @@ cameraView.setGridColor(Color.WHITE); cameraView.setGridColor(Color.BLACK); ``` -### Undocumented features +### UI Orientation -Some features and APIs were not documented in this document, including: +Within a Camera app, it's common to rotate buttons and other UI elements as the device is tilted around. +We offer a handy callback giving you the right rotation that should be applied to UI elements for them +to be consistent with what the user is seeing: -- `CameraUtils` utilities -- `CameraOptions` options -- `CameraView.setLocation` APIs +```java +cameraView.addCameraListener(new CameraListener() { + @Override + public void onOrientationChanged(int orientation) { + // orientation is the counter-clockwise rotation that a View should have + // based on current device tilting and native activity orientation. + } +}); +``` -For informations, please take a look at the javadocs or the source code. +### Location APIs + +You can plug in location tags into picture EXIF (for JPEGs) and video metadata by simply using `setLocation`. +The location can be obtained from any location provider after getting appropriate permissions. +This is not guaranteed to be appended into snapshots. |Method|Description| |------|-----------| -|`setZoom(float)`, `getZoom()`|Sets a zoom value, where 0 means camera zoomed out and 1 means zoomed in. No-op if zoom is not supported, or camera not started.| -|`setExposureCorrection(float)`, `getExposureCorrection()`|Sets exposure compensation EV value, in camera stops. No-op if this is not supported. Should be between the bounds returned by CameraOptions.| |`setLocation(Location)`|Sets location data to be appended to picture/video metadata.| |`setLocation(double, double)`|Sets latitude and longitude to be appended to picture/video metadata.| |`getLocation()`|Retrieves location data previously applied with setLocation().| -|`startAutoFocus(float, float)`|Starts an autofocus process at the given coordinates, with respect to the view dimensions.| +### Undocumented features + +Some features and APIs were not documented in this document, including: +- `CameraUtils` utilities +- `CameraOptions` options + +For informations, please take a look at the javadocs or the source code.