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.one.v2.sharedimagereader.imagedistributor; 18 19 import com.android.camera.async.BufferQueue; 20 import com.android.camera.one.v2.camera2proxy.ImageProxy; 21 import com.android.camera.one.v2.core.CaptureStream; 22 23 import java.util.concurrent.TimeUnit; 24 import java.util.concurrent.TimeoutException; 25 26 /** 27 * An interface for {@link CaptureStream}s which route images into a 28 * {@link BufferQueue}. 29 * <p> 30 * For example, an implementation of this may be added to a 31 * {@link com.android.camera.one.v2.core.RequestBuilder} to then get Images 32 * corresponding to that request as a queue. 33 * <p> 34 * Note that images always arrive in order. Different implementations may behave 35 * differently with respect to how images are dropped. For example, some may act 36 * like a ring-buffer and automatically drop the oldest image when a new image 37 * arrives. Others may close new images immediately if no capacity is available. 38 */ 39 public interface ImageStream extends BufferQueue<ImageProxy>, CaptureStream { 40 /** 41 * Closes the ImageStream. After being closed, no more images will be 42 * available and any images left in the stream are closed. 43 */ 44 @Override 45 public void close(); 46 47 /** 48 * Blocks, returning the next available image. 49 * 50 * @return The next available image. 51 * @throws InterruptedException If interrupted while waiting for the next 52 * image. 53 * @throws com.android.camera.async.BufferQueue.BufferQueueClosedException 54 * If the stream is closed and no more images will be available. 55 */ 56 @Override 57 public ImageProxy getNext() throws InterruptedException, BufferQueueClosedException; 58 59 /** 60 * Blocks, returning the next available image. 61 * 62 * @param timeout The maximum amount of time to wait. 63 * @param unit The unit associated with the timeout. 64 * @return The next available image. 65 * @throws InterruptedException If interrupted while waiting for the next 66 * image. 67 * @throws com.android.camera.async.BufferQueue.BufferQueueClosedException 68 * If the stream is closed and no more images will be available. 69 * @throws TimeoutException If no new image is made available within the 70 * specified time limit. 71 */ 72 @Override 73 public ImageProxy getNext(long timeout, TimeUnit unit) throws InterruptedException, 74 TimeoutException, 75 BufferQueueClosedException; 76 77 /** 78 * Immediately returns the next available image without removing it from the 79 * stream. Note that the ImageStream still owns the image, so the caller 80 * MUST NOT close it. 81 * 82 * @return The next available value if one exists, or null if no value 83 * exists yet or the stream is closed. 84 */ 85 @Override 86 public ImageProxy peekNext(); 87 88 /** 89 * Immediately discards the next available image, if one exists. 90 */ 91 @Override 92 public void discardNext(); 93 94 /** 95 * @return True if the stream has been closed by either the producer or the 96 * consumer. 97 */ 98 @Override 99 public boolean isClosed(); 100 } 101
