• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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      */
getName()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      */
apply(int inputTexId, int width, int height, int outputTexId)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      */
setParameter(String parameterKey, Object value)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      */
setUpdateListener(EffectUpdateListener listener)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      */
release()109     public abstract void release();
110 }
111 
112