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 44 extern "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 */ 51 typedef 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 */ 85 media_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 */ 99 void 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 */ 113 media_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 */ 129 media_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 */ 145 media_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 */ 158 media_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 */ 171 media_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 */ 207 media_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 */ 251 media_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 */ 261 typedef void (*AImageReader_ImageCallback)(void* context, AImageReader* reader); 262 263 typedef 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 */ 294 media_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