/ocr/ocrservice/src/com/googlecode/eyesfree/opticflow/FrameProcessor.java

  1/*
  2 * Copyright (C) 2011 Google Inc.
  3 *
  4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
  5 * use this file except in compliance with the License. You may obtain a copy of
  6 * 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, WITHOUT
 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 13 * License for the specific language governing permissions and limitations under
 14 * the License.
 15 */
 16
 17package com.googlecode.eyesfree.opticflow;
 18
 19import android.graphics.Canvas;
 20
 21import com.googlecode.eyesfree.env.Size;
 22import com.googlecode.eyesfree.env.Stopwatch;
 23
 24import java.util.Vector;
 25
 26/**
 27 * Abstract class which defines base functionality of a preview frame processor,
 28 * to be called by PreviewLooper. Frame processors are chained together and may
 29 * use the output of preceeding FrameProcessors. Uses the Template Method design
 30 * pattern to delegate functionality to implementing classes. Modified by Alan
 31 * Viverette from Andrew Harp's original source.
 32 *
 33 * @author Andrew Harp
 34 * @author alanv@google.com (Alan Viverette)
 35 */
 36public abstract class FrameProcessor {
 37    private Stopwatch timer;
 38
 39    private boolean initialized;
 40
 41    private boolean firstFrame;
 42
 43    /**
 44     * @return The amount of time this processor wishes to wait until it sees
 45     *         the next frame.
 46     */
 47    protected final long timeTillNextFrameMillis() {
 48        // No processor should pass up its first frame.
 49        if (firstFrame) {
 50            return 0;
 51        }
 52
 53        // Frame processors have the ability to adjust the result of this method
 54        // by
 55        // modifying what is returned from getTimeBetweenFramesMillis().
 56        return getTimeBetweenFramesMillis() - timer.getElapsedMilliseconds();
 57    }
 58
 59    /**
 60     * Overridable method controlling the rate at which this processor can
 61     * consume frames.
 62     *
 63     * @return The amount of time the frame processor wants to wait between
 64     *         successive calls to processFrame.
 65     */
 66    protected long getTimeBetweenFramesMillis() {
 67        // Greedy by default; always process available frames.
 68        return 0;
 69    }
 70
 71    /**
 72     * Handles per-processor initialization. Guaranteed to be called at least
 73     * once after the camera size is known and before looping starts. May be
 74     * called multiple times. Calls onInit() on child-classes for customized
 75     * implementation.
 76     *
 77     * @param size
 78     */
 79    protected final synchronized void init(final Size size) {
 80        timer = new Stopwatch();
 81        timer.start();
 82
 83        firstFrame = true;
 84        initialized = true;
 85
 86        onInit(size);
 87    }
 88
 89    /**
 90     * @return whether or not this processor has received at least one call to
 91     *         init().
 92     */
 93    protected final boolean isInitialized() {
 94        return initialized;
 95    }
 96
 97    /**
 98     * Frees up any resources consumed by this processor. Calls onShutdown() to
 99     * handle customized cleanup.
100     */
101    protected final synchronized void shutdown() {
102        timer = null;
103        initialized = false;
104
105        onShutdown();
106    }
107
108    /**
109     * Every time processing thread is started, this method is guaranteed to be
110     * called.
111     */
112    protected final synchronized void start() {
113        onStart();
114    }
115
116    /**
117     * Every time processing thread is stopped, this method is guaranteed to be
118     * called.
119     */
120    protected final synchronized void stop() {
121        onStop();
122    }
123
124    /**
125     * Processes an incoming frame. Delegates actual processing to child-class.
126     *
127     * @param frame the frame to process.
128     */
129    protected final synchronized void processFrame(final TimestampedFrame frame) {
130        timer.reset();
131        firstFrame = false;
132
133        onProcessFrame(frame);
134    }
135
136    /**
137     * Overridable method for processors to define their own custom
138     * initialization logic.
139     *
140     * @param size
141     */
142    protected void onInit(final Size size) {
143    }
144
145    /**
146     * Overridable method for processors to define their own custom shutdown
147     * logic.
148     */
149    protected void onShutdown() {
150    }
151
152    /**
153     * Overridable method for processors to define their own custom logic when
154     * they are started. This method is called every time the processing thread
155     * is started and a sequence of frames will arrive at the processor.
156     * onInit() is guaranteed to be called before this method.
157     */
158    protected void onStart() {
159    }
160
161    /**
162     * Overridable method for processors to define their own custom logic when
163     * they are stopped. This method is called every time the processing thread
164     * is stopped and frame processor will not receive frames continuously.
165     * onStart() may be called later when the frame processing thread is
166     * restarted. Different from onShutdown() which is called when a processor
167     * is destroyed, this method may be called several times.
168     */
169    protected void onStop() {
170    }
171
172    /**
173     * The one method that FrameProcessors must implement themselves to do their
174     * customized frame processing.
175     *
176     * @param frame the frame to process.
177     */
178    protected abstract void onProcessFrame(final TimestampedFrame frame);
179
180    /**
181     * Do all debug drawing here.
182     *
183     * @param canvas
184     */
185    protected final void drawDebug(Canvas canvas) {
186        onDrawDebug(canvas);
187    }
188
189    protected void onDrawDebug(Canvas canvas) {
190    }
191
192    protected String getName() {
193        return this.getClass().getSimpleName();
194    }
195
196    /**
197     * @return A vector of strings to show, one per line, for debug purposes.
198     */
199    protected Vector<String> getDebugText() {
200        return new Vector<String>();
201    }
202
203    protected final void preprocessFrame(TimestampedFrame frame) {
204        onPreprocess(frame);
205    }
206
207    protected void onPreprocess(TimestampedFrame frame) {
208    }
209}