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
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 <sys/cdefs.h>
40
41#include <android/native_window.h>
42#include "NdkMediaError.h"
43#include "NdkImage.h"
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49#if __ANDROID_API__ >= 24
50
51/**
52 * AImage is an opaque type that allows direct application access to image data rendered into a
53 * {@link ANativeWindow}.
54 */
55typedef struct AImageReader AImageReader;
56
57/**
58 * Create a new reader for images of the desired size and format.
59 *
60 * <p>
61 * The maxImages parameter determines the maximum number of {@link AImage} objects that can be
62 * acquired from the {@link AImageReader} simultaneously. Requesting more buffers will use up
63 * more memory, so it is important to use only the minimum number necessary for the use case.
64 * </p>
65 * <p>
66 * The valid sizes and formats depend on the source of the image data.
67 * </p>
68 *
69 * @param width The default width in pixels of the Images that this reader will produce.
70 * @param height The default height in pixels of the Images that this reader will produce.
71 * @param format The format of the Image that this reader will produce. This must be one of the
72 *            AIMAGE_FORMAT_* enum value defined in {@link AIMAGE_FORMATS}. Note that not all
73 *            formats are supported, like {@link AIMAGE_FORMAT_PRIVATE}.
74 * @param maxImages The maximum number of images the user will want to access simultaneously. This
75 *            should be as small as possible to limit memory use. Once maxImages Images are obtained
76 *            by the user, one of them has to be released before a new {@link AImage} will become
77 *            available for access through {@link AImageReader_acquireLatestImage} or
78 *            {@link AImageReader_acquireNextImage}. Must be greater than 0.
79 * @param reader The created image reader will be filled here if the method call succeeeds.
80 *
81 * @return <ul>
82 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
83 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL, or one or more of width,
84 *                 height, format, maxImages arguments is not supported.</li>
85 *         <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
86 *
87 * @see AImage
88 */
89media_status_t AImageReader_new(
90        int32_t width, int32_t height, int32_t format, int32_t maxImages,
91        /*out*/AImageReader** reader);
92
93/**
94 * Delete an {@link AImageReader} and return all images generated by this reader to system.
95 *
96 * <p>This method will return all {@link AImage} objects acquired by this reader (via
97 * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}) to system,
98 * making any of data pointers obtained from {@link AImage_getPlaneData} invalid. Do NOT access
99 * the reader object or any of those data pointers after this method returns.</p>
100 *
101 * @param reader The image reader to be deleted.
102 */
103void AImageReader_delete(AImageReader* reader);
104
105/**
106 * Get a {@link ANativeWindow} that can be used to produce {@link AImage} for this image reader.
107 *
108 * @param reader The image reader of interest.
109 * @param window The output {@link ANativeWindow} will be filled here if the method call succeeds.
110 *                The {@link ANativeWindow} is managed by this image reader. Do NOT call
111 *                {@link ANativeWindow_release} on it. Instead, use {@link AImageReader_delete}.
112 *
113 * @return <ul>
114 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
115 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or window is NULL.</li></ul>
116 */
117media_status_t AImageReader_getWindow(AImageReader* reader, /*out*/ANativeWindow** window);
118
119/**
120 * Query the default width of the {@link AImage} generated by this reader, in pixels.
121 *
122 * <p>The width may be overridden by the producer sending buffers to this reader's
123 * {@link ANativeWindow}. If so, the actual width of the images can be found using
124 * {@link AImage_getWidth}.</p>
125 *
126 * @param reader The image reader of interest.
127 * @param width the default width of the reader will be filled here if the method call succeeeds.
128 *
129 * @return <ul>
130 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
131 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or width is NULL.</li></ul>
132 */
133media_status_t AImageReader_getWidth(const AImageReader* reader, /*out*/int32_t* width);
134
135/**
136 * Query the default height of the {@link AImage} generated by this reader, in pixels.
137 *
138 * <p>The height may be overridden by the producer sending buffers to this reader's
139 * {@link ANativeWindow}. If so, the actual height of the images can be found using
140 * {@link AImage_getHeight}.</p>
141 *
142 * @param reader The image reader of interest.
143 * @param height the default height of the reader will be filled here if the method call succeeeds.
144 *
145 * @return <ul>
146 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
147 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or height is NULL.</li></ul>
148 */
149media_status_t AImageReader_getHeight(const AImageReader* reader, /*out*/int32_t* height);
150
151/**
152 * Query the format of the {@link AImage} generated by this reader.
153 *
154 * @param reader The image reader of interest.
155 * @param format the fromat of the reader will be filled here if the method call succeeeds. The
156 *                value will be one of the AIMAGE_FORMAT_* enum value defiend in {@link NdkImage.h}.
157 *
158 * @return <ul>
159 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
160 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or format is NULL.</li></ul>
161 */
162media_status_t AImageReader_getFormat(const AImageReader* reader, /*out*/int32_t* format);
163
164/**
165 * Query the maximum number of concurrently acquired {@link AImage}s of this reader.
166 *
167 * @param reader The image reader of interest.
168 * @param maxImages the maximum number of concurrently acquired images of the reader will be filled
169 *                here if the method call succeeeds.
170 *
171 * @return <ul>
172 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
173 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or maxImages is NULL.</li></ul>
174 */
175media_status_t AImageReader_getMaxImages(const AImageReader* reader, /*out*/int32_t* maxImages);
176
177/**
178 * Acquire the next {@link AImage} from the image reader's queue.
179 *
180 * <p>Warning: Consider using {@link AImageReader_acquireLatestImage} instead, as it will
181 * automatically release older images, and allow slower-running processing routines to catch
182 * up to the newest frame. Usage of {@link AImageReader_acquireNextImage} is recommended for
183 * batch/background processing. Incorrectly using this method can cause images to appear
184 * with an ever-increasing delay, followed by a complete stall where no new images seem to appear.
185 * </p>
186 *
187 * <p>
188 * This method will fail if {@link AImageReader_getMaxImages maxImages} have been acquired with
189 * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}. In particular
190 * a sequence of {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}
191 * calls greater than {@link AImageReader_getMaxImages maxImages} without calling
192 * {@link AImage_delete} in-between will exhaust the underlying queue. At such a time,
193 * {@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} will be returned until more images are released with
194 * {@link AImage_delete}.
195 * </p>
196 *
197 * @param reader The image reader of interest.
198 * @param image the acquired {@link AImage} will be filled here if the method call succeeeds.
199 *
200 * @return <ul>
201 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
202 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or image is NULL.</li>
203 *         <li>{@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} if the number of concurrently acquired
204 *                 images has reached the limit.</li>
205 *         <li>{@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} if there is no buffers currently
206 *                 available in the reader queue.</li>
207 *         <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
208 *
209 * @see AImageReader_acquireLatestImage
210 */
211media_status_t AImageReader_acquireNextImage(AImageReader* reader, /*out*/AImage** image);
212
213/**
214
215 * Acquire the latest {@link AImage} from the image reader's queue, dropping older images.
216 *
217 * <p>
218 * This operation will acquire all the images possible from the image reader, but
219 * {@link AImage_delete} all images that aren't the latest. This function is recommended to use over
220 * {@link AImageReader_acquireNextImage} for most use-cases, as it's more suited for real-time
221 * processing.
222 * </p>
223 * <p>
224 * Note that {@link AImageReader_getMaxImages maxImages} should be at least 2 for
225 * {@link AImageReader_acquireLatestImage} to be any different than
226 * {@link AImageReader_acquireNextImage} - discarding all-but-the-newest {@link AImage} requires
227 * temporarily acquiring two {@link AImage}s at once. Or more generally, calling
228 * {@link AImageReader_acquireLatestImage} with less than two images of margin, that is
229 * (maxImages - currentAcquiredImages < 2) will not discard as expected.
230 * </p>
231 * <p>
232 * This method will fail if {@link AImageReader_getMaxImages maxImages} have been acquired with
233 * {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}. In particular
234 * a sequence of {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}
235 * calls greater than {@link AImageReader_getMaxImages maxImages} without calling
236 * {@link AImage_delete} in-between will exhaust the underlying queue. At such a time,
237 * {@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} will be returned until more images are released with
238 * {@link AImage_delete}.
239 * </p>
240 *
241 * @param reader The image reader of interest.
242 * @param image the acquired {@link AImage} will be filled here if the method call succeeeds.
243 *
244 * @return <ul>
245 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
246 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader or image is NULL.</li>
247 *         <li>{@link AMEDIA_IMGREADER_MAX_IMAGES_ACQUIRED} if the number of concurrently acquired
248 *                 images has reached the limit.</li>
249 *         <li>{@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} if there is no buffers currently
250 *                 available in the reader queue.</li>
251 *         <li>{@link AMEDIA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul>
252 *
253 * @see AImageReader_acquireNextImage
254 */
255media_status_t AImageReader_acquireLatestImage(AImageReader* reader, /*out*/AImage** image);
256
257
258/**
259 * The definition of {@link AImageReader} new image available callback.
260 *
261 * @param context The optional application context provided by user in
262 *                {@link AImageReader_setImageListener}.
263 * @param session The camera capture session whose state is changing.
264 */
265typedef void (*AImageReader_ImageCallback)(void* context, AImageReader* reader);
266
267typedef struct AImageReader_ImageListener {
268    /// optional application context.
269    void*                      context;
270
271    /**
272     * This callback is called when there is a new image available for in the image reader's queue.
273     *
274     * <p>The callback happens on one dedicated thread per {@link AImageReader} instance. It is okay
275     * to use AImageReader_* and AImage_* methods within the callback. Note that it is possible that
276     * calling {@link AImageReader_acquireNextImage} or {@link AImageReader_acquireLatestImage}
277     * returns {@link AMEDIA_IMGREADER_NO_BUFFER_AVAILABLE} within this callback. For example, when
278     * there are multiple images and callbacks queued, if application called
279     * {@link AImageReader_acquireLatestImage}, some images will be returned to system before their
280     * corresponding callback is executed.</p>
281     */
282    AImageReader_ImageCallback onImageAvailable;
283} AImageReader_ImageListener;
284
285/**
286 * Set the onImageAvailable listener of this image reader.
287 *
288 * <p>Note that calling this method will replace previously registered listeners.</p>
289 *
290 * @param reader The image reader of interest.
291 * @param listener the {@link AImageReader_ImageListener} to be registered. Set this to NULL if
292 *                 application no longer needs to listen to new images.
293 *
294 * @return <ul>
295 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
296 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL.</li></ul>
297 */
298media_status_t AImageReader_setImageListener(
299        AImageReader* reader, AImageReader_ImageListener* listener);
300
301#endif /* __ANDROID_API__ >= 24 */
302
303#if __ANDROID_API__ >= 26
304
305/**
306 * AImageReader constructor similar to {@link AImageReader_new} that takes an additional parameter
307 * for the consumer usage. All other parameters and the return values are identical to those passed
308 * to {@line AImageReader_new}.
309 *
310 * @param usage specifies how the consumer will access the AImage, using combination of the
311 *            AHARDWAREBUFFER_USAGE flags described in {@link hardware_buffer.h}.
312 *            Passing {@link AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN} is equivalent to calling
313 *            {@link AImageReader_new} with the same parameters.
314 *
315 * Note that not all format and usage flag combination is supported by the {@link AImageReader}.
316 * Below are the combinations supported by the {@link AImageReader}.
317 * <table>
318 * <tr>
319 *   <th>Format</th>
320 *   <th>Compatible usage flags</th>
321 * </tr>
322 * <tr>
323 *   <td>non-{@link AIMAGE_FORMAT_PRIVATE PRIVATE} formats defined in {@link AImage.h}
324 * </td>
325 *   <td>{@link AHARDWAREBUFFER_USAGE_CPU_READ_RARELY} or
326 *   {@link AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN}</td>
327 * </tr>
328 * <tr>
329 *   <td>{@link AIMAGE_FORMAT_RGBA_8888}</td>
330 *   <td>{@link AHARDWAREBUFFER_USAGE_VIDEO_ENCODE} or
331 *   {@link AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE}, or combined</td>
332 * </tr>
333 * </table>
334 *
335 * @see AImage
336 * @see AImageReader_new
337 * @see AHardwareBuffer
338 */
339media_status_t AImageReader_newWithUsage(
340        int32_t width, int32_t height, int32_t format, uint64_t usage, int32_t maxImages,
341        /*out*/ AImageReader** reader);
342
343/*
344 * Acquire the next {@link AImage} from the image reader's queue asynchronously.
345 *
346 * <p>AImageReader acquire method similar to {@link AImageReader_acquireNextImage} that takes an
347 * additional parameter for the sync fence. All other parameters and the return values are
348 * identical to those passed to {@link AImageReader_acquireNextImage}.</p>
349 *
350 * @param acquireFenceFd A sync fence fd defined in {@link sync.h}, which is used to signal when the
351 *         buffer is ready to consume. When synchronization fence is not needed, fence will be set
352 *         to -1 and the {@link AImage} returned is ready for use immediately. Otherwise, user shall
353 *         use syscalls such as {@code poll()}, {@code epoll()}, {@code select()} to wait for the
354 *         fence fd to change status before attempting to access the {@link AImage} returned.
355 *
356 * @see sync.h
357 * @see sync_get_fence_info
358 */
359media_status_t AImageReader_acquireNextImageAsync(
360        AImageReader* reader, /*out*/AImage** image, /*out*/int* acquireFenceFd);
361
362/*
363 * Acquire the latest {@link AImage} from the image reader's queue asynchronously, dropping older
364 * images.
365 *
366 * <p>AImageReader acquire method similar to {@link AImageReader_acquireLatestImage} that takes an
367 * additional parameter for the sync fence. All other parameters and the return values are
368 * identical to those passed to {@link AImageReader_acquireLatestImage}.</p>
369 *
370 * @param acquireFenceFd A sync fence fd defined in {@link sync.h}, which is used to signal when the
371 *         buffer is ready to consume. When synchronization fence is not needed, fence will be set
372 *         to -1 and the {@link AImage} returned is ready for use immediately. Otherwise, user shall
373 *         use syscalls such as {@code poll()}, {@code epoll()}, {@code select()} to wait for the
374 *         fence fd to change status before attempting to access the {@link AImage} returned.
375 *
376 * @see sync.h
377 * @see sync_get_fence_info
378 */
379media_status_t AImageReader_acquireLatestImageAsync(
380        AImageReader* reader, /*out*/AImage** image, /*out*/int* acquireFenceFd);
381/**
382 * The definition of {@link AImageReader} buffer removed callback.
383 *
384 * @param context The optional application context provided by user in
385 *                {@link AImageReader_setBufferRemovedListener}.
386 * @param reader The {@link AImageReader} of interest.
387 * @param buffer The {@link AHardwareBuffer} that is being removed from this image reader.
388 */
389typedef void (*AImageReader_BufferRemovedCallback)(void* context,
390        AImageReader* reader,
391        AHardwareBuffer* buffer);
392
393typedef struct AImageReader_BufferRemovedListener {
394    /// optional application context.
395    void*                      context;
396
397    /**
398     * This callback is called when an old {@link AHardwareBuffer} is about to be removed from the
399     * image reader.
400     *
401     * <p>Note that registering this callback is optional unless the user holds on extra reference
402     * to {@link AHardwareBuffer} returned from {@link AImage_getHardwareBuffer} by calling {@link
403     * AHardwareBuffer_acquire} or creating external graphic objects, such as EglImage, from it.</p>
404     *
405     * <p>If the callback is registered, the {@link AImageReader} will hold on the last of its
406     * references to the {@link AHardwareBuffer} until this callback returns. User can use the
407     * callback to get notified that it becomes the last owner of the buffer. It is up to the user
408     * to decide to either 1) immediately release all of its references to the buffer; or 2) keep
409     * using the buffer and release it in future. Note that, if option 2 if used, user of this API
410     * is responsible to deallocate the buffer properly by calling {@link AHardwareBuffer_release}.
411     * </p>
412     *
413     * @see AHardwareBuffer_release
414     * @see AImage_getHardwareBuffer
415     */
416    AImageReader_BufferRemovedCallback onBufferRemoved;
417} AImageReader_BufferRemovedListener;
418
419/**
420 * Set the onBufferRemoved listener of this image reader.
421 *
422 * <p>Note that calling this method will replace previously registered listeners.</p>
423 *
424 * @param reader The image reader of interest.
425 * @param listener the {@link AImageReader_BufferRemovedListener} to be registered. Set this to
426 * NULL if application no longer needs to listen to buffer removed events.
427 *
428 * @return <ul>
429 *         <li>{@link AMEDIA_OK} if the method call succeeds.</li>
430 *         <li>{@link AMEDIA_ERROR_INVALID_PARAMETER} if reader is NULL.</li></ul>
431 *
432 * @see AImage_getHardwareBuffer
433 */
434media_status_t AImageReader_setBufferRemovedListener(
435        AImageReader* reader, AImageReader_BufferRemovedListener* listener);
436
437#endif /* __ANDROID_API__ >= 26 */
438
439
440#ifdef __cplusplus
441} // extern "C"
442#endif
443
444#endif //_NDK_IMAGE_READER_H
445
446/** @} */
447