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.filterfw; 19 20 import android.content.Context; 21 import android.filterfw.core.AsyncRunner; 22 import android.filterfw.core.FilterGraph; 23 import android.filterfw.core.FilterContext; 24 import android.filterfw.core.FrameManager; 25 import android.filterfw.core.GraphRunner; 26 import android.filterfw.core.RoundRobinScheduler; 27 import android.filterfw.core.SyncRunner; 28 import android.filterfw.io.GraphIOException; 29 import android.filterfw.io.GraphReader; 30 import android.filterfw.io.TextGraphReader; 31 32 import java.util.ArrayList; 33 34 /** 35 * A GraphEnvironment provides a simple front-end to filter graph setup and execution using the 36 * mobile filter framework. Typically, you use a GraphEnvironment in the following fashion: 37 * 1. Instantiate a new GraphEnvironment instance. 38 * 2. Perform any configuration, such as adding graph references and setting a GL environment. 39 * 3. Load a graph file using loadGraph() or add a graph using addGraph(). 40 * 4. Obtain a GraphRunner instance using getRunner(). 41 * 5. Execute the obtained runner. 42 * Note that it is possible to add multiple graphs and runners to a single GraphEnvironment. 43 * 44 * @hide 45 */ 46 public class GraphEnvironment extends MffEnvironment { 47 48 public static final int MODE_ASYNCHRONOUS = 1; 49 public static final int MODE_SYNCHRONOUS = 2; 50 51 private GraphReader mGraphReader; 52 private ArrayList<GraphHandle> mGraphs = new ArrayList<GraphHandle>(); 53 54 private class GraphHandle { 55 private FilterGraph mGraph; 56 private AsyncRunner mAsyncRunner; 57 private SyncRunner mSyncRunner; 58 GraphHandle(FilterGraph graph)59 public GraphHandle(FilterGraph graph) { 60 mGraph = graph; 61 } 62 getGraph()63 public FilterGraph getGraph() { 64 return mGraph; 65 } 66 getAsyncRunner(FilterContext environment)67 public AsyncRunner getAsyncRunner(FilterContext environment) { 68 if (mAsyncRunner == null) { 69 mAsyncRunner = new AsyncRunner(environment, RoundRobinScheduler.class); 70 mAsyncRunner.setGraph(mGraph); 71 } 72 return mAsyncRunner; 73 } 74 getSyncRunner(FilterContext environment)75 public GraphRunner getSyncRunner(FilterContext environment) { 76 if (mSyncRunner == null) { 77 mSyncRunner = new SyncRunner(environment, mGraph, RoundRobinScheduler.class); 78 } 79 return mSyncRunner; 80 } 81 } 82 83 /** 84 * Create a new GraphEnvironment with default components. 85 */ GraphEnvironment()86 public GraphEnvironment() { 87 super(null); 88 } 89 90 /** 91 * Create a new GraphEnvironment with a custom FrameManager and GraphReader. Specifying null 92 * for either of these, will auto-create a default instance. 93 * 94 * @param frameManager The FrameManager to use, or null to auto-create one. 95 * @param reader The GraphReader to use for graph loading, or null to auto-create one. 96 * Note, that the reader will not be created until it is required. Pass 97 * null if you will not load any graph files. 98 */ GraphEnvironment(FrameManager frameManager, GraphReader reader)99 public GraphEnvironment(FrameManager frameManager, GraphReader reader) { 100 super(frameManager); 101 mGraphReader = reader; 102 } 103 104 /** 105 * Returns the used graph reader. This will create one, if a reader has not been set already. 106 */ getGraphReader()107 public GraphReader getGraphReader() { 108 if (mGraphReader == null) { 109 mGraphReader = new TextGraphReader(); 110 } 111 return mGraphReader; 112 } 113 114 /** 115 * Add graph references to resolve during graph reading. The references added here are shared 116 * among all graphs. 117 * 118 * @param references An alternating argument list of keys (Strings) and values. 119 */ addReferences(Object... references)120 public void addReferences(Object... references) { 121 getGraphReader().addReferencesByKeysAndValues(references); 122 } 123 124 /** 125 * Loads a graph file from the specified resource and adds it to this environment. 126 * 127 * @param context The context in which to read the resource. 128 * @param resourceId The ID of the graph resource to load. 129 * @return A unique ID for the graph. 130 */ loadGraph(Context context, int resourceId)131 public int loadGraph(Context context, int resourceId) { 132 // Read the file into a graph 133 FilterGraph graph = null; 134 try { 135 graph = getGraphReader().readGraphResource(context, resourceId); 136 } catch (GraphIOException e) { 137 throw new RuntimeException("Could not read graph: " + e.getMessage()); 138 } 139 140 // Add graph to our list of graphs 141 return addGraph(graph); 142 } 143 144 /** 145 * Add a graph to the environment. Consider using loadGraph() if you are loading a graph from 146 * a graph file. 147 * 148 * @param graph The graph to add to the environment. 149 * @return A unique ID for the added graph. 150 */ addGraph(FilterGraph graph)151 public int addGraph(FilterGraph graph) { 152 GraphHandle graphHandle = new GraphHandle(graph); 153 mGraphs.add(graphHandle); 154 return mGraphs.size() - 1; 155 } 156 157 /** 158 * Access a specific graph of this environment given a graph ID (previously returned from 159 * loadGraph() or addGraph()). Throws an InvalidArgumentException if no graph with the 160 * specified ID could be found. 161 * 162 * @param graphId The ID of the graph to get. 163 * @return The graph with the specified ID. 164 */ getGraph(int graphId)165 public FilterGraph getGraph(int graphId) { 166 if (graphId < 0 || graphId >= mGraphs.size()) { 167 throw new IllegalArgumentException( 168 "Invalid graph ID " + graphId + " specified in runGraph()!"); 169 } 170 return mGraphs.get(graphId).getGraph(); 171 } 172 173 /** 174 * Get a GraphRunner instance for the graph with the specified ID. The GraphRunner instance can 175 * be used to execute the graph. Throws an InvalidArgumentException if no graph with the 176 * specified ID could be found. 177 * 178 * @param graphId The ID of the graph to get. 179 * @param executionMode The mode of graph execution. Currently this can be either 180 MODE_SYNCHRONOUS or MODE_ASYNCHRONOUS. 181 * @return A GraphRunner instance for this graph. 182 */ getRunner(int graphId, int executionMode)183 public GraphRunner getRunner(int graphId, int executionMode) { 184 switch (executionMode) { 185 case MODE_ASYNCHRONOUS: 186 return mGraphs.get(graphId).getAsyncRunner(getContext()); 187 188 case MODE_SYNCHRONOUS: 189 return mGraphs.get(graphId).getSyncRunner(getContext()); 190 191 default: 192 throw new RuntimeException( 193 "Invalid execution mode " + executionMode + " specified in getRunner()!"); 194 } 195 } 196 197 } 198