From dabbbed6999cfdaa8a94b5d0f05d2b0eec142b76 Mon Sep 17 00:00:00 2001 From: Mattia Iavarone Date: Tue, 6 Aug 2019 17:49:31 +0200 Subject: [PATCH] Add documentation --- README.md | 2 + .../engine/CameraIntegrationTest.java | 12 ++- .../cameraview/controls/Preview.java | 3 +- .../video/encoding/TextureMediaEncoder.java | 2 +- docs/_posts/2018-12-20-debugging.md | 2 +- docs/_posts/2018-12-20-error-handling.md | 2 +- docs/_posts/2018-12-20-more-features.md | 2 +- docs/_posts/2018-12-20-previews.md | 2 +- docs/_posts/2018-12-20-runtime-permissions.md | 2 +- docs/_posts/2019-08-06-filters.md | 102 ++++++++++++++++++ docs/index.md | 1 + 11 files changed, 122 insertions(+), 10 deletions(-) create mode 100644 docs/_posts/2019-08-06-filters.md diff --git a/README.md b/README.md index c433d6da..26ef8f02 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ api 'com.otaliastudios:cameraview:2.0.0' - Fast & reliable - Gestures support [[docs]](https://natario1.github.io/CameraView/docs/gestures.html) +- Real-time filters [[docs]](https://natario1.github.io/CameraView/docs/filters.html) - Camera1 or Camera2 powered engine [[docs]](https://natario1.github.io/CameraView/docs/previews.html) - Frame processing support [[docs]](https://natario1.github.io/CameraView/docs/frame-processing.html) - Watermarks & animated overlays [[docs]](https://natario1.github.io/CameraView/docs/watermarks-and-overlays.html) @@ -101,6 +102,7 @@ motivation boost to push the library forward. app:cameraAutoFocusResetDelay="@integer/autofocus_delay" app:cameraAutoFocusMarker="@string/cameraview_default_autofocus_marker" app:cameraUseDeviceOrientation="true|false" + app:cameraFilter="@string/real_time_filter" app:cameraExperimental="false|true"> diff --git a/cameraview/src/androidTest/java/com/otaliastudios/cameraview/engine/CameraIntegrationTest.java b/cameraview/src/androidTest/java/com/otaliastudios/cameraview/engine/CameraIntegrationTest.java index 86172788..b4a9bc85 100644 --- a/cameraview/src/androidTest/java/com/otaliastudios/cameraview/engine/CameraIntegrationTest.java +++ b/cameraview/src/androidTest/java/com/otaliastudios/cameraview/engine/CameraIntegrationTest.java @@ -65,7 +65,6 @@ public abstract class CameraIntegrationTest extends BaseTest { private final static CameraLogger LOG = CameraLogger.create(CameraIntegrationTest.class.getSimpleName()); private final static long DELAY = 8000; - private final static long VIDEO_DELAY = 16000; @Rule public ActivityTestRule rule = new ActivityTestRule<>(TestActivity.class); @@ -183,8 +182,15 @@ public abstract class CameraIntegrationTest extends BaseTest { })); // Wait for onVideoTaken and check. - VideoResult result = video.await(VIDEO_DELAY); - if (expectSuccess) { + VideoResult result = video.await(DELAY); + + // It seems that when running all the tests together, the device can go in some + // power saving mode which makes the CPU extremely slow. This is especially problematic + // with video snapshots where we do lots of processing. The videoEnd callback can return + // long after the actual stop() call, so if we're still processing, let's wait more. + if (expectSuccess && camera.isTakingVideo()) { + return waitForVideoResult(true); + } else if (expectSuccess) { assertEquals("Should call onVideoRecordingEnd", 0, onVideoRecordingEnd.getCount()); assertNotNull("Should end video", result); } else { diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/controls/Preview.java b/cameraview/src/main/java/com/otaliastudios/cameraview/controls/Preview.java index 9e8b9aee..71c7abf3 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/controls/Preview.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/controls/Preview.java @@ -29,7 +29,8 @@ public enum Preview implements Control { /** * Preview engine based on {@link android.opengl.GLSurfaceView}. * This is the best engine available. Supports video snapshots, - * and picture snapshots while taking videos. + * supports picture snapshots while taking videos, supports + * watermarks and overlays, supports real-time filters. */ GL_SURFACE(2); diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/video/encoding/TextureMediaEncoder.java b/cameraview/src/main/java/com/otaliastudios/cameraview/video/encoding/TextureMediaEncoder.java index 79b23aee..b93328ad 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/video/encoding/TextureMediaEncoder.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/video/encoding/TextureMediaEncoder.java @@ -31,7 +31,7 @@ public class TextureMediaEncoder extends VideoMediaEncoder { private EglCore mEglCore; private EglWindowSurface mWindow; private EglViewport mViewport; - private Pool mFramePool = new Pool<>(100, new Pool.Factory() { + private Pool mFramePool = new Pool<>(Integer.MAX_VALUE, new Pool.Factory() { @Override public Frame create() { return new Frame(); diff --git a/docs/_posts/2018-12-20-debugging.md b/docs/_posts/2018-12-20-debugging.md index 1ea6f1b3..17382d00 100644 --- a/docs/_posts/2018-12-20-debugging.md +++ b/docs/_posts/2018-12-20-debugging.md @@ -2,7 +2,7 @@ layout: page title: "Debugging" category: docs -order: 13 +order: 14 date: 2018-12-20 20:02:38 disqus: 1 --- diff --git a/docs/_posts/2018-12-20-error-handling.md b/docs/_posts/2018-12-20-error-handling.md index 3a3a1968..069e039e 100644 --- a/docs/_posts/2018-12-20-error-handling.md +++ b/docs/_posts/2018-12-20-error-handling.md @@ -2,7 +2,7 @@ layout: page title: "Error Handling" category: docs -order: 12 +order: 13 date: 2018-12-20 20:02:31 disqus: 1 --- diff --git a/docs/_posts/2018-12-20-more-features.md b/docs/_posts/2018-12-20-more-features.md index 45f1cd67..36cb9eed 100644 --- a/docs/_posts/2018-12-20-more-features.md +++ b/docs/_posts/2018-12-20-more-features.md @@ -4,7 +4,7 @@ title: "More features" subtitle: "Undocumented features & more" description: "Undocumented features & more" category: docs -order: 14 +order: 15 date: 2018-12-20 20:41:20 disqus: 1 --- diff --git a/docs/_posts/2018-12-20-previews.md b/docs/_posts/2018-12-20-previews.md index c346522d..32c9a532 100644 --- a/docs/_posts/2018-12-20-previews.md +++ b/docs/_posts/2018-12-20-previews.md @@ -39,7 +39,7 @@ to use all the features available. However, experienced user might prefer a diff |-------|---------|----| |`Preview.SURFACE`|A `SurfaceView`|Can be good for battery, but will not work well with dynamic layout changes and similar things. No support for video snapshots.| |`Preview.TEXTURE`|A `TextureView`|Better. Requires hardware acceleration. No support for video snapshots.| -|`Preview.GL_SURFACE`|A `GLSurfaceView`|Recommended. Supports video snapshots. Might support GL real time filters in the future.| +|`Preview.GL_SURFACE`|A `GLSurfaceView`|Recommended. Supports video snapshots. Supports [overlays](watermarks-and-overlays.html). Supports [real-time filters](filters.html).| The GL surface, as an extra benefit, has a much more efficient way of capturing picture snapshots, that avoids OOM errors, rotating the image on the fly, reading EXIF, and other horrible things belonging to v1. diff --git a/docs/_posts/2018-12-20-runtime-permissions.md b/docs/_posts/2018-12-20-runtime-permissions.md index 84882504..cd3d7934 100644 --- a/docs/_posts/2018-12-20-runtime-permissions.md +++ b/docs/_posts/2018-12-20-runtime-permissions.md @@ -4,7 +4,7 @@ title: "Runtime Permissions" subtitle: "Permissions and Manifest setup" description: "Permissions and Manifest setup" category: docs -order: 11 +order: 12 date: 2018-12-20 20:03:03 disqus: 1 --- diff --git a/docs/_posts/2019-08-06-filters.md b/docs/_posts/2019-08-06-filters.md new file mode 100644 index 00000000..1d8c6a0c --- /dev/null +++ b/docs/_posts/2019-08-06-filters.md @@ -0,0 +1,102 @@ +--- +layout: page +title: "Real-time Filters" +subtitle: "Apply filters to preview and snapshots" +description: "Apply filters to preview and snapshots" +category: docs +order: 11 +date: 2019-08-06 17:10:17 +disqus: 1 +--- + +Starting from version `2.1.0`, CameraView experimentally supports real-time filters that can modify +the camera frames before they are shown and recorded. Just like [overlays](watermarks-and-overlays.html), +these filters are applied to the preview and to any [picture or video snapshots](capturing-media.html). + +Conditions: + +- you must set the experimental flag: `app:cameraExperimental="true"` +- you must use `Preview.GL_SURFACE` as a preview + +### Simple usage + +```xml + +``` + +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: + +```java +cameraView.setFilter(Filters.BLACK_AND_WHITE.newInstance()); +cameraView.setFilter(Filters.VIGNETTE.newInstance()); +cameraView.setFilter(Filters.SEPIA.newInstance()); +``` + +All of the filters stored in the `Filters` class have an XML string resource that you can use +to quickly setup the camera view. For example, `Filters.BLACK_AND_WHITE` can be set by using +`app:cameraFilter="@string/cameraview_filter_black_and_white`. + +The default filter is called `NoFilter` (`Filters.NONE`) and can be used to clear up any other +filter that was previously set and return back to normal. + +|Filter class|Filters value|XML resource value| +|------------|-------------|---------------------| +|`NoFilter`|`Filters.NONE`|`@string/cameraview_filter_none`| +|`AutoFixFilter`|`Filters.AUTO_FIX`|`@string/cameraview_filter_autofix`| +|`BlackAndWhiteFilter`|`Filters.BLACK_AND_WHITE`|`@string/cameraview_filter_black_and_white`| +|`BrightnessFilter`|`Filters.BRIGHTNESS`|`@string/cameraview_filter_brightness`| +|`ContrastFilter`|`Filters.CONTRAST`|`@string/cameraview_filter_contrast`| +|`CrossProcessFilter`|`Filters.CROSS_PROCESS`|`@string/cameraview_filter_cross_process`| +|`DocumentaryFilter`|`Filters.DOCUMENTARY`|`@string/cameraview_filter_documentary`| +|`DuotoneFilter`|`Filters.DUOTONE`|`@string/cameraview_filter_duotone`| +|`FillLightFilter`|`Filters.FILL_LIGHT`|`@string/cameraview_filter_fill_light`| +|`GammaFilter`|`Filters.GAMMA`|`@string/cameraview_filter_gamma`| +|`GrainFilter`|`Filters.GRAIN`|`@string/cameraview_filter_grain`| +|`GrayscaleFilter`|`Filters.GRAYSCALE`|`@string/cameraview_filter_grayscale`| +|`HueFilter`|`Filters.HUE`|`@string/cameraview_filter_hue`| +|`InvertColorsFilter`|`Filters.INVERT_COLORS`|`@string/cameraview_filter_invert_colors`| +|`LomoishFilter`|`Filters.LOMOISH`|`@string/cameraview_filter_lomoish`| +|`PosterizeFilter`|`Filters.POSTERIZE`|`@string/cameraview_filter_posterize`| +|`SaturationFilter`|`Filters.SATURATION`|`@string/cameraview_filter_saturation`| +|`SepiaFilter`|`Filters.SEPIA`|`@string/cameraview_filter_sepia`| +|`SharpnessFilter`|`Filters.SHARPNESS`|`@string/cameraview_filter_sharpness`| +|`TemperatureFilter`|`Filters.TEMPERATURE`|`@string/cameraview_filter_temperature`| +|`TintFilter`|`Filters.TINT`|`@string/cameraview_filter_tint`| +|`VignetteFilter`|`Filters.VIGNETTE`|`@string/cameraview_filter_vignette`| + +Most of these filters accept input parameters to tune them. For example, `DuotoneFilter` will +accept two colors to apply the duotone effect. + +```java +duotoneFilter.setFirstColor(Color.RED); +duotoneFilter.setSecondColor(Color.GREEN); +``` + +You can change these values by acting on the filter object, before or after passing it to `CameraView`. +Whenever something is changed, the updated values will be visible immediately in the next frame. + +### Advanced usage + +Advanced users with OpenGL experience can create their own filters by implementing the `Filter` interface +and passing in a fragment shader and a vertex shader that will be used for drawing. + +We recommend: + +- Subclassing `BaseFilter` instead of implementing `Filter`, since that takes care of most of the work +- If accepting parameters, implementing `OneParameterFilter` or `TwoParameterFilter` as well + +Most of all, the best way of learning is by looking at the current filters implementations in the +`com.otaliastudios.cameraview.filters` package. + +### Related APIs + +|Method|Description| +|------|-----------| +|`setFilter(Filter)`|Sets a new real-time filter.| +|`getFilter()`|Returns the current real-time filter.| \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 4081cf1d..6621266e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -14,6 +14,7 @@ addressing most of the common issues and needs, and still leaving you with flexi - Fast & reliable - Gestures support [[docs]](docs/gestures.html) +- Real-time filters [[docs]](docs/filters.html) - Camera1 or Camera2 powered engine [[docs]](docs/previews.html) - Frame processing support [[docs]](docs/frame-processing.html) - Watermarks & animated overlays [[docs]](docs/watermarks-and-overlays.html)