src.android.media.effect.EffectFactory Maven / Gradle / Ivy

Go to download
/*
 * Copyright (C) 2011 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package android.media.effect;

import java.lang.reflect.Constructor;

/**
 * The EffectFactory class defines the list of available Effects, and provides functionality to
 * inspect and instantiate them. Some effects may not be available on all platforms, so before
 * creating a certain effect, the application should confirm that the effect is supported on this
 * platform by calling {@link #isEffectSupported(String)}.
 */
public class EffectFactory {

    private EffectContext mEffectContext;

    private final static String[] EFFECT_PACKAGES = {
        "android.media.effect.effects.",  // Default effect package
        ""                                // Allows specifying full class path
    };

    /** List of Effects */
    /**
     * Copies the input texture to the output.
     * Available parameters: None
     * @hide
     */
    public final static String EFFECT_IDENTITY = "IdentityEffect";

    /**
     * Adjusts the brightness of the image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
brightness The brightness multiplier. Positive float. 1.0 means no change;
               larger values will increase brightness.
     */
    public final static String EFFECT_BRIGHTNESS =
            "android.media.effect.effects.BrightnessEffect";

    /**
     * Adjusts the contrast of the image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
contrast The contrast multiplier. Float. 1.0 means no change;
               larger values will increase contrast.
     */
    public final static String EFFECT_CONTRAST =
            "android.media.effect.effects.ContrastEffect";

    /**
     * Applies a fisheye lens distortion to the image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
scale The scale of the distortion. Float, between 0 and 1. Zero means no distortion.
     */
    public final static String EFFECT_FISHEYE =
            "android.media.effect.effects.FisheyeEffect";

    /**
     * Replaces the background of the input frames with frames from a
     * selected video.  Requires an initial learning period with only the
     * background visible before the effect becomes active. The effect will wait
     * until it does not see any motion in the scene before learning the
     * background and starting the effect.
     *
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
source A URI for the background video to use. This parameter must be
     *         supplied before calling apply() for the first time. String, such as from
     *         {@link android.net.Uri#toString Uri.toString()}
     *
     * If the update listener is set for this effect using
     * {@link Effect#setUpdateListener}, it will be called when the effect has
     * finished learning the background, with a null value for the info
     * parameter.
     */
    public final static String EFFECT_BACKDROPPER =
            "android.media.effect.effects.BackDropperEffect";

    /**
     * Attempts to auto-fix the image based on histogram equalization.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
scale The scale of the adjustment. Float, between 0 and 1. Zero means no adjustment, while 1 indicates the maximum
     *     amount of adjustment.
     */
    public final static String EFFECT_AUTOFIX =
            "android.media.effect.effects.AutoFixEffect";

    /**
     * Adjusts the range of minimal and maximal color pixel intensities.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
black The value of the minimal pixel. Float, between 0 and 1.
white The value of the maximal pixel. Float, between 0 and 1.
     */
    public final static String EFFECT_BLACKWHITE =
            "android.media.effect.effects.BlackWhiteEffect";

    /**
     * Crops an upright rectangular area from the image. If the crop region falls outside of
     * the image bounds, the results are undefined.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * 
     *     
     *     
     * 
     * 
     *     
     *     
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
xorigin The origin's x-value. Integer, between 0 and width of the image.
yorigin The origin's y-value. Integer, between 0 and height of the image.
width The width of the cropped image. Integer, between 1 and the width of the image minus xorigin.
height The height of the cropped image. Integer, between 1 and the height of the image minus yorigin.
     */
    public final static String EFFECT_CROP =
            "android.media.effect.effects.CropEffect";

    /**
     * Applies a cross process effect on image, in which the red and green channels are
     * enhanced while the blue channel is restricted.
     * Available parameters: None
     */
    public final static String EFFECT_CROSSPROCESS =
            "android.media.effect.effects.CrossProcessEffect";

    /**
     * Applies black and white documentary style effect on image..
     * Available parameters: None
     */
    public final static String EFFECT_DOCUMENTARY =
            "android.media.effect.effects.DocumentaryEffect";


    /**
     * Overlays a bitmap (with premultiplied alpha channel) onto the input image. The bitmap
     * is stretched to fit the input image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
bitmap The overlay bitmap. A non-null Bitmap instance.
     */
    public final static String EFFECT_BITMAPOVERLAY =
            "android.media.effect.effects.BitmapOverlayEffect";

    /**
     * Representation of photo using only two color tones.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
first_color The first color tone. Integer, representing an ARGB color with 8 bits per channel. May be created using
     *     {@link android.graphics.Color Color} class.
second_color The second color tone. Integer, representing an ARGB color with 8 bits per channel. May be created using
     *     {@link android.graphics.Color Color} class.
     */
    public final static String EFFECT_DUOTONE =
            "android.media.effect.effects.DuotoneEffect";

    /**
     * Applies back-light filling to the image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
strength The strength of the backlight. Float, between 0 and 1. Zero means no change.
     */
    public final static String EFFECT_FILLLIGHT =
            "android.media.effect.effects.FillLightEffect";

    /**
     * Flips image vertically and/or horizontally.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
vertical Whether to flip image vertically. Boolean
horizontal Whether to flip image horizontally. Boolean
     */
    public final static String EFFECT_FLIP =
            "android.media.effect.effects.FlipEffect";

    /**
     * Applies film grain effect to image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
strength The strength of the grain effect. Float, between 0 and 1. Zero means no change.
     */
    public final static String EFFECT_GRAIN =
            "android.media.effect.effects.GrainEffect";

    /**
     * Converts image to grayscale.
     * Available parameters: None
     */
    public final static String EFFECT_GRAYSCALE =
            "android.media.effect.effects.GrayscaleEffect";

    /**
     * Applies lomo-camera style effect to image.
     * Available parameters: None
     */
    public final static String EFFECT_LOMOISH =
            "android.media.effect.effects.LomoishEffect";

    /**
     * Inverts the image colors.
     * Available parameters: None
     */
    public final static String EFFECT_NEGATIVE =
            "android.media.effect.effects.NegativeEffect";

    /**
     * Applies posterization effect to image.
     * Available parameters: None
     */
    public final static String EFFECT_POSTERIZE =
            "android.media.effect.effects.PosterizeEffect";

    /**
     * Removes red eyes on specified region.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
centers Multiple center points (x, y) of the red eye regions. An array of floats, where (f[2*i], f[2*i+1]) specifies the center of the i'th eye.
     *     Coordinate values are expected to be normalized between 0 and 1.
     */
    public final static String EFFECT_REDEYE =
            "android.media.effect.effects.RedEyeEffect";

    /**
     * Rotates the image. The output frame size must be able to fit the rotated version of
     * the input image. Note that the rotation snaps to a the closest multiple of 90 degrees.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
angle The angle of rotation in degrees. Integer value. This will be rounded to the nearest multiple of 90.
     */
    public final static String EFFECT_ROTATE =
            "android.media.effect.effects.RotateEffect";

    /**
     * Adjusts color saturation of image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
scale The scale of color saturation. Float, between -1 and 1. 0 means no change, while -1 indicates full desaturation,
     *     i.e. grayscale.
     */
    public final static String EFFECT_SATURATE =
            "android.media.effect.effects.SaturateEffect";

    /**
     * Converts image to sepia tone.
     * Available parameters: None
     */
    public final static String EFFECT_SEPIA =
            "android.media.effect.effects.SepiaEffect";

    /**
     * Sharpens the image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
scale The degree of sharpening. Float, between 0 and 1. 0 means no change.
     */
    public final static String EFFECT_SHARPEN =
            "android.media.effect.effects.SharpenEffect";

    /**
     * Rotates the image according to the specified angle, and crops the image so that no
     * non-image portions are visible.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
angle The angle of rotation. Float, between -45 and +45.
     */
    public final static String EFFECT_STRAIGHTEN =
            "android.media.effect.effects.StraightenEffect";

    /**
     * Adjusts color temperature of the image.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
scale The value of color temperature. Float, between 0 and 1, with 0 indicating cool, and 1 indicating warm. A value of
     *     of 0.5 indicates no change.
     */
    public final static String EFFECT_TEMPERATURE =
            "android.media.effect.effects.ColorTemperatureEffect";

    /**
     * Tints the photo with specified color.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
tint The color of the tint. Integer, representing an ARGB color with 8 bits per channel. May be created using
     *     {@link android.graphics.Color Color} class.
     */
    public final static String EFFECT_TINT =
            "android.media.effect.effects.TintEffect";

    /**
     * Adds a vignette effect to image, i.e. fades away the outer image edges.
     * Available parameters:
     * 
     * 
     * 
     *     
     *     
     * 
     * Parameter name Meaning Valid values
scale The scale of vignetting. Float, between 0 and 1. 0 means no change.
     */
    public final static String EFFECT_VIGNETTE =
            "android.media.effect.effects.VignetteEffect";

    EffectFactory(EffectContext effectContext) {
        mEffectContext = effectContext;
    }

    /**
     * Instantiate a new effect with the given effect name.
     *
     * The effect's parameters will be set to their default values.
     *
     * Note that the EGL context associated with the current EffectContext need not be made
     * current when creating an effect. This allows the host application to instantiate effects
     * before any EGL context has become current.
     *
     * @param effectName The name of the effect to create.
     * @return A new Effect instance.
     * @throws IllegalArgumentException if the effect with the specified name is not supported or
     *         not known.
     */
    public Effect createEffect(String effectName) {
        Class effectClass = getEffectClassByName(effectName);
        if (effectClass == null) {
            throw new IllegalArgumentException("Cannot instantiate unknown effect '" +
                effectName + "'!");
        }
        return instantiateEffect(effectClass, effectName);
    }

    /**
     * Check if an effect is supported on this platform.
     *
     * Some effects may only be available on certain platforms. Use this method before
     * instantiating an effect to make sure it is supported.
     *
     * @param effectName The name of the effect.
     * @return true, if the effect is supported on this platform.
     * @throws IllegalArgumentException if the effect name is not known.
     */
    public static boolean isEffectSupported(String effectName) {
        return getEffectClassByName(effectName) != null;
    }

    private static Class getEffectClassByName(String className) {
        Class effectClass = null;

        // Get context's classloader; otherwise cannot load non-framework effects
        ClassLoader contextClassLoader = Thread.currentThread().getContextClassLoader();

        // Look for the class in the imported packages
        for (String packageName : EFFECT_PACKAGES) {
            try {
                effectClass = contextClassLoader.loadClass(packageName + className);
            } catch (ClassNotFoundException e) {
                continue;
            }
            // Exit loop if class was found.
            if (effectClass != null) {
                break;
            }
        }
        return effectClass;
    }

    private Effect instantiateEffect(Class effectClass, String name) {
        // Make sure this is an Effect subclass
        try {
            effectClass.asSubclass(Effect.class);
        } catch (ClassCastException e) {
            throw new IllegalArgumentException("Attempting to allocate effect '" + effectClass
                + "' which is not a subclass of Effect!", e);
        }

        // Look for the correct constructor
        Constructor effectConstructor = null;
        try {
            effectConstructor = effectClass.getConstructor(EffectContext.class, String.class);
        } catch (NoSuchMethodException e) {
            throw new RuntimeException("The effect class '" + effectClass + "' does not have "
                + "the required constructor.", e);
        }

        // Construct the effect
        Effect effect = null;
        try {
            effect = (Effect)effectConstructor.newInstance(mEffectContext, name);
        } catch (Throwable t) {
            throw new RuntimeException("There was an error constructing the effect '" + effectClass
                + "'!", t);
        }

        return effect;
    }
}
Parameter name	Meaning	Valid values
`brightness`	The brightness multiplier.	Positive float. 1.0 means no change; larger values will increase brightness.