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
18package android.filterfw.core;
19
20/**
21 * @hide
22 */
23public abstract class GraphRunner {
24
25    protected FilterContext mFilterContext = null;
26
27    /** Interface for listeners waiting for the runner to complete. */
28    public interface OnRunnerDoneListener {
29        /** Callback method to be called when the runner completes a
30         * {@link #run()} call.
31         *
32         * @param result will be RESULT_FINISHED if the graph finished running
33         *        on its own, RESULT_STOPPED if the runner was stopped by a call
34         *        to stop(), RESULT_BLOCKED if no filters could run due to lack
35         *        of inputs or outputs or due to scheduling policies, and
36         *        RESULT_SLEEPING if a filter node requested sleep.
37         */
38        public void onRunnerDone(int result);
39    }
40
41    public static final int RESULT_UNKNOWN  = 0;
42    public static final int RESULT_RUNNING  = 1;
43    public static final int RESULT_FINISHED = 2;
44    public static final int RESULT_SLEEPING = 3;
45    public static final int RESULT_BLOCKED  = 4;
46    public static final int RESULT_STOPPED  = 5;
47    public static final int RESULT_ERROR    = 6;
48
49    public GraphRunner(FilterContext context) {
50        mFilterContext = context;
51    }
52
53    public abstract FilterGraph getGraph();
54
55    public FilterContext getContext() {
56        return mFilterContext;
57    }
58
59    /**
60     * Helper function for subclasses to activate the GL environment before running.
61     * @return true, if the GL environment was activated. Returns false, if the GL environment
62     *         was already active.
63     */
64    protected boolean activateGlContext() {
65        GLEnvironment glEnv = mFilterContext.getGLEnvironment();
66        if (glEnv != null && !glEnv.isActive()) {
67            glEnv.activate();
68            return true;
69        }
70        return false;
71    }
72
73    /**
74     * Helper function for subclasses to deactivate the GL environment after running.
75     */
76    protected void deactivateGlContext() {
77        GLEnvironment glEnv = mFilterContext.getGLEnvironment();
78        if (glEnv != null) {
79            glEnv.deactivate();
80        }
81    }
82
83    /** Starts running the graph. Will open the filters in the graph if they are not already open. */
84    public abstract void run();
85
86    public abstract void setDoneCallback(OnRunnerDoneListener listener);
87    public abstract boolean isRunning();
88
89    /** Stops graph execution. As part of stopping, also closes the graph nodes. */
90    public abstract void stop();
91
92    /** Closes the filters in a graph. Can only be called if the graph is not running. */
93    public abstract void close();
94
95    /**
96     * Returns the last exception that happened during an asynchronous run. Returns null if
97     * there is nothing to report.
98     */
99    public abstract Exception getError();
100}
101