165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn/* 265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Copyright (C) 2011 The Android Open Source Project 365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Licensed under the Apache License, Version 2.0 (the "License"); 565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * you may not use this file except in compliance with the License. 665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * You may obtain a copy of the License at 765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * http://www.apache.org/licenses/LICENSE-2.0 965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 1065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Unless required by applicable law or agreed to in writing, software 1165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * distributed under the License is distributed on an "AS IS" BASIS, 1265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * See the License for the specific language governing permissions and 1465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * limitations under the License. 1565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn */ 1665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 1765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 1865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Rennpackage android.media.effect; 1965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 2065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 2165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn/** 2265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>Effects are high-performance transformations that can be applied to image frames. These are 2365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * passed in the form of OpenGL ES 2.0 texture names. Typical frames could be images loaded from 2465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * disk, or frames from the camera or other video streams.</p> 2565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 2665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>To create an Effect you must first create an EffectContext. You can obtain an instance of the 2765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * context's EffectFactory by calling 2865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * {@link android.media.effect.EffectContext#getFactory() getFactory()}. The EffectFactory allows 2965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * you to instantiate specific Effects.</p> 3065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 3165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>The application is responsible for creating an EGL context, and making it current before 3265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * applying an effect. An effect is bound to a single EffectContext, which in turn is bound to a 3365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * single EGL context. If your EGL context is destroyed, the EffectContext becomes invalid and any 3465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * effects bound to this context can no longer be used.</p> 3565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 3665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn */ 3765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Rennpublic abstract class Effect { 3865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 3965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn /** 4065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Get the effect name. 4165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 4265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Returns the unique name of the effect, which matches the name used for instantiating this 4365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * effect by the EffectFactory. 4465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 4565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @return The name of the effect. 4665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn */ 4765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn public abstract String getName(); 4865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 4965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn /** 5065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Apply an effect to GL textures. 5165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 5265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>Apply the Effect on the specified input GL texture, and write the result into the 5365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * output GL texture. The texture names passed must be valid in the current GL context.</p> 5465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 5565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>The input texture must be a valid texture name with the given width and height and must be 5665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * bound to a GL_TEXTURE_2D texture image (usually done by calling the glTexImage2D() function). 5765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Multiple mipmap levels may be provided.</p> 5865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 5965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>If the output texture has not been bound to a texture image, it will be automatically 6065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * bound by the effect as a GL_TEXTURE_2D. It will contain one mipmap level (0), which will have 6165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * the same size as the input. No other mipmap levels are defined. If the output texture was 6265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * bound already, and its size does not match the input texture size, the result may be clipped 6365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * or only partially fill the texture.</p> 6465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 6565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>Note, that regardless of whether a texture image was originally provided or not, both the 6665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * input and output textures are owned by the caller. That is, the caller is responsible for 6765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * calling glDeleteTextures() to deallocate the input and output textures.</p> 6865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 6965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @param inputTexId The GL texture name of a valid and bound input texture. 7065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @param width The width of the input texture in pixels. 7165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @param height The height of the input texture in pixels. 7265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @param outputTexId The GL texture name of the output texture. 7365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn */ 7465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn public abstract void apply(int inputTexId, int width, int height, int outputTexId); 7565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 7665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn /** 7765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Set a filter parameter. 7865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 7965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Consult the effect documentation for a list of supported parameter keys for each effect. 8065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 8165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @param parameterKey The name of the parameter to adjust. 8265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @param value The new value to set the parameter to. 8365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @throws InvalidArgumentException if parameterName is not a recognized name, or the value is 8465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * not a valid value for this parameter. 8565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn */ 8665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn public abstract void setParameter(String parameterKey, Object value); 8765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 8865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn /** 8965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Set an effect listener. 9065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 9165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Some effects may report state changes back to the host, if a listener is set. Consult the 9265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * individual effect documentation for more details. 9365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 9465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * @param listener The listener to receive update callbacks on. 9565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn */ 9665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn public void setUpdateListener(EffectUpdateListener listener) { 9765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn } 9865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 9965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn /** 10065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * Release an effect. 10165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 10265953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>Releases the effect and any resources associated with it. You may call this if you need to 10365953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * make sure acquired resources are no longer held by the effect. Releasing an effect makes it 10465953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * invalid for reuse.</p> 10565953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * 10665953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * <p>Note that this method must be called with the EffectContext and EGL context current, as 10765953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn * the effect may release internal GL resources.</p> 10865953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn */ 10965953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn public abstract void release(); 11065953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn} 11165953da4636fbf5f0a24b8f5f2b5fa7d76ff13d9Marius Renn 112