1/*
2 * Copyright (C) 2014 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
17package com.android.camera.processing.imagebackend;
18
19import com.google.common.base.Optional;
20
21import com.android.camera.session.CaptureSession;
22
23import java.util.Set;
24import java.util.concurrent.Executor;
25
26import javax.annotation.Nullable;
27
28/**
29 * Defines interface between an ImageBackend object and a simplified camera
30 * object that merely delivers images to the backend. After the tasks and
31 * Android image is submitted to the ImageConsumer, the responsibility to close
32 * on the Android image object as early as possible is transferred to the
33 * implementation. Whether an image can be submitted again for process is up to
34 * the implementation of the consumer. For integration of Camera Application, we
35 * now pass in the CaptureSession in order to properly update filmstrip and UI.
36 * More generalized versions of functions of this interface allow a Runnable to
37 * be executed when the set of events and any spawned events have completed
38 * processing.
39 */
40public interface ImageConsumer {
41
42    /**
43     * ImageTaskFlags specifies the current tasks that will be run with an
44     * image.
45     * <ol>
46     * <li>CREATE_EARLY_FILMSTRIP_PREVIEW: Subsamples a YUV Image and converts
47     * it to an ARGB Image with nearly similar aspect ratio. ONLY Valid when
48     * specified with COMPRESS_TO_JPEG_AND_WRITE_TO_DISK. Otherwise, ignored.</li>
49     * <li>COMPRESS_TO_JPEG_AND_WRITE_TO_DISK: Compresses an YUV/JPEG Image to
50     * JPEG (when necessary), delivers the compressed artifact via the listener,
51     * and writes it to disk.</li>
52     * <li>CONVERT_TO_RGB_PREVIEW: Subsamples a YUV Image and converts the
53     * uncompressed output to ARGB image inset within a circle</li>
54     * <li>BLOCK_UNTIL_ALL_TASKS_RELEASE: Block on ReceiveImage call until image
55     * is released.</li>
56     * <li>CLOSE_ON_ALL_TASKS_RELEASE: Close the ImageProxy on ReceiveImage Call
57     * when all tasks release their image</li>
58     * </ol>
59     */
60    public enum ImageTaskFlags {
61        CREATE_EARLY_FILMSTRIP_PREVIEW,
62        COMPRESS_TO_JPEG_AND_WRITE_TO_DISK,
63        CONVERT_TO_RGB_PREVIEW,
64        BLOCK_UNTIL_ALL_TASKS_RELEASE,
65        CLOSE_ON_ALL_TASKS_RELEASE
66    }
67
68    /**
69     * Provides the basic functionality of camera processing via an easy-to-use
70     * method call.  Feel free to expand this implementation by increasing the
71     * types of common tasks in the enum ImageTaskFlags.  This version of the call
72     * also automatically registers at time of task submission and unregisters
73     * the listener at the time when all tasks and associated spawned tasks have
74     * completed their processing.
75     *
76     * @param img image to be processed
77     * @param executor The executor on which to execute events and image close
78     * @param processingFlags {@see ImageTaskFlags}
79     * @param imageProcessorListener Optional listener to automatically register
80     *            at task submission and unregister after all tasks are done
81     * @return Whether any tasks were actually added.
82     * @throws InterruptedException occurs when call is set to be blocking and
83     *             is interrupted.
84     */
85    public boolean receiveImage(ImageToProcess img, Executor executor,
86            Set<ImageTaskFlags> processingFlags, CaptureSession captureSession,
87            Optional<ImageProcessorListener> imageProcessorListener)
88            throws InterruptedException;
89
90    /**
91     * Provides the basic functionality of camera processing via an easy-to-use
92     * method call w/o a listener to be released.
93     *
94     * @param img image to be processed
95     * @param executor executor on which to execute events and image close
96     * @param processingFlags {@see ImageTaskFlags}
97     * @return Whether any tasks were actually added.
98     * @throws InterruptedException occurs when call is set to be blocking and
99     *             is interrupted.
100     */
101    /*
102    public boolean receiveImage(ImageToProcess img, Executor executor,
103            Set<ImageTaskFlags> processingFlags, CaptureSession captureSession)
104            throws InterruptedException;
105            */
106
107    /**
108     * Provides the basic functionality of camera processing via a more general-
109     * purpose method call. Tasks can be extended off of the TaskImageContainer,
110     * or created from factory method provided by implementation.
111     *
112     * @param img image to be processed
113     * @param sharedTask a single task to be run
114     * @param blockOnImageRelease If true, call blocks until the object img is
115     *            no longer referred by any task. If false, call is non-blocking
116     * @param closeOnImageRelease If true, images is closed when the object img
117     *            is is no longer referred by any task. If false,
118     * @param runnableWhenDone Optional runnable to be executed when the task is
119     *            done.
120     * @return Whether the blocking completed properly. If false, there may be a
121     *         need to clean up image closes manually.
122     * @throws InterruptedException occurs when call is set to be blocking and
123     *             is interrupted.
124     */
125
126    public boolean receiveImage(ImageToProcess img, TaskImageContainer sharedTask,
127            boolean blockOnImageRelease, boolean closeOnImageRelease,
128            Optional<Runnable> runnableWhenDone)
129            throws InterruptedException;
130
131    /**
132     * Provides the basic functionality of camera processing via a more general-
133     * purpose method call w/o a Runnable to be executed when the task is done.
134     * Tasks can be extended off of the TaskImageContainer, or created from
135     * factory method provided by implementation.
136     *
137     * @param img image to be processed.
138     * @param sharedTask a single task to be run.
139     * @param blockOnImageRelease If true, call blocks until the object img is
140     *            no longer referred by any task. If false, call is non-blocking
141     * @param closeOnImageRelease If true, images is closed when the object img
142     *            is is no longer referred by any task. If false,
143     * @return Whether the blocking completed properly. If false, there may be a
144     *         need to clean up image closes manually.
145     * @throws InterruptedException occurs when call is set to be blocking and
146     *             is interrupted.
147     */
148    @Deprecated
149    public boolean receiveImage(ImageToProcess img, TaskImageContainer sharedTask,
150            boolean blockOnImageRelease, boolean closeOnImageRelease)
151            throws InterruptedException;
152
153    /**
154     * Provides the basic functionality of camera processing via the most
155     * general- purpose method call. Tasks can be extended off of the
156     * TaskImageContainer, or created from factory method provided by the
157     * implementation.
158     *
159     * @param img image to be processed.
160     * @param sharedTasks Set of tasks to be run on the given image.
161     * @param blockOnImageRelease If true, call blocks until the object img is
162     *            no longer referred by any task. If false, call is non-blocking
163     * @param closeOnImageRelease If true, images is closed when the object img
164     *            is is no longer referred by any task. If false, close is not
165     *            called on release.
166     * @param runnableWhenDone optional runnable to be executed when the set of
167     *            tasks are done.
168     * @return Whether the blocking completed properly. If false, there may be a
169     *         need to clean up image closes manually.
170     * @throws InterruptedException occurs when call is set to be blocking and
171     *             is interrupted.
172     */
173    public boolean receiveImage(ImageToProcess img, Set<TaskImageContainer> sharedTasks,
174            boolean blockOnImageRelease, boolean closeOnImageRelease,
175            Optional<Runnable> runnableWhenDone)
176            throws InterruptedException;
177
178    /**
179     * Returns the number of images that are currently being referred by the
180     * consumer component.
181     *
182     * @return Number of images that are currently being referred by the
183     *         consumer
184     */
185    public int getNumberOfReservedOpenImages();
186
187    /**
188     * Returns the number of currently outstanding receiveImage calls that are
189     * processing and/or enqueued.
190     *
191     * @return the number of receiveImage calls still running or queued in the
192     *         ImageBackend
193     */
194    public int getNumberOfOutstandingCalls();
195
196    /**
197     * Shutdown all tasks by blocking on tasks to be completed.
198     */
199    public void shutdown();
200
201    /**
202     * Getter to the object that manages the ListenerEvents. Register listeners
203     * to this object.
204     */
205    public ImageProcessorProxyListener getProxyListener();
206
207}
208