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.core;
18 
19 import android.view.Surface;
20 
21 import com.android.camera.async.BufferQueue;
22 
23 /**
24  * A generic Surface-holding object which can be attached to a {@link Request},
25  * when build via {@link RequestBuilder}. The simplest implementation may simply
26  * provide a {@link Surface} on which to send frames from the camera. However,
27  * other implementations may wish to filter images sent to the {@link Surface}
28  * in response to different {@link Request}s. To enable this, {@link #bind} is
29  * called for each Request with a queue which will contain the timestamps of
30  * every image captured for that request.
31  * <p>
32  * Implementations must provide a {@link Surface} and (optionally) implement
33  * logic to filter images added to the surface according to a stream of image
34  * timestamps.
35  * </p>
36  * <p>
37  * Implementations should use the {@link CaptureStream#bind} method to kick off
38  * a process of taking, as input, a {@link com.android.camera.async.BufferQueue}
39  * of image timestamps as well as the images added to the {@link Surface}, and
40  * producing, as output, a stream of useful handles to the image data.
41  * </p>
42  */
43 public interface CaptureStream {
44 
45     /**
46      * Implementations should use this method to allocate all resources
47      * necessary to ensure that the requested images can be saved.
48      *
49      * @param timestamps A stream of monotonically-increasing timestamps of
50      *            images which correspond to the request to which the surface
51      *            will be bound Images with timestamps not present in the queue
52      *            should typically be ignored/discarded by the implementation.
53      *            Note that for non-repeating requests, this will only be a
54      *            single timestamp.
55      * @return The stream which clients may use to interact with the returned
56      *         images.
57      * @throws InterruptedException if interrupted while waiting to allocate
58      *             resources necessary to begin accepting new images.
59      */
bind(BufferQueue<Long> timestamps)60     public Surface bind(BufferQueue<Long> timestamps)
61             throws InterruptedException, ResourceAcquisitionFailedException;
62 }
63