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

# 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

# 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 := \

# 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)

/*

 * 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();

}

/*

 * 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]);

    }

}