/* * Copyright (C) 2014 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package com.android.camera.processing.imagebackend; import com.google.common.base.Optional; import com.android.camera.session.CaptureSession; import java.util.Set; import java.util.concurrent.Executor; import javax.annotation.Nullable; /** * Defines interface between an ImageBackend object and a simplified camera * object that merely delivers images to the backend. After the tasks and * Android image is submitted to the ImageConsumer, the responsibility to close * on the Android image object as early as possible is transferred to the * implementation. Whether an image can be submitted again for process is up to * the implementation of the consumer. For integration of Camera Application, we * now pass in the CaptureSession in order to properly update filmstrip and UI. * More generalized versions of functions of this interface allow a Runnable to * be executed when the set of events and any spawned events have completed * processing. */ public interface ImageConsumer { /** * ImageTaskFlags specifies the current tasks that will be run with an * image. *
    *
  1. CREATE_EARLY_FILMSTRIP_PREVIEW: Subsamples a YUV Image and converts * it to an ARGB Image with nearly similar aspect ratio. ONLY Valid when * specified with COMPRESS_TO_JPEG_AND_WRITE_TO_DISK. Otherwise, ignored.
  2. *
  3. COMPRESS_TO_JPEG_AND_WRITE_TO_DISK: Compresses an YUV/JPEG Image to * JPEG (when necessary), delivers the compressed artifact via the listener, * and writes it to disk.
  4. *
  5. CONVERT_TO_RGB_PREVIEW: Subsamples a YUV Image and converts the * uncompressed output to ARGB image inset within a circle
  6. *
  7. BLOCK_UNTIL_ALL_TASKS_RELEASE: Block on ReceiveImage call until image * is released.
  8. *
  9. CLOSE_ON_ALL_TASKS_RELEASE: Close the ImageProxy on ReceiveImage Call * when all tasks release their image
  10. *
*/ public enum ImageTaskFlags { CREATE_EARLY_FILMSTRIP_PREVIEW, COMPRESS_TO_JPEG_AND_WRITE_TO_DISK, CONVERT_TO_RGB_PREVIEW, BLOCK_UNTIL_ALL_TASKS_RELEASE, CLOSE_ON_ALL_TASKS_RELEASE } /** * Provides the basic functionality of camera processing via an easy-to-use * method call. Feel free to expand this implementation by increasing the * types of common tasks in the enum ImageTaskFlags. This version of the call * also automatically registers at time of task submission and unregisters * the listener at the time when all tasks and associated spawned tasks have * completed their processing. * * @param img image to be processed * @param executor The executor on which to execute events and image close * @param processingFlags {@see ImageTaskFlags} * @param imageProcessorListener Optional listener to automatically register * at task submission and unregister after all tasks are done * @return Whether any tasks were actually added. * @throws InterruptedException occurs when call is set to be blocking and * is interrupted. */ public boolean receiveImage(ImageToProcess img, Executor executor, Set processingFlags, CaptureSession captureSession, Optional imageProcessorListener) throws InterruptedException; /** * Provides the basic functionality of camera processing via an easy-to-use * method call w/o a listener to be released. * * @param img image to be processed * @param executor executor on which to execute events and image close * @param processingFlags {@see ImageTaskFlags} * @return Whether any tasks were actually added. * @throws InterruptedException occurs when call is set to be blocking and * is interrupted. */ /* public boolean receiveImage(ImageToProcess img, Executor executor, Set processingFlags, CaptureSession captureSession) throws InterruptedException; */ /** * Provides the basic functionality of camera processing via a more general- * purpose method call. Tasks can be extended off of the TaskImageContainer, * or created from factory method provided by implementation. * * @param img image to be processed * @param sharedTask a single task to be run * @param blockOnImageRelease If true, call blocks until the object img is * no longer referred by any task. If false, call is non-blocking * @param closeOnImageRelease If true, images is closed when the object img * is is no longer referred by any task. If false, * @param runnableWhenDone Optional runnable to be executed when the task is * done. * @return Whether the blocking completed properly. If false, there may be a * need to clean up image closes manually. * @throws InterruptedException occurs when call is set to be blocking and * is interrupted. */ public boolean receiveImage(ImageToProcess img, TaskImageContainer sharedTask, boolean blockOnImageRelease, boolean closeOnImageRelease, Optional runnableWhenDone) throws InterruptedException; /** * Provides the basic functionality of camera processing via a more general- * purpose method call w/o a Runnable to be executed when the task is done. * Tasks can be extended off of the TaskImageContainer, or created from * factory method provided by implementation. * * @param img image to be processed. * @param sharedTask a single task to be run. * @param blockOnImageRelease If true, call blocks until the object img is * no longer referred by any task. If false, call is non-blocking * @param closeOnImageRelease If true, images is closed when the object img * is is no longer referred by any task. If false, * @return Whether the blocking completed properly. If false, there may be a * need to clean up image closes manually. * @throws InterruptedException occurs when call is set to be blocking and * is interrupted. */ @Deprecated public boolean receiveImage(ImageToProcess img, TaskImageContainer sharedTask, boolean blockOnImageRelease, boolean closeOnImageRelease) throws InterruptedException; /** * Provides the basic functionality of camera processing via the most * general- purpose method call. Tasks can be extended off of the * TaskImageContainer, or created from factory method provided by the * implementation. * * @param img image to be processed. * @param sharedTasks Set of tasks to be run on the given image. * @param blockOnImageRelease If true, call blocks until the object img is * no longer referred by any task. If false, call is non-blocking * @param closeOnImageRelease If true, images is closed when the object img * is is no longer referred by any task. If false, close is not * called on release. * @param runnableWhenDone optional runnable to be executed when the set of * tasks are done. * @return Whether the blocking completed properly. If false, there may be a * need to clean up image closes manually. * @throws InterruptedException occurs when call is set to be blocking and * is interrupted. */ public boolean receiveImage(ImageToProcess img, Set sharedTasks, boolean blockOnImageRelease, boolean closeOnImageRelease, Optional runnableWhenDone) throws InterruptedException; /** * Returns the number of images that are currently being referred by the * consumer component. * * @return Number of images that are currently being referred by the * consumer */ public int getNumberOfReservedOpenImages(); /** * Returns the number of currently outstanding receiveImage calls that are * processing and/or enqueued. * * @return the number of receiveImage calls still running or queued in the * ImageBackend */ public int getNumberOfOutstandingCalls(); /** * Shutdown all tasks by blocking on tasks to be completed. */ public void shutdown(); /** * Getter to the object that manages the ListenerEvents. Register listeners * to this object. */ public ImageProcessorProxyListener getProxyListener(); }