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 17 package com.android.camera.processing.imagebackend; 18 19 import com.google.common.base.Optional; 20 21 import com.android.camera.session.CaptureSession; 22 23 import java.util.Set; 24 import java.util.concurrent.Executor; 25 26 import 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 */ 40 public 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
