1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18 package android.media.effect; 19 20 21 /** 22 * <p>Effects are high-performance transformations that can be applied to image frames. These are 23 * passed in the form of OpenGL ES 2.0 texture names. Typical frames could be images loaded from 24 * disk, or frames from the camera or other video streams.</p> 25 * 26 * <p>To create an Effect you must first create an EffectContext. You can obtain an instance of the 27 * context's EffectFactory by calling 28 * {@link android.media.effect.EffectContext#getFactory() getFactory()}. The EffectFactory allows 29 * you to instantiate specific Effects.</p> 30 * 31 * <p>The application is responsible for creating an EGL context, and making it current before 32 * applying an effect. An effect is bound to a single EffectContext, which in turn is bound to a 33 * single EGL context. If your EGL context is destroyed, the EffectContext becomes invalid and any 34 * effects bound to this context can no longer be used.</p> 35 * 36 */ 37 public abstract class Effect { 38 39 /** 40 * Get the effect name. 41 * 42 * Returns the unique name of the effect, which matches the name used for instantiating this 43 * effect by the EffectFactory. 44 * 45 * @return The name of the effect. 46 */ 47 public abstract String getName(); 48 49 /** 50 * Apply an effect to GL textures. 51 * 52 * <p>Apply the Effect on the specified input GL texture, and write the result into the 53 * output GL texture. The texture names passed must be valid in the current GL context.</p> 54 * 55 * <p>The input texture must be a valid texture name with the given width and height and must be 56 * bound to a GL_TEXTURE_2D texture image (usually done by calling the glTexImage2D() function). 57 * Multiple mipmap levels may be provided.</p> 58 * 59 * <p>If the output texture has not been bound to a texture image, it will be automatically 60 * bound by the effect as a GL_TEXTURE_2D. It will contain one mipmap level (0), which will have 61 * the same size as the input. No other mipmap levels are defined. If the output texture was 62 * bound already, and its size does not match the input texture size, the result may be clipped 63 * or only partially fill the texture.</p> 64 * 65 * <p>Note, that regardless of whether a texture image was originally provided or not, both the 66 * input and output textures are owned by the caller. That is, the caller is responsible for 67 * calling glDeleteTextures() to deallocate the input and output textures.</p> 68 * 69 * @param inputTexId The GL texture name of a valid and bound input texture. 70 * @param width The width of the input texture in pixels. 71 * @param height The height of the input texture in pixels. 72 * @param outputTexId The GL texture name of the output texture. 73 */ 74 public abstract void apply(int inputTexId, int width, int height, int outputTexId); 75 76 /** 77 * Set a filter parameter. 78 * 79 * Consult the effect documentation for a list of supported parameter keys for each effect. 80 * 81 * @param parameterKey The name of the parameter to adjust. 82 * @param value The new value to set the parameter to. 83 * @throws InvalidArgumentException if parameterName is not a recognized name, or the value is 84 * not a valid value for this parameter. 85 */ 86 public abstract void setParameter(String parameterKey, Object value); 87 88 /** 89 * Set an effect listener. 90 * 91 * Some effects may report state changes back to the host, if a listener is set. Consult the 92 * individual effect documentation for more details. 93 * 94 * @param listener The listener to receive update callbacks on. 95 */ 96 public void setUpdateListener(EffectUpdateListener listener) { 97 } 98 99 /** 100 * Release an effect. 101 * 102 * <p>Releases the effect and any resources associated with it. You may call this if you need to 103 * make sure acquired resources are no longer held by the effect. Releasing an effect makes it 104 * invalid for reuse.</p> 105 * 106 * <p>Note that this method must be called with the EffectContext and EGL context current, as 107 * the effect may release internal GL resources.</p> 108 */ 109 public abstract void release(); 110 } 111 112
