1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15package com.android.camera.burst;
16
17import android.graphics.SurfaceTexture;
18
19import com.android.camera.one.v2.camera2proxy.ImageProxy;
20import com.android.camera.one.v2.imagesaver.MetadataImage;
21import com.android.camera.session.CaptureSession;
22
23import java.util.List;
24
25/**
26 * Controls the interactions with burst.
27 * <p/>
28 * A burst consists of a series of images. Burst module controls the internal
29 * camera buffer and keeps images that best represent a burst at any given point
30 * in time. The burst module makes decisions on which frames to keep by
31 * analyzing low-res preview frames and keeping the corresponding high-res
32 * images in the camera internal buffer. At the end of the burst, the burst
33 * module retrieves results from the internal camera buffer and can do post
34 * processing on the results.
35 * <p/>
36 * Camera initializes the burst module by calling {@link #startBurst(SurfaceTexture,
37 * ImageStreamProperties, BurstResultsListener, CaptureSession)}. The returned
38 * eviction strategy is used by the internal camera buffer to decide which
39 * frames to keep and which to reject.
40 * <p/>
41 * Once burst finishes, camera calls the {@link #processBurstResults(List)} to
42 * let the burst module retrieve burst results from the internal buffer. Once
43 * {@link #processBurstResults(List)} completes all resources allocated for the
44 * burst are freed.
45 * <p/>
46 * Once post processing is complete, the burst module returns the final results
47 * by calling {@link BurstResultsListener#onBurstCompleted(BurstResult)} method.
48 */
49interface BurstController {
50
51    /**
52     * Properties of the image stream.
53     */
54    public static class ImageStreamProperties {
55        private final int width;
56        private final int height;
57        private final int imageRotation;
58        private final boolean isMirrored;
59
60        public ImageStreamProperties(int width, int height,
61                int imageRotation,
62                boolean isMirrored) {
63            this.width = width;
64            this.height = height;
65            this.imageRotation = imageRotation;
66            this.isMirrored = isMirrored;
67        }
68
69        public int getWidth() {
70            return width;
71        }
72
73        public int getHeight() {
74            return height;
75        }
76
77        public int getImageRotation() {
78            return imageRotation;
79        }
80
81        public boolean isMirrored() {
82            return isMirrored;
83        }
84    }
85
86    /**
87     * Starts the burst.
88     * <p/>
89     * Takes a SurfaceTexture that is not attached to any context (call
90     * {@link android.graphics.SurfaceTexture#detachFromGLContext()} before
91     * passing it here. Can register as a frame available listener by calling
92     * {@link SurfaceTexture#setOnFrameAvailableListener(SurfaceTexture.OnFrameAvailableListener,
93     * android.os.Handler)}.
94     *
95     * @param surfaceTexture the SurfaceTexture for the low-res image stream.
96     *            This surface should not be attached to any GL context.
97     * @param imageStreamProperties the properties of the low-res image stream.
98     * @param burstResultsListener the listener for burst results.
99     * @param captureSession the capture session associated with the burst.
100     * @return the configuration of burst that can be used to control the
101     *         ongoing burst.
102     */
103    public EvictionHandler startBurst(SurfaceTexture surfaceTexture,
104            ImageStreamProperties imageStreamProperties,
105            BurstResultsListener burstResultsListener,
106            CaptureSession captureSession);
107
108    /**
109     * Stops the burst.
110     * <p/>
111     *
112     * @param capturedImages list of images captured from the burst. Implementations should
113     *                        close the images as soon as possible.
114     */
115    public void processBurstResults(List<MetadataImage> capturedImages);
116}
117