Multi-Project Commit: Move of filterfw out of system/media (2 of 7)

This is part of the multi-project commit to move the filter-framework
from system/media/mca to frameworks/base/media/mca.

Note that the filter-framework will soon be replaced with a refactored
version currently under API review (also to go under frameworks/base).
This move is done now to unblock the PDK efforts.

Change-Id: I9f42be5a12a9e8157512be11f04e38e4548970be

Author: mrenn

Android.mk

@@ -324,9 +324,6 @@ fwbase_dirs_to_document := \
 # include definition of libcore_to_document
 include $(LOCAL_PATH)/../../libcore/Docs.mk
 
-# include definition of libfilterfw_to_document
-include $(LOCAL_PATH)/../../system/media/mca/Docs.mk
-
 non_base_dirs := \
 	../../external/apache-http/src/org/apache/http
 
@@ -349,8 +346,7 @@ html_dirs := \
 # Common sources for doc check and api check
 common_src_files := \
 	$(call find-other-html-files, $(html_dirs)) \
-	$(addprefix ../../libcore/, $(call libcore_to_document, $(LOCAL_PATH)/../../libcore)) \
-	$(addprefix ../../system/media/mca/, $(call libfilterfw_to_document, $(LOCAL_PATH)/../../system/media/mca)) \
+	$(addprefix ../../libcore/, $(call libcore_to_document, $(LOCAL_PATH)/../../libcore))
 
 # These are relative to frameworks/base
 framework_docs_LOCAL_SRC_FILES := \

media/mca/Android.mk

@@ -0,0 +1,21 @@
+# 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.
+#
+
+#
+# Build all native libraries
+#
+include $(call all-subdir-makefiles)
+
+

media/mca/effect/java/android/media/effect/Effect.java

@@ -0,0 +1,111 @@
+/*
+ * 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;
+
+
+/**
+ * <p>Effects are high-performance transformations that can be applied to image frames. These are
+ * passed in the form of OpenGL ES 2.0 texture names. Typical frames could be images loaded from
+ * disk, or frames from the camera or other video streams.</p>
+ *
+ * <p>To create an Effect you must first create an EffectContext. You can obtain an instance of the
+ * context's EffectFactory by calling
+ * {@link android.media.effect.EffectContext#getFactory() getFactory()}. The EffectFactory allows
+ * you to instantiate specific Effects.</p>
+ *
+ * <p>The application is responsible for creating an EGL context, and making it current before
+ * applying an effect. An effect is bound to a single EffectContext, which in turn is bound to a
+ * single EGL context. If your EGL context is destroyed, the EffectContext becomes invalid and any
+ * effects bound to this context can no longer be used.</p>
+ *
+ */
+public abstract class Effect {
+
+    /**
+     * Get the effect name.
+     *
+     * Returns the unique name of the effect, which matches the name used for instantiating this
+     * effect by the EffectFactory.
+     *
+     * @return The name of the effect.
+     */
+    public abstract String getName();
+
+    /**
+     * Apply an effect to GL textures.
+     *
+     * <p>Apply the Effect on the specified input GL texture, and write the result into the
+     * output GL texture. The texture names passed must be valid in the current GL context.</p>
+     *
+     * <p>The input texture must be a valid texture name with the given width and height and must be
+     * bound to a GL_TEXTURE_2D texture image (usually done by calling the glTexImage2D() function).
+     * Multiple mipmap levels may be provided.</p>
+     *
+     * <p>If the output texture has not been bound to a texture image, it will be automatically
+     * bound by the effect as a GL_TEXTURE_2D. It will contain one mipmap level (0), which will have
+     * the same size as the input. No other mipmap levels are defined. If the output texture was
+     * bound already, and its size does not match the input texture size, the result may be clipped
+     * or only partially fill the texture.</p>
+     *
+     * <p>Note, that regardless of whether a texture image was originally provided or not, both the
+     * input and output textures are owned by the caller. That is, the caller is responsible for
+     * calling glDeleteTextures() to deallocate the input and output textures.</p>
+     *
+     * @param inputTexId The GL texture name of a valid and bound input texture.
+     * @param width The width of the input texture in pixels.
+     * @param height The height of the input texture in pixels.
+     * @param outputTexId The GL texture name of the output texture.
+     */
+    public abstract void apply(int inputTexId, int width, int height, int outputTexId);
+
+    /**
+     * Set a filter parameter.
+     *
+     * Consult the effect documentation for a list of supported parameter keys for each effect.
+     *
+     * @param parameterKey The name of the parameter to adjust.
+     * @param value The new value to set the parameter to.
+     * @throws InvalidArgumentException if parameterName is not a recognized name, or the value is
+     *         not a valid value for this parameter.
+     */
+    public abstract void setParameter(String parameterKey, Object value);
+
+    /**
+     * Set an effect listener.
+     *
+     * Some effects may report state changes back to the host, if a listener is set. Consult the
+     * individual effect documentation for more details.
+     *
+     * @param listener The listener to receive update callbacks on.
+     */
+    public void setUpdateListener(EffectUpdateListener listener) {
+    }
+
+    /**
+     * Release an effect.
+     *
+     * <p>Releases the effect and any resources associated with it. You may call this if you need to
+     * make sure acquired resources are no longer held by the effect. Releasing an effect makes it
+     * invalid for reuse.</p>
+     *
+     * <p>Note that this method must be called with the EffectContext and EGL context current, as
+     * the effect may release internal GL resources.</p>
+     */
+    public abstract void release();
+}
+

media/mca/effect/java/android/media/effect/EffectContext.java

@@ -0,0 +1,131 @@
+/*
+ * 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 android.filterfw.core.CachedFrameManager;
+import android.filterfw.core.FilterContext;
+import android.filterfw.core.FilterFactory;
+import android.filterfw.core.GLEnvironment;
+import android.filterfw.core.GLFrame;
+import android.filterfw.core.FrameManager;
+import android.opengl.GLES20;
+
+/**
+ * <p>An EffectContext keeps all necessary state information to run Effects within a Open GL ES 2.0
+ * context.</p>
+ *
+ * <p>Every EffectContext is bound to one GL context. The application is responsible for creating
+ * this EGL context, and making it current before applying any effect. If your EGL context is
+ * destroyed, the EffectContext becomes invalid and any effects bound to this context can no longer
+ * be used. If you switch to another EGL context, you must create a new EffectContext. Each Effect
+ * is bound to a single EffectContext, and can only be executed in that context.</p>
+ */
+public class EffectContext {
+
+    private final int GL_STATE_FBO          = 0;
+    private final int GL_STATE_PROGRAM      = 1;
+    private final int GL_STATE_ARRAYBUFFER  = 2;
+    private final int GL_STATE_COUNT        = 3;
+
+    FilterContext mFilterContext;
+
+    private EffectFactory mFactory;
+
+    private int[] mOldState = new int[GL_STATE_COUNT];
+
+    /**
+     * Creates a context within the current GL context.
+     *
+     * <p>Binds the EffectContext to the current OpenGL context. All subsequent calls to the
+     * EffectContext must be made in the GL context that was active during creation.
+     * When you have finished using a context, you must call {@link #release()}. to dispose of all
+     * resources associated with this context.</p>
+     */
+    public static EffectContext createWithCurrentGlContext() {
+        EffectContext result = new EffectContext();
+        result.initInCurrentGlContext();
+        return result;
+    }
+
+    /**
+     * Returns the EffectFactory for this context.
+     *
+     * <p>The EffectFactory returned from this method allows instantiating new effects within this
+     * context.</p>
+     *
+     * @return The EffectFactory instance for this context.
+     */
+    public EffectFactory getFactory() {
+        return mFactory;
+    }
+
+    /**
+     * Releases the context.
+     *
+     * <p>Releases all the resources and effects associated with the EffectContext. This renders the
+     * context and all the effects bound to this context invalid. You must no longer use the context
+     * or any of its bound effects after calling release().</p>
+     *
+     * <p>Note that this method must be called with the proper EGL context made current, as the
+     * EffectContext and its effects may release internal GL resources.</p>
+     */
+    public void release() {
+        mFilterContext.tearDown();
+        mFilterContext = null;
+    }
+
+    private EffectContext() {
+        mFilterContext = new FilterContext();
+        mFilterContext.setFrameManager(new CachedFrameManager());
+        mFactory = new EffectFactory(this);
+    }
+
+    private void initInCurrentGlContext() {
+        if (!GLEnvironment.isAnyContextActive()) {
+            throw new RuntimeException("Attempting to initialize EffectContext with no active "
+                + "GL context!");
+        }
+        GLEnvironment glEnvironment = new GLEnvironment();
+        glEnvironment.initWithCurrentContext();
+        mFilterContext.initGLEnvironment(glEnvironment);
+    }
+
+    final void assertValidGLState() {
+        GLEnvironment glEnv = mFilterContext.getGLEnvironment();
+        if (glEnv == null || !glEnv.isContextActive()) {
+            if (GLEnvironment.isAnyContextActive()) {
+                throw new RuntimeException("Applying effect in wrong GL context!");
+            } else {
+                throw new RuntimeException("Attempting to apply effect without valid GL context!");
+            }
+        }
+    }
+
+    final void saveGLState() {
+        GLES20.glGetIntegerv(GLES20.GL_FRAMEBUFFER_BINDING, mOldState, GL_STATE_FBO);
+        GLES20.glGetIntegerv(GLES20.GL_CURRENT_PROGRAM, mOldState, GL_STATE_PROGRAM);
+        GLES20.glGetIntegerv(GLES20.GL_ARRAY_BUFFER_BINDING, mOldState, GL_STATE_ARRAYBUFFER);
+    }
+
+    final void restoreGLState() {
+        GLES20.glBindFramebuffer(GLES20.GL_FRAMEBUFFER, mOldState[GL_STATE_FBO]);
+        GLES20.glUseProgram(mOldState[GL_STATE_PROGRAM]);
+        GLES20.glBindBuffer(GLES20.GL_ARRAY_BUFFER, mOldState[GL_STATE_ARRAYBUFFER]);
+    }
+}
+