Improve comments

pull/535/head
Mattia Iavarone 6 years ago
parent 5ffdbc5713
commit b24acde126
  1. 13
      cameraview/src/main/java/com/otaliastudios/cameraview/filter/BaseFilter.java
  2. 9
      cameraview/src/main/java/com/otaliastudios/cameraview/filter/Filter.java
  3. 22
      cameraview/src/main/java/com/otaliastudios/cameraview/filter/OneParameterFilter.java
  4. 23
      cameraview/src/main/java/com/otaliastudios/cameraview/filter/TwoParameterFilter.java

@ -12,28 +12,31 @@ import java.nio.FloatBuffer;
/** /**
* A base implementation of {@link Filter} that just leaves the fragment shader to subclasses. * 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 * 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 * to be changed. Most effects can be rendered by simply changing the fragment shader, thus
* by overriding {@link #getFragmentShader()}. * 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 #vertexPositionName}
* - {@link #vertexTransformMatrixName} * - {@link #vertexTransformMatrixName}
* - {@link #vertexModelViewProjectionMatrixName} * - {@link #vertexModelViewProjectionMatrixName}
* - {@link #vertexTextureCoordinateName} * - {@link #vertexTextureCoordinateName}
* - {@link #fragmentTextureCoordinateName} * - {@link #fragmentTextureCoordinateName}
*
* You can either change these variables, for example in your constructor, or change your * You can either change these variables, for example in your constructor, or change your
* vertex and fragment shader code to use them. * 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: * NOTE - the {@link android.graphics.SurfaceTexture} restrictions apply:
* We only support the {@link android.opengl.GLES11Ext#GL_TEXTURE_EXTERNAL_OES} texture target * 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. * 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)}. * You also have to explicitly require the extension: see {@link #createDefaultFragmentShader(String)}.
*
*/ */
public abstract class BaseFilter implements Filter { public abstract class BaseFilter implements Filter {

@ -18,6 +18,14 @@ import java.io.File;
* *
* Advanced users can create custom filters using GLES. * Advanced users can create custom filters using GLES.
* It is recommended to extend {@link BaseFilter} instead of this class. * 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 { public interface Filter {
@ -65,6 +73,7 @@ public interface Filter {
/** /**
* Called anytime the output size changes. * Called anytime the output size changes.
*
* @param width width * @param width width
* @param height height * @param height height
*/ */

@ -1,8 +1,30 @@
package com.otaliastudios.cameraview.filter; 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 { public interface OneParameterFilter extends Filter {
/**
* Sets the parameter.
* The value should always be between 0 and 1.
*
* @param value parameter
*/
void setParameter1(float value); void setParameter1(float value);
/**
* Returns the parameter.
* The returned value should always be between 0 and 1.
*
* @return parameter
*/
float getParameter1(); float getParameter1();
} }

@ -1,8 +1,31 @@
package com.otaliastudios.cameraview.filter; 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 { 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); void setParameter2(float value);
/**
* Returns the second parameter.
* The returned value should always be between 0 and 1.
*
* @return parameter
*/
float getParameter2(); float getParameter2();
} }

Loading…
Cancel
Save