1 /*
2  * Copyright 2019 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 androidx.camera.core.impl;
18 
19 import android.media.ImageReader;
20 import android.view.Surface;
21 
22 import androidx.annotation.RestrictTo;
23 import androidx.annotation.RestrictTo.Scope;
24 import androidx.camera.core.ImageProxy;
25 
26 import org.jspecify.annotations.NonNull;
27 import org.jspecify.annotations.Nullable;
28 
29 import java.util.concurrent.Executor;
30 
31 /**
32  * An image reader proxy which has an analogous interface as {@link ImageReader}.
33  *
34  * <p>Whereas an {@link ImageReader} provides {@link android.media.Image} instances, an {@link
35  * ImageReaderProxy} provides {@link ImageProxy} instances.
36  *
37  */
38 public interface ImageReaderProxy {
39     /**
40      * Acquires the latest image in the queue.
41      *
42      * <p>@see {@link ImageReader#acquireLatestImage()}.
43      */
acquireLatestImage()44     @Nullable ImageProxy acquireLatestImage();
45 
46     /**
47      * Acquires the next image in the queue.
48      *
49      * <p>@see {@link ImageReader#acquireNextImage()}.
50      */
acquireNextImage()51     @Nullable ImageProxy acquireNextImage();
52 
53     /**
54      * Closes the reader.
55      *
56      * <p>@see {@link ImageReader#close()}.
57      */
close()58     void close();
59 
60     /**
61      * Returns the image height.
62      *
63      * <p>@see {@link ImageReader#getHeight()}.
64      */
getHeight()65     int getHeight();
66 
67     /**
68      * Returns the image width.
69      *
70      * <p>@see {@link ImageReader#getWidth()}.
71      */
getWidth()72     int getWidth();
73 
74     /**
75      * Returns the image format.
76      *
77      * <p>@see {@link ImageReader#getImageFormat()}.
78      */
getImageFormat()79     int getImageFormat();
80 
81     /**
82      * Returns the max number of images in the queue.
83      *
84      * <p>@see {@link ImageReader#getMaxImages()}.
85      */
getMaxImages()86     int getMaxImages();
87 
88     /**
89      * Returns the underlying surface.
90      *
91      * <p>@see {@link ImageReader#getSurface()}.
92      */
getSurface()93     @Nullable Surface getSurface();
94 
95     /**
96      * Sets the on-image-available listener.
97      *
98      * @param listener The listener that will be run.
99      * @param executor The executor on which the listener should be invoked.
100      */
setOnImageAvailableListener( ImageReaderProxy.@onNull OnImageAvailableListener listener, @NonNull Executor executor)101     void setOnImageAvailableListener(
102             ImageReaderProxy.@NonNull OnImageAvailableListener listener,
103             @NonNull Executor executor);
104 
105     /**
106      * Clears the currently set {@link OnImageAvailableListener}.
107      *
108      * <p> This does not cancel any currently in progress listener.
109      */
clearOnImageAvailableListener()110     void clearOnImageAvailableListener();
111 
112     /**
113      * A listener for newly available images.
114      *
115      */
116     @RestrictTo(Scope.LIBRARY_GROUP)
117     interface OnImageAvailableListener {
118         /**
119          * Callback for a newly available image.
120          *
121          * <p>@see {@link ImageReader.OnImageAvailableListener#onImageAvailable(ImageReader)}.
122          */
onImageAvailable(@onNull ImageReaderProxy imageReader)123         void onImageAvailable(@NonNull ImageReaderProxy imageReader);
124     }
125 }
126