A couple of fixes and docs improvements (#1184)

* fix typos and add minor details to the docs

* fix the issue #1175 & fix a typo

* fix the issue #1168 & fix a typo

* fix a typo in PR template

* check result data for null in the onPictureResult() callback

* revert unnecessary changes

* improve log message

Co-authored-by: Dmitry Naymushin <d.naymushin@tinkoff.ru>

.github/pull_request_template.md

@@ -6,7 +6,7 @@ unfortunately, this PR will likely be ignored.
 If the edited files were covered by tests, updated tests are required for merging. 
 Please look into the tests folders and make sure you cover new code.
 
-- Fixes ... (*issue number*)
+- Fixes: ... (*issue number*)
 - Tests: ... (*yes/no*)
 - Docs updated: ... (*yes/no*)
 

cameraview/src/main/java/com/otaliastudios/cameraview/BitmapCallback.java

@@ -12,7 +12,7 @@ public interface BitmapCallback {
     /**
      * Notifies that the bitmap was successfully decoded.
      * This is run on the UI thread.
-     * Returns a null object if a {@link OutOfMemoryError} was encountered.
+     * Returns a null object if an {@link OutOfMemoryError} was encountered.
      *
      * @param bitmap decoded bitmap, or null
      */

cameraview/src/main/java/com/otaliastudios/cameraview/engine/Camera1Engine.java

@@ -881,7 +881,12 @@ public class Camera1Engine extends CameraBaseEngine implements
                 if (maxAF > 0) params.setFocusAreas(transformed.get(maxAF, transform));
                 if (maxAE > 0) params.setMeteringAreas(transformed.get(maxAE, transform));
                 params.setFocusMode(Camera.Parameters.FOCUS_MODE_AUTO);
-                mCamera.setParameters(params);
+                try {
+                    mCamera.setParameters(params);
+                } catch (RuntimeException re) {
+                    LOG.e("startAutoFocus:", "Failed to set camera parameters");
+                    throw new CameraException(re, CameraException.REASON_UNKNOWN);
+                }
                 getCallback().dispatchOnFocusStart(gesture, legacyPoint);
 
                 // The auto focus callback is not guaranteed to be called, but we really want it

cameraview/src/main/java/com/otaliastudios/cameraview/engine/Camera2Engine.java

@@ -479,7 +479,7 @@ public class Camera2Engine extends CameraBaseEngine implements
 
         // Compute sizes.
         // TODO preview stream should never be bigger than 1920x1080 as per
-        //  CameraDevice.createCaptureSession. This should be probably be applied
+        //  CameraDevice.createCaptureSession. This should probably be applied
         //  before all the other external selectors, to treat it as a hard limit.
         //  OR: pass an int into these functions to be able to take smaller dims
         //  when session configuration fails

cameraview/src/main/java/com/otaliastudios/cameraview/engine/CameraBaseEngine.java

@@ -559,10 +559,10 @@ public abstract class CameraBaseEngine extends CameraEngine {
     @Override
     public void onPictureResult(@Nullable PictureResult.Stub result, @Nullable Exception error) {
         mPictureRecorder = null;
-        if (result != null) {
+        if (result != null && result.data != null) {
             getCallback().dispatchOnPictureTaken(result);
         } else {
-            LOG.e("onPictureResult", "result is null: something went wrong.", error);
+            LOG.e("onPictureResult", "result or data is null: something went wrong.", error);
             getCallback().dispatchError(new CameraException(error,
                     CameraException.REASON_PICTURE_FAILED));
         }

demo/src/main/kotlin/com/otaliastudios/cameraview/demo/PicturePreviewActivity.kt

@@ -46,7 +46,7 @@ class PicturePreviewActivity : AppCompatActivity() {
             result.toBitmap(1000, 1000) { bitmap -> imageView.setImageBitmap(bitmap) }
         } catch (e: UnsupportedOperationException) {
             imageView.setImageDrawable(ColorDrawable(Color.GREEN))
-            Toast.makeText(this, "Can't preview this format: " + result.getFormat(), Toast.LENGTH_LONG).show()
+            Toast.makeText(this, "Can't preview this format: " + result.format, Toast.LENGTH_LONG).show()
         }
         if (result.isSnapshot) {
             // Log the real size for debugging reason.
@@ -76,13 +76,13 @@ class PicturePreviewActivity : AppCompatActivity() {
     override fun onOptionsItemSelected(item: MenuItem): Boolean {
         if (item.itemId == R.id.share) {
             Toast.makeText(this, "Sharing...", Toast.LENGTH_SHORT).show()
-            val extension = when (pictureResult!!.format) {
+            val extension = when (requireNotNull(pictureResult).format) {
                 PictureFormat.JPEG -> "jpg"
                 PictureFormat.DNG -> "dng"
                 else -> throw RuntimeException("Unknown format.")
             }
-            val file = File(filesDir, "picture.$extension")
+            val destFile = File(filesDir, "picture.$extension")
-            CameraUtils.writeToFile(pictureResult!!.data, file) { file ->
+            CameraUtils.writeToFile(requireNotNull(pictureResult?.data), destFile) { file ->
                 if (file != null) {
                     val context = this@PicturePreviewActivity
                     val intent = Intent(Intent.ACTION_SEND)

docs/_docs/capturing-media.md

@@ -46,9 +46,9 @@ resulting snapshots are square as well, no matter what the sensor available size
 |`takePictureSnapshot()`|Pictures|Snapshot|`yes`|`yes`|`yes`|That of the preview stream, [or less](snapshot-size)|
 |`takeVideoSnapshot(File)`|Videos|Snapshot|`yes`|`yes`|`yes`|That of the preview stream, [or less](snapshot-size)|
 
-> Please note that the video snaphot features requires:
+> Please note that the video snapshot features require:
-> - API 18. If called before, it throws
+> - API 18. If called on earlier versions, it throws an `IllegalStateException`
-> - An OpenGL preview (see [previews](previews)). If not, it throws
+> - An OpenGL preview (see [previews](previews)). If not, it throws an `IllegalStateException`
 
 ### Capturing pictures while recording
 

docs/_docs/filters.md

@@ -25,7 +25,7 @@ flag to use it. The only condition is to use the `Preview.GL_SURFACE` preview.
 Real-time filters are applied at creation time, through the `app:cameraFilter` XML attribute,
 or anytime during the camera lifecycle using `cameraView.setFilter()`.
 
-We offers a reasonable amount of filters through the `Filters` class, for example:
+We offer a reasonable amount of filters through the `Filters` class, for example:
 
 ```java
 cameraView.setFilter(Filters.BLACK_AND_WHITE.newInstance());

docs/_docs/frame-processing.md

@@ -120,7 +120,7 @@ You can check which formats are available for use through `CameraOptions.getSupp
 ### Advanced: Thread Control
 
 Starting from `v2.5.1`, you can control the number of background threads that are allocated
-for frame processing work. This should further push you into perform processing actions synchronously
+for frame processing work. This should further push you into performing processing actions synchronously
 and can be useful if processing is very slow with respect to the preview frame rate, in order to
 avoid dropping too many frames.
 

docs/_docs/metering.md

@@ -53,7 +53,7 @@ This action needs the coordinates of a point or region computed with respect to
 
 ```java
 // Start touch metering at the center:
-cameraView.startAutoFocus(cameraView.getWidth() / 2F, cameraView.getHeight/() / 2F);
+cameraView.startAutoFocus(cameraView.getWidth() / 2F, cameraView.getHeight() / 2F);
 // Start touch metering within a given area,
 // like the bounding box of a face.
  cameraView.startAutoFocus(rect);
@@ -102,7 +102,7 @@ cameraView.setAutoFocusMarker(new DefaultAutoFocusMarker());
 
 ##### Touch Metering Reset Delay
 
-You control control how a touch metering operation is reset after completed.
+You control how a touch metering operation is reset after being completed.
 Setting a negative value (or 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.

docs/_docs/preview-size.md

@@ -66,7 +66,7 @@ by the engine. The default selector will do the following:
 - Constraint 2: match sizes a bit bigger than the View (so there is no upscaling)
 - Try to match both, or just one, or fallback to the biggest available size
 
-There are not so many reason why you would replace this, other than control the frame processor size
+There are not so many reasons why you would replace this, other than to control the frame processor size
 or, indirectly, the snapshot size. You can, however, hook into the process using `setPreviewStreamSize(SizeSelector)`:
 
 ```java
@@ -79,7 +79,7 @@ cameraView.setPreviewStreamSize(new SizeSelector() {
 });
 ```
 
-After the preview stream size is determined, if it has changed since list time, the `CameraView` will receive
+After the preview stream size is determined, if it has changed since last time, the `CameraView` will receive
 another call to `onMeasure` so the `WRAP_CONTENT` magic can take place.
 
 To understand how SizeSelectors work and the available utilities, please read the [Capture Size](capture-size) document.

docs/_extra/v1-migration-guide.md

@@ -105,8 +105,8 @@ which means that **square videos** or any other ratio are possible.
 The video snapshot supports audio and respects the `Audio`, max duration, max size & codec settings,
 which makes it a powerful tool. The drawback is that it needs:
 
-- API 18. If called before, it throws
+- API 18. If called on earlier versions, it throws an `IllegalStateException`
-- An OpenGL preview (see below). If not, it throws
+- An OpenGL preview (see below). If not, it throws an `IllegalStateException`
 
 ##### Video capturing
 Some new APIs were introduced, which are respected by both standard videos and snapshot videos:
@@ -141,7 +141,7 @@ smart enough to
 - respect the picture/video aspect ratio
 - be a bit bigger than the view so that there is no upscaling
 
-There are not so many reason why you would use this method, other than, for example, control the frame
+There are not so many reasons why you would use this method, other than, for example, to control the frame
 processor size or, indirectly, the snapshots size. If what you are doing is just assigning an aspect ratio, 
 for instance, please do so using `setPictureSize()` and `setVideoSize()`.