diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/BaseFilter.java b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/BaseFilter.java index e6ec3d60..e85d2a9d 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/BaseFilter.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/BaseFilter.java @@ -12,28 +12,31 @@ import java.nio.FloatBuffer; /** * A base implementation of {@link Filter} that just leaves the fragment shader to subclasses. - * See {@link NoFilter} for a full implementation. + * See {@link NoFilter} for a non-abstract implementation. * * This class offers a default vertex shader implementation which in most cases is not required * to be changed. Most effects can be rendered by simply changing the fragment shader, thus * by overriding {@link #getFragmentShader()}. * - * This class expects variable to have a certain name: + * All {@link BaseFilter}s should have a no-op public constructor. + * This class will try to automatically implement {@link #copy()} thanks to this. + * If your filter implements public parameters, please implement {@link OneParameterFilter} + * and {@link TwoParameterFilter} to handle them and have them passed automatically to copies. + * + * NOTE - This class expects variable to have a certain name: * - {@link #vertexPositionName} * - {@link #vertexTransformMatrixName} * - {@link #vertexModelViewProjectionMatrixName} * - {@link #vertexTextureCoordinateName} * - {@link #fragmentTextureCoordinateName} - * * You can either change these variables, for example in your constructor, or change your * vertex and fragment shader code to use them. * - * NOTE - All {@link BaseFilter}s should have a no-op public constructor. - * * NOTE - the {@link android.graphics.SurfaceTexture} restrictions apply: * We only support the {@link android.opengl.GLES11Ext#GL_TEXTURE_EXTERNAL_OES} texture target * and it must be specified in the fragment shader as a samplerExternalOES texture. * You also have to explicitly require the extension: see {@link #createDefaultFragmentShader(String)}. + * */ public abstract class BaseFilter implements Filter { diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/Filter.java b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/Filter.java index 021d2679..0a20b710 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/Filter.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/Filter.java @@ -18,6 +18,14 @@ import java.io.File; * * Advanced users can create custom filters using GLES. * It is recommended to extend {@link BaseFilter} instead of this class. + * + * All {@link Filter}s should have a no-op public constructor. + * This ensures that you can pass the filter class to XML attribute {@code app:cameraFilter}, + * and also helps {@link BaseFilter} automatically make a copy of the filter. + * + * Parameterized filters can implement {@link OneParameterFilter} and {@link TwoParameterFilter} + * to receive parameters in the 0F-1F range. This helps in making filter copies and also let us + * map the filter parameter to gestures. */ public interface Filter { @@ -65,6 +73,7 @@ public interface Filter { /** * Called anytime the output size changes. + * * @param width width * @param height height */ diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/OneParameterFilter.java b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/OneParameterFilter.java index 0eead556..b3f0b760 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/OneParameterFilter.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/OneParameterFilter.java @@ -1,8 +1,30 @@ package com.otaliastudios.cameraview.filter; +/** + * A special {@link Filter} that accepts a float parameter. + * + * The parameters will always be between 0F and 1F, so subclasses should + * map this range to their internal range if needed. + * + * A standardized range is useful for different applications. For example: + * - Filter parameters can be easily mapped to gestures since the range is fixed + * - {@link BaseFilter} can use this setters and getters to make a filter copy + */ public interface OneParameterFilter extends Filter { + /** + * Sets the parameter. + * The value should always be between 0 and 1. + * + * @param value parameter + */ void setParameter1(float value); + /** + * Returns the parameter. + * The returned value should always be between 0 and 1. + * + * @return parameter + */ float getParameter1(); } diff --git a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/TwoParameterFilter.java b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/TwoParameterFilter.java index a0a38bfc..8c944ff8 100644 --- a/cameraview/src/main/java/com/otaliastudios/cameraview/filter/TwoParameterFilter.java +++ b/cameraview/src/main/java/com/otaliastudios/cameraview/filter/TwoParameterFilter.java @@ -1,8 +1,31 @@ package com.otaliastudios.cameraview.filter; +/** + * A special {@link Filter} that accepts two floats parameters. + * This is done by extending {@link OneParameterFilter}. + * + * The parameters will always be between 0F and 1F, so subclasses should + * map this range to their internal range if needed. + * + * A standardized range is useful for different applications. For example: + * - Filter parameters can be easily mapped to gestures since the range is fixed + * - {@link BaseFilter} can use this setters and getters to make a filter copy + */ public interface TwoParameterFilter extends OneParameterFilter { + /** + * Sets the second parameter. + * The value should always be between 0 and 1. + * + * @param value parameter + */ void setParameter2(float value); + /** + * Returns the second parameter. + * The returned value should always be between 0 and 1. + * + * @return parameter + */ float getParameter2(); }