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