processing/imagebackend/ImageConsumer.java

/*
 * 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.
     * <ol>
     * <li>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.</li>
     * <li>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.</li>
     * <li>CONVERT_TO_RGB_PREVIEW: Subsamples a YUV Image and converts the
     * uncompressed output to ARGB image inset within a circle</li>
     * <li>BLOCK_UNTIL_ALL_TASKS_RELEASE: Block on ReceiveImage call until image
     * is released.</li>
     * <li>CLOSE_ON_ALL_TASKS_RELEASE: Close the ImageProxy on ReceiveImage Call
     * when all tasks release their image</li>
     * </ol>
     */
    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<ImageTaskFlags> processingFlags, CaptureSession captureSession,
            Optional<ImageProcessorListener> 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<ImageTaskFlags> 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<Runnable> 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<TaskImageContainer> sharedTasks,
            boolean blockOnImageRelease, boolean closeOnImageRelease,
            Optional<Runnable> 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();

}