1/*
2 * Copyright (C) 2016 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/**
18 * @addtogroup Media Camera
19 * @{
20 */
21
22/**
23 * @file NdkImageReader.h
24 */
25
26/*
27 * This file defines an NDK API.
28 * Do not remove methods.
29 * Do not change method signatures.
30 * Do not change the value of constants.
31 * Do not change the size of any of the classes defined in here.
32 * Do not reference types that are not part of the NDK.
33 * Do not #include files that aren't part of the NDK.
34 */
35
36#ifndef _NDK_IMAGE_READER_H
37#define _NDK_IMAGE_READER_H
38
39#include <android/native_window.h>
40#include "NdkMediaError.h"
41#include "NdkImage.h"
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48 * AImage is an opaque type that allows direct application access to image data rendered into a
49 * {@link ANativeWindow}.
50 */
51typedef struct AImageReader AImageReader;
52
53/**
54 * Create a new reader for images of the desired size and format.
55 *
56 * <p>
57 * The maxImages parameter determines the maximum number of {@link AImage} objects that can be
58 * acquired from the {@link AImageReader} simultaneously. Requesting more buffers will use up
59 * more memory, so it is important to use only the minimum number necessary for the use case.
60 * </p>
61 * <p>
62 * The valid sizes and formats depend on the source of the image data.
63 * </p>
64 *
65 * @param width The default width in pixels of the Images that this reader will produce.
66 * @param height The default height in pixels of the Images that this reader will produce.
67 * @param format The format of the Image that this reader will produce. This must be one of the
68 *            AIMAGE_FORMAT_* enum value defined in {@link AIMAGE_FORMATS}. Note that not all
69 *            formats are supported, like {@link AIMAGE_FORMAT_PRIVATE}.
70 * @param maxImages The maximum number of images the user will want to access simultaneously. This
71 *            should be as small as possible to limit memory use. Once maxImages Images are obtained
72 *            by the user, one of them has to be released before a new {@link AImage} will become
73 *            available for access through {@link AImageReader_acquireLatestImage} or
74 *            {@link AImageReader_acquireNextImage}. Must be greater than 0.
75 * @param reader The created image reader will be filled here if the method call succeeeds.
76 *
77 * @return <ul>
78 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
79 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL, or one or more of width,
80 *                 height, format, maxImages arguments is not supported.</li>
81 *         <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
82 *
83 * @see AImage
84 */
85media_status_t AImageReader_new(
86        int32_t width, int32_t height, int32_t format, int32_t maxImages,
87        /*out*/AImageReader** reader);
88
89/**
90 * Delete an {@link AImageReader} and return all images generated by this reader to system.
91 *
92 * <p>This method will return all {@link AImage} objects acquired by this reader (via
93 * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}) to system,
94 * making any of data pointers obtained from {@link AImage_getPlaneData} invalid. Do NOT access
95 * the reader object or any of those data pointers after this method returns.</p>
96 *
97 * @param reader The image reader to be deleted.
98 */
99void AImageReader_delete(AImageReader* reader);
100
101/**
102 * Get a {@link ANativeWindow} that can be used to produce {@link AImage} for this image reader.
103 *
104 * @param reader The image reader of interest.
105 * @param window The output {@link ANativeWindow} will be filled here if the method call succeeds.
106 *                The {@link ANativeWindow} is managed by this image reader. Do NOT call
107 *                {@link ANativeWindow_release} on it. Instead, use {@link AImageReader_delete}.
108 *
109 * @return <ul>
110 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
111 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or window is NULL.</li></ul>
112 */
113media_status_t AImageReader_getWindow(AImageReader* reader, /*out*/ANativeWindow** window);
114
115/**
116 * Query the default width of the {@link AImage} generated by this reader, in pixels.
117 *
118 * <p>The width may be overridden by the producer sending buffers to this reader's
119 * {@link ANativeWindow}. If so, the actual width of the images can be found using
120 * {@link AImage_getWidth}.</p>
121 *
122 * @param reader The image reader of interest.
123 * @param width the default width of the reader will be filled here if the method call succeeeds.
124 *
125 * @return <ul>
126 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
127 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or width is NULL.</li></ul>
128 */
129media_status_t AImageReader_getWidth(const AImageReader* reader, /*out*/int32_t* width);
130
131/**
132 * Query the default height of the {@link AImage} generated by this reader, in pixels.
133 *
134 * <p>The height may be overridden by the producer sending buffers to this reader's
135 * {@link ANativeWindow}. If so, the actual height of the images can be found using
136 * {@link AImage_getHeight}.</p>
137 *
138 * @param reader The image reader of interest.
139 * @param height the default height of the reader will be filled here if the method call succeeeds.
140 *
141 * @return <ul>
142 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
143 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or height is NULL.</li></ul>
144 */
145media_status_t AImageReader_getHeight(const AImageReader* reader, /*out*/int32_t* height);
146
147/**
148 * Query the format of the {@link AImage} generated by this reader.
149 *
150 * @param reader The image reader of interest.
151 * @param format the fromat of the reader will be filled here if the method call succeeeds. The
152 *                value will be one of the AIMAGE_FORMAT_* enum value defiend in {@link NdkImage.h}.
153 *
154 * @return <ul>
155 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
156 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or format is NULL.</li></ul>
157 */
158media_status_t AImageReader_getFormat(const AImageReader* reader, /*out*/int32_t* format);
159
160/**
161 * Query the maximum number of concurrently acquired {@link AImage}s of this reader.
162 *
163 * @param reader The image reader of interest.
164 * @param maxImages the maximum number of concurrently acquired images of the reader will be filled
165 *                here if the method call succeeeds.
166 *
167 * @return <ul>
168 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
169 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or maxImages is NULL.</li></ul>
170 */
171media_status_t AImageReader_getMaxImages(const AImageReader* reader, /*out*/int32_t* maxImages);
172
173/**
174 * Acquire the next {@link AImage} from the image reader's queue.
175 *
176 * <p>Warning: Consider using {@link AImageReader_acquireLatestImage} instead, as it will
177 * automatically release older images, and allow slower-running processing routines to catch
178 * up to the newest frame. Usage of {@link AImageReader_acquireNextImage} is recommended for
179 * batch/background processing. Incorrectly using this method can cause images to appear
180 * with an ever-increasing delay, followed by a complete stall where no new images seem to appear.
181 * </p>
182 *
183 * <p>
184 * This method will fail if {@link AImageReader_getMaxImages maxImages} have been acquired with
185 * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}. In particular
186 * a sequence of {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}
187 * calls greater than {@link AImageReader_getMaxImages maxImages} without calling
188 * {@link AImage_delete} in-between will exhaust the underlying queue. At such a time,
189 * {@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} will be returned until more images are released with
190 * {@link AImage_delete}.
191 * </p>
192 *
193 * @param reader The image reader of interest.
194 * @param image the acquired {@link AImage} will be filled here if the method call succeeeds.
195 *
196 * @return <ul>
197 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
198 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or image is NULL.</li>
199 *         <li>{@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} if the number of concurrently acquired
200 *                 images has reached the limit.</li>
201 *         <li>{@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} if there is no buffers currently
202 *                 available in the reader queue.</li>
203 *         <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
204 *
205 * @see AImageReader_acquireLatestImage
206 */
207media_status_t AImageReader_acquireNextImage(AImageReader* reader, /*out*/AImage** image);
208
209/**
210
211 * Acquire the latest {@link AImage} from the image reader's queue, dropping older images.
212 *
213 * <p>
214 * This operation will acquire all the images possible from the image reader, but
215 * {@link AImage_delete} all images that aren't the latest. This function is recommended to use over
216 * {@link AImageReader_acquireNextImage} for most use-cases, as it's more suited for real-time
217 * processing.
218 * </p>
219 * <p>
220 * Note that {@link AImageReader_getMaxImages maxImages} should be at least 2 for
221 * {@link AImageReader_acquireLatestImage} to be any different than
222 * {@link AImageReader_acquireNextImage} - discarding all-but-the-newest {@link AImage} requires
223 * temporarily acquiring two {@link AImage}s at once. Or more generally, calling
224 * {@link AImageReader_acquireLatestImage} with less than two images of margin, that is
225 * (maxImages - currentAcquiredImages < 2) will not discard as expected.
226 * </p>
227 * <p>
228 * This method will fail if {@link AImageReader_getMaxImages maxImages} have been acquired with
229 * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}. In particular
230 * a sequence of {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}
231 * calls greater than {@link AImageReader_getMaxImages maxImages} without calling
232 * {@link AImage_delete} in-between will exhaust the underlying queue. At such a time,
233 * {@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} will be returned until more images are released with
234 * {@link AImage_delete}.
235 * </p>
236 *
237 * @param reader The image reader of interest.
238 * @param image the acquired {@link AImage} will be filled here if the method call succeeeds.
239 *
240 * @return <ul>
241 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
242 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or image is NULL.</li>
243 *         <li>{@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} if the number of concurrently acquired
244 *                 images has reached the limit.</li>
245 *         <li>{@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} if there is no buffers currently
246 *                 available in the reader queue.</li>
247 *         <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
248 *
249 * @see AImageReader_acquireNextImage
250 */
251media_status_t AImageReader_acquireLatestImage(AImageReader* reader, /*out*/AImage** image);
252
253
254/**
255 * The definition of {@link AImageReader} new image available callback.
256 *
257 * @param context The optional application context provided by user in
258 *                {@link AImageReader_setImageListener}.
259 * @param session The camera capture session whose state is changing.
260 */
261typedef void (*AImageReader_ImageCallback)(void* context, AImageReader* reader);
262
263typedef struct AImageReader_ImageListener {
264    /// optional application context.
265    void*                      context;
266
267    /**
268     * This callback is called when there is a new image available for in the image reader's queue.
269     *
270     * <p>The callback happens on one dedicated thread per {@link AImageReader} instance. It is okay
271     * to use AImageReader_* and AImage_* methods within the callback. Note that it is possible that
272     * calling {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}
273     * returns {@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} within this callback. For example, when
274     * there are multiple images and callbacks queued, if application called
275     * {@link AImageReader_acquireLatestImage}, some images will be returned to system before their
276     * corresponding callback is executed.</p>
277     */
278    AImageReader_ImageCallback onImageAvailable;
279} AImageReader_ImageListener;
280
281/**
282 * Set the onImageAvailable listener of this image reader.
283 *
284 * <p>Note that calling this method will replace previously registered listeners.</p>
285 *
286 * @param reader The image reader of interest.
287 * @param listener the {@link AImageReader_ImageListener} to be registered. Set this to NULL if
288 *                 application no longer needs to listen to new images.
289 *
290 * @return <ul>
291 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
292 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL.</li></ul>
293 */
294media_status_t AImageReader_setImageListener(
295        AImageReader* reader, AImageReader_ImageListener* listener);
296
297#ifdef __cplusplus
298} // extern "C"
299#endif
300
301#endif //_NDK_IMAGE_READER_H
302
303/** @} */
304