1 /* 2 * Copyright (C) 2015 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 Camera 19 * @{ 20 */ 21 22 /** 23 * @file NdkCameraDevice.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 #include <sys/cdefs.h> 36 37 #include <android/native_window.h> 38 #include "NdkCameraError.h" 39 #include "NdkCaptureRequest.h" 40 #include "NdkCameraCaptureSession.h" 41 42 #ifndef _NDK_CAMERA_DEVICE_H 43 #define _NDK_CAMERA_DEVICE_H 44 45 __BEGIN_DECLS 46 47 #if __ANDROID_API__ >= 24 48 49 /** 50 * ACameraDevice is opaque type that provides access to a camera device. 51 * 52 * A pointer can be obtained using {@link ACameraManager_openCamera} method. 53 */ 54 typedef struct ACameraDevice ACameraDevice; 55 56 /// Enum for ACameraDevice_ErrorStateCallback error code 57 enum { 58 /** 59 * The camera device is in use already. 60 */ 61 ERROR_CAMERA_IN_USE = 1, 62 63 /** 64 * The system-wide limit for number of open cameras or camera resources has 65 * been reached, and more camera devices cannot be opened until previous 66 * instances are closed. 67 */ 68 ERROR_MAX_CAMERAS_IN_USE = 2, 69 70 /** 71 * The camera is disabled due to a device policy, and cannot be opened. 72 */ 73 ERROR_CAMERA_DISABLED = 3, 74 75 /** 76 * The camera device has encountered a fatal error. 77 * <p>The camera device needs to be re-opened to be used again.</p> 78 */ 79 ERROR_CAMERA_DEVICE = 4, 80 81 /** 82 * The camera service has encountered a fatal error. 83 * <p>The Android device may need to be shut down and restarted to restore 84 * camera function, or there may be a persistent hardware problem. 85 * An attempt at recovery may be possible by closing the 86 * CameraDevice and the CameraManager, and trying to acquire all resources 87 * again from scratch.</p> 88 */ 89 ERROR_CAMERA_SERVICE = 5 90 }; 91 92 /** 93 * Camera device state callbacks to be used in {@link ACameraDevice_StateCallbacks}. 94 * 95 * @param context The optional context in {@link ACameraDevice_StateCallbacks} will be 96 * passed to this callback. 97 * @param device The {@link ACameraDevice} that is being disconnected. 98 */ 99 typedef void (*ACameraDevice_StateCallback)(void* context, ACameraDevice* device); 100 101 /** 102 * Camera device error state callbacks to be used in {@link ACameraDevice_StateCallbacks}. 103 * 104 * @param context The optional context in {@link ACameraDevice_StateCallbacks} will be 105 * passed to this callback. 106 * @param device The {@link ACameraDevice} that is being disconnected. 107 * @param error The error code describes the cause of this error callback. See the folowing 108 * links for more detail. 109 * 110 * @see ERROR_CAMERA_IN_USE 111 * @see ERROR_MAX_CAMERAS_IN_USE 112 * @see ERROR_CAMERA_DISABLED 113 * @see ERROR_CAMERA_DEVICE 114 * @see ERROR_CAMERA_SERVICE 115 */ 116 typedef void (*ACameraDevice_ErrorStateCallback)(void* context, ACameraDevice* device, int error); 117 118 typedef struct ACameraDevice_StateCallbacks { 119 /// optional application context. 120 void* context; 121 122 /** 123 * The function is called when a camera device is no longer available for use. 124 * 125 * <p>Any attempt to call API methods on this ACameraDevice will return 126 * {@link ACAMERA_ERROR_CAMERA_DISCONNECTED}. The disconnection could be due to a 127 * change in security policy or permissions; the physical disconnection 128 * of a removable camera device; or the camera being needed for a 129 * higher-priority camera API client.</p> 130 * 131 * <p>Application should clean up the camera with {@link ACameraDevice_close} after 132 * this happens, as it is not recoverable until the camera can be opened 133 * again.</p> 134 * 135 */ 136 ACameraDevice_StateCallback onDisconnected; 137 138 /** 139 * The function called when a camera device has encountered a serious error. 140 * 141 * <p>This indicates a failure of the camera device or camera service in some way. 142 * Any attempt to call API methods on this ACameraDevice in the future will return 143 * {@link ACAMERA_ERROR_CAMERA_DISCONNECTED}.</p> 144 * 145 * <p>There may still be capture completion or camera stream callbacks that will be called 146 * after this error is received.</p> 147 * 148 * <p>Application should clean up the camera with {@link ACameraDevice_close} after this 149 * happens. Further attempts at recovery are error-code specific.</p> 150 * 151 */ 152 ACameraDevice_ErrorStateCallback onError; 153 } ACameraDevice_StateCallbacks; 154 155 /** 156 * For backward compatiblity. 157 */ 158 typedef ACameraDevice_StateCallbacks ACameraDevice_stateCallbacks; 159 160 /** 161 * Close the connection and free this ACameraDevice synchronously. Access to the ACameraDevice 162 * after calling this method will cause a crash. 163 * 164 * <p>After this call, all calls to the active ACameraCaptureSession associated to this 165 * ACameraDevice will return {@link ACAMERA_ERROR_SESSION_CLOSED} except for calls to 166 * {@link ACameraCaptureSession_close}.</p> 167 * 168 * <p>This method will stop all repeating captures sent via 169 * {@link ACameraCaptureSession_setRepeatingRequest} and block until all capture requests sent via 170 * {@link ACameraCaptureSession_capture} is complete. Once the method returns, the camera device 171 * will be removed from memory and access to the closed camera device pointer will cause a crash.</p> 172 * 173 * @param device the camera device to be closed 174 * 175 * @return <ul> 176 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 177 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if device is NULL.</li></ul> 178 */ 179 camera_status_t ACameraDevice_close(ACameraDevice* device); 180 181 /** 182 * Return the camera id associated with this camera device. 183 * 184 * @param device the camera device to be closed 185 * 186 * @return camera ID string. The returned string is managed by framework and should not be 187 * delete/free by the application. Also the returned string must not be used after the device 188 * has been closed. 189 */ 190 const char* ACameraDevice_getId(const ACameraDevice* device); 191 192 typedef enum { 193 /** 194 * Create a request suitable for a camera preview window. Specifically, this 195 * means that high frame rate is given priority over the highest-quality 196 * post-processing. These requests would normally be used with the 197 * {@link ACameraCaptureSession_setRepeatingRequest} method. 198 * This template is guaranteed to be supported on all camera devices. 199 * 200 * @see ACameraDevice_createCaptureRequest 201 */ 202 TEMPLATE_PREVIEW = 1, 203 204 /** 205 * Create a request suitable for still image capture. Specifically, this 206 * means prioritizing image quality over frame rate. These requests would 207 * commonly be used with the {@link ACameraCaptureSession_capture} method. 208 * This template is guaranteed to be supported on all camera devices. 209 * 210 * @see ACameraDevice_createCaptureRequest 211 */ 212 TEMPLATE_STILL_CAPTURE = 2, 213 214 /** 215 * Create a request suitable for video recording. Specifically, this means 216 * that a stable frame rate is used, and post-processing is set for 217 * recording quality. These requests would commonly be used with the 218 * {@link ACameraCaptureSession_setRepeatingRequest} method. 219 * This template is guaranteed to be supported on all camera devices. 220 * 221 * @see ACameraDevice_createCaptureRequest 222 */ 223 TEMPLATE_RECORD = 3, 224 225 /** 226 * Create a request suitable for still image capture while recording 227 * video. Specifically, this means maximizing image quality without 228 * disrupting the ongoing recording. These requests would commonly be used 229 * with the {@link ACameraCaptureSession_capture} method while a request based on 230 * {@link TEMPLATE_RECORD} is is in use with {@link ACameraCaptureSession_setRepeatingRequest}. 231 * This template is guaranteed to be supported on all camera devices. 232 * 233 * @see ACameraDevice_createCaptureRequest 234 */ 235 TEMPLATE_VIDEO_SNAPSHOT = 4, 236 237 /** 238 * Create a request suitable for zero shutter lag still capture. This means 239 * means maximizing image quality without compromising preview frame rate. 240 * AE/AWB/AF should be on auto mode. 241 * 242 * @see ACameraDevice_createCaptureRequest 243 */ 244 TEMPLATE_ZERO_SHUTTER_LAG = 5, 245 246 /** 247 * A basic template for direct application control of capture 248 * parameters. All automatic control is disabled (auto-exposure, auto-white 249 * balance, auto-focus), and post-processing parameters are set to preview 250 * quality. The manual capture parameters (exposure, sensitivity, and so on) 251 * are set to reasonable defaults, but should be overriden by the 252 * application depending on the intended use case. 253 * This template is guaranteed to be supported on camera devices that support the 254 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR} capability. 255 * 256 * @see ACameraDevice_createCaptureRequest 257 */ 258 TEMPLATE_MANUAL = 6, 259 260 } ACameraDevice_request_template; 261 262 /** 263 * Create a ACaptureRequest for capturing images, initialized with template 264 * for a target use case. 265 * 266 * <p>The settings are chosen to be the best options for this camera device, 267 * so it is not recommended to reuse the same request for a different camera device.</p> 268 * 269 * @param device the camera device of interest 270 * @param templateId the type of capture request to be created. 271 * See {@link ACameraDevice_request_template}. 272 * @param request the output request will be stored here if the method call succeeds. 273 * 274 * @return <ul> 275 * <li>{@link ACAMERA_OK} if the method call succeeds. The created capture request will be 276 * filled in request argument.</li> 277 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if device or request is NULL, templateId 278 * is undefined or camera device does not support requested template. 279 * </li> 280 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed.</li> 281 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error.</li> 282 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error.</li> 283 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 284 * 285 * @see TEMPLATE_PREVIEW 286 * @see TEMPLATE_RECORD 287 * @see TEMPLATE_STILL_CAPTURE 288 * @see TEMPLATE_VIDEO_SNAPSHOT 289 * @see TEMPLATE_MANUAL 290 */ 291 camera_status_t ACameraDevice_createCaptureRequest( 292 const ACameraDevice* device, ACameraDevice_request_template templateId, 293 /*out*/ACaptureRequest** request); 294 295 296 typedef struct ACaptureSessionOutputContainer ACaptureSessionOutputContainer; 297 298 typedef struct ACaptureSessionOutput ACaptureSessionOutput; 299 300 /** 301 * Create a capture session output container. 302 * 303 * <p>The container is used in {@link ACameraDevice_createCaptureSession} method to create a capture 304 * session. Use {@link ACaptureSessionOutputContainer_free} to free the container and its memory 305 * after application no longer needs the ACaptureSessionOutputContainer.</p> 306 * 307 * @param container the output {@link ACaptureSessionOutputContainer} will be stored here if the 308 * method call succeeds. 309 * 310 * @return <ul> 311 * <li>{@link ACAMERA_OK} if the method call succeeds. The created container will be 312 * filled in container argument.</li> 313 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if container is NULL.</li></ul> 314 */ 315 camera_status_t ACaptureSessionOutputContainer_create( 316 /*out*/ACaptureSessionOutputContainer** container); 317 318 /** 319 * Free a capture session output container. 320 * 321 * @param container the {@link ACaptureSessionOutputContainer} to be freed. 322 * 323 * @see ACaptureSessionOutputContainer_create 324 */ 325 void ACaptureSessionOutputContainer_free(ACaptureSessionOutputContainer* container); 326 327 /** 328 * Create a ACaptureSessionOutput object. 329 * 330 * <p>The ACaptureSessionOutput is used in {@link ACaptureSessionOutputContainer_add} method to add 331 * an output {@link ANativeWindow} to ACaptureSessionOutputContainer. Use 332 * {@link ACaptureSessionOutput_free} to free the object and its memory after application no longer 333 * needs the {@link ACaptureSessionOutput}.</p> 334 * 335 * @param anw the {@link ANativeWindow} to be associated with the {@link ACaptureSessionOutput} 336 * @param output the output {@link ACaptureSessionOutput} will be stored here if the 337 * method call succeeds. 338 * 339 * @return <ul> 340 * <li>{@link ACAMERA_OK} if the method call succeeds. The created container will be 341 * filled in the output argument.</li> 342 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if anw or output is NULL.</li></ul> 343 * 344 * @see ACaptureSessionOutputContainer_add 345 */ 346 camera_status_t ACaptureSessionOutput_create( 347 ANativeWindow* anw, /*out*/ACaptureSessionOutput** output); 348 349 /** 350 * Free a ACaptureSessionOutput object. 351 * 352 * @param output the {@link ACaptureSessionOutput} to be freed. 353 * 354 * @see ACaptureSessionOutput_create 355 */ 356 void ACaptureSessionOutput_free(ACaptureSessionOutput* output); 357 358 /** 359 * Add an {@link ACaptureSessionOutput} object to {@link ACaptureSessionOutputContainer}. 360 * 361 * @param container the {@link ACaptureSessionOutputContainer} of interest. 362 * @param output the output {@link ACaptureSessionOutput} to be added to container. 363 * 364 * @return <ul> 365 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 366 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if container or output is NULL.</li></ul> 367 */ 368 camera_status_t ACaptureSessionOutputContainer_add( 369 ACaptureSessionOutputContainer* container, const ACaptureSessionOutput* output); 370 371 /** 372 * Remove an {@link ACaptureSessionOutput} object from {@link ACaptureSessionOutputContainer}. 373 * 374 * <p>This method has no effect if the ACaptureSessionOutput does not exist in 375 * ACaptureSessionOutputContainer.</p> 376 * 377 * @param container the {@link ACaptureSessionOutputContainer} of interest. 378 * @param output the output {@link ACaptureSessionOutput} to be removed from container. 379 * 380 * @return <ul> 381 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 382 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if container or output is NULL.</li></ul> 383 */ 384 camera_status_t ACaptureSessionOutputContainer_remove( 385 ACaptureSessionOutputContainer* container, const ACaptureSessionOutput* output); 386 387 /** 388 * Create a new camera capture session by providing the target output set of {@link ANativeWindow} 389 * to the camera device. 390 * 391 * <p>If there is a preexisting session, the previous session will be closed 392 * automatically. However, app still needs to call {@link ACameraCaptureSession_close} on previous 393 * session. Otherwise the resources held by previous session will NOT be freed.</p> 394 * 395 * <p>The active capture session determines the set of potential output {@link ANativeWindow}s for 396 * the camera device for each capture request. A given request may use all 397 * or only some of the outputs. Once the ACameraCaptureSession is created, requests can be 398 * submitted with {@link ACameraCaptureSession_capture} or 399 * {@link ACameraCaptureSession_setRepeatingRequest}.</p> 400 * 401 * <p>Often the {@link ANativeWindow} used with this method can be obtained from a <a href= 402 * "http://developer.android.com/reference/android/view/Surface.html">Surface</a> java object by 403 * {@link ANativeWindow_fromSurface} NDK method. Surfaces or ANativeWindow suitable for inclusion as a camera 404 * output can be created for various use cases and targets:</p> 405 * 406 * <ul> 407 * 408 * <li>For drawing to a 409 * <a href="http://developer.android.com/reference/android/view/SurfaceView.html">SurfaceView</a>: 410 * Once the SurfaceView's Surface is created, set the size 411 * of the Surface with 412 * <a href="http://developer.android.com/reference/android/view/SurfaceHolder.html#setFixedSize(int, int)"> 413 * android.view.SurfaceHolder\#setFixedSize</a> to be one of the PRIVATE output sizes 414 * returned by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 415 * and then obtain the Surface by calling <a href= 416 * "http://developer.android.com/reference/android/view/SurfaceHolder.html#getSurface()"> 417 * android.view.SurfaceHolder\#getSurface</a>. If the size is not set by the application, it will 418 * be rounded to the nearest supported size less than 1080p, by the camera device.</li> 419 * 420 * <li>For accessing through an OpenGL texture via a <a href= 421 * "http://developer.android.com/reference/android/graphics/SurfaceTexture.html">SurfaceTexture</a>: 422 * Set the size of the SurfaceTexture with <a href= 423 * "http://developer.android.com/reference/android/graphics/SurfaceTexture.html#setDefaultBufferSize(int, int)"> 424 * setDefaultBufferSize</a> to be one of the PRIVATE output sizes 425 * returned by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 426 * before creating a Surface from the SurfaceTexture with <a href= 427 * "http://developer.android.com/reference/android/view/Surface.html#Surface(android.graphics.SurfaceTexture)"> 428 * Surface\#Surface(SurfaceTextrue)</a>. If the size is not set by the application, it will be set to be the 429 * smallest supported size less than 1080p, by the camera device.</li> 430 * 431 * <li>For recording with <a href= 432 * "http://developer.android.com/reference/android/media/MediaCodec.html"> 433 * MediaCodec</a>: Call 434 * <a href= 435 * "http://developer.android.com/reference/android/media/MediaCodec.html#createInputSurface()"> 436 * android.media.MediaCodec\#createInputSurface</a> after configuring 437 * the media codec to use one of the PRIVATE output sizes 438 * returned by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}. 439 * </li> 440 * 441 * <li>For recording with <a href= 442 * "http://developer.android.com/reference/android/media/MediaRecorder.html"> 443 * MediaRecorder</a>: Call 444 * <a href="http://developer.android.com/reference/android/media/MediaRecorder.html#getSurface()"> 445 * android.media.MediaRecorder\#getSurface</a> after configuring the media recorder to use 446 * one of the PRIVATE output sizes returned by 447 * {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}, or configuring it to use one of the supported 448 * <a href="http://developer.android.com/reference/android/media/CamcorderProfile.html"> 449 * CamcorderProfiles</a>.</li> 450 * 451 * <li>For efficient YUV processing with <a href= 452 * "http://developer.android.com/reference/android/renderscript/package-summary.html"> 453 * RenderScript</a>: 454 * Create a RenderScript 455 * <a href="http://developer.android.com/reference/android/renderscript/Allocation.html"> 456 * Allocation</a> with a supported YUV 457 * type, the IO_INPUT flag, and one of the YUV output sizes returned by 458 * {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}, 459 * Then obtain the Surface with 460 * <a href="http://developer.android.com/reference/android/renderscript/Allocation.html#getSurface()"> 461 * Allocation#getSurface}</a>.</li> 462 * 463 * <li>For access to RAW, uncompressed YUV, or compressed JPEG data in the application: Create an 464 * {@link AImageReader} object using the {@link AImageReader_new} method with one of the supported 465 * output formats given by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}. Then obtain a 466 * ANativeWindow from it with {@link AImageReader_getWindow}. 467 * If the AImageReader size is not set to a supported size, it will be rounded to a supported 468 * size less than 1080p by the camera device. 469 * </li> 470 * 471 * </ul> 472 * 473 * <p>The camera device will query each ANativeWindow's size and formats upon this 474 * call, so they must be set to a valid setting at this time.</p> 475 * 476 * <p>It can take several hundred milliseconds for the session's configuration to complete, 477 * since camera hardware may need to be powered on or reconfigured.</p> 478 * 479 * <p>If a prior ACameraCaptureSession already exists when this method is called, the previous 480 * session will no longer be able to accept new capture requests and will be closed. Any 481 * in-progress capture requests made on the prior session will be completed before it's closed. 482 * To minimize the transition time, 483 * the ACameraCaptureSession_abortCaptures method can be used to discard the remaining 484 * requests for the prior capture session before a new one is created. Note that once the new 485 * session is created, the old one can no longer have its captures aborted.</p> 486 * 487 * <p>Using larger resolution outputs, or more outputs, can result in slower 488 * output rate from the device.</p> 489 * 490 * <p>Configuring a session with an empty list will close the current session, if 491 * any. This can be used to release the current session's target surfaces for another use.</p> 492 * 493 * <p>While any of the sizes from {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} can be used when 494 * a single output stream is configured, a given camera device may not be able to support all 495 * combination of sizes, formats, and targets when multiple outputs are configured at once. The 496 * tables below list the maximum guaranteed resolutions for combinations of streams and targets, 497 * given the capabilities of the camera device.</p> 498 * 499 * <p>If an application tries to create a session using a set of targets that exceed the limits 500 * described in the below tables, one of three possibilities may occur. First, the session may 501 * be successfully created and work normally. Second, the session may be successfully created, 502 * but the camera device won't meet the frame rate guarantees as described in 503 * {@link ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. Or third, if the output set 504 * cannot be used at all, session creation will fail entirely, with 505 * {@link ACAMERA_ERROR_STREAM_CONFIGURE_FAIL} being returned.</p> 506 * 507 * <p>For the type column `PRIV` refers to output format {@link AIMAGE_FORMAT_PRIVATE}, 508 * `YUV` refers to output format {@link AIMAGE_FORMAT_YUV_420_888}, 509 * `JPEG` refers to output format {@link AIMAGE_FORMAT_JPEG}, 510 * and `RAW` refers to output format {@link AIMAGE_FORMAT_RAW16} 511 * 512 * 513 * <p>For the maximum size column, `PREVIEW` refers to the best size match to the 514 * device's screen resolution, or to 1080p `(1920x1080)`, whichever is 515 * smaller. `RECORD` refers to the camera device's maximum supported recording resolution, 516 * as determined by <a href="http://developer.android.com/reference/android/media/CamcorderProfile.html"> 517 * android.media.CamcorderProfiles</a>. And `MAXIMUM` refers to the 518 * camera device's maximum output resolution for that format or target from 519 * {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}.</p> 520 * 521 * <p>To use these tables, determine the number and the formats/targets of outputs needed, and 522 * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes 523 * that can be used; it is guaranteed that for those targets, the listed sizes and anything 524 * smaller from the list given by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} can be 525 * successfully used to create a session. For example, if a row indicates that a 8 megapixel 526 * (MP) YUV_420_888 output can be used together with a 2 MP `PRIV` output, then a session 527 * can be created with targets `[8 MP YUV, 2 MP PRIV]` or targets `[2 MP YUV, 2 MP PRIV]`; 528 * but a session with targets `[8 MP YUV, 4 MP PRIV]`, targets `[4 MP YUV, 4 MP PRIV]`, 529 * or targets `[8 MP PRIV, 2 MP YUV]` would not be guaranteed to work, unless 530 * some other row of the table lists such a combination.</p> 531 * 532 * <p>Legacy devices ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 533 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at 534 * least the following stream combinations: 535 * 536 * <table> 537 * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr> 538 * <tr> <th colspan="2" id="rb">Target 1</th> <th colspan="2" id="rb">Target 2</th> <th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 539 * <tr> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th></tr> 540 * <tr> <td>`PRIV`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>Simple preview, GPU video processing, or no-preview video recording.</td> </tr> 541 * <tr> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-viewfinder still image capture.</td> </tr> 542 * <tr> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>In-application video/image processing.</td> </tr> 543 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Standard still imaging.</td> </tr> 544 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>In-app processing plus still capture.</td> </tr> 545 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td colspan="2" id="rb"></td> <td>Standard recording.</td> </tr> 546 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td colspan="2" id="rb"></td> <td>Preview plus in-app processing.</td> </tr> 547 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>Still capture plus in-app processing.</td> </tr> 548 * </table><br> 549 * </p> 550 * 551 * <p>Limited-level ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 552 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 553 * support at least the following stream combinations in addition to those for 554 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: 555 * 556 * <table> 557 * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr> 558 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 559 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 560 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`RECORD `</td> <td colspan="2" id="rb"></td> <td>High-resolution video recording with preview.</td> </tr> 561 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`RECORD `</td> <td colspan="2" id="rb"></td> <td>High-resolution in-app video processing with preview.</td> </tr> 562 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`RECORD `</td> <td colspan="2" id="rb"></td> <td>Two-input in-app video processing.</td> </tr> 563 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`RECORD `</td> <td>`JPEG`</td><td id="rb">`RECORD `</td> <td>High-resolution recording with video snapshot.</td> </tr> 564 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`RECORD `</td> <td>`JPEG`</td><td id="rb">`RECORD `</td> <td>High-resolution in-app processing with video snapshot.</td> </tr> 565 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>Two-input in-app processing with still capture.</td> </tr> 566 * </table><br> 567 * </p> 568 * 569 * <p>FULL-level ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 570 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 571 * support at least the following stream combinations in addition to those for 572 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 573 * 574 * <table> 575 * <tr><th colspan="7">FULL-level additional guaranteed configurations</th></tr> 576 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 577 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 578 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 579 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 580 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 581 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>Video recording with maximum-size video snapshot</td> </tr> 582 * <tr> <td>`YUV `</td><td id="rb">`640x480`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Standard video recording plus maximum-resolution in-app processing.</td> </tr> 583 * <tr> <td>`YUV `</td><td id="rb">`640x480`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Preview plus two-input maximum-resolution in-app processing.</td> </tr> 584 * </table><br> 585 * </p> 586 * 587 * <p>RAW-capability ({@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES} includes 588 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 589 * at least the following stream combinations on both 590 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 591 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 592 * 593 * <table> 594 * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr> 595 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 596 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 597 * <tr> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-preview DNG capture.</td> </tr> 598 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Standard DNG capture.</td> </tr> 599 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>In-app processing plus DNG capture.</td> </tr> 600 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Video recording with DNG capture.</td> </tr> 601 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Preview with in-app processing and DNG capture.</td> </tr> 602 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Two-input in-app processing plus DNG capture.</td> </tr> 603 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Still capture with simultaneous JPEG and DNG.</td> </tr> 604 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>In-app processing with simultaneous JPEG and DNG.</td> </tr> 605 * </table><br> 606 * </p> 607 * 608 * <p>BURST-capability ({@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES} includes 609 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices 610 * support at least the below stream combinations in addition to those for 611 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all 612 * FULL-level devices support the BURST capability, and the below list is a strict subset of the 613 * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that 614 * support the BURST_CAPTURE capability. 615 * 616 * <table> 617 * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr> 618 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th rowspan="2">Sample use case(s)</th> </tr> 619 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 620 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`MAXIMUM`</td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 621 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 622 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 623 * </table><br> 624 * </p> 625 * 626 * <p>LEVEL-3 ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 627 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) 628 * support at least the following stream combinations in addition to the combinations for 629 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and for 630 * RAW capability ({@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES} includes 631 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}): 632 * 633 * <table> 634 * <tr><th colspan="11">LEVEL-3 additional guaranteed configurations</th></tr> 635 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th><th colspan="2" id="rb">Target 4</th><th rowspan="2">Sample use case(s)</th> </tr> 636 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 637 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`640x480`</td> <td>`YUV`</td><td id="rb">`MAXIMUM`</td> <td>`RAW`</td><td id="rb">`MAXIMUM`</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 638 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`640x480`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>`RAW`</td><td id="rb">`MAXIMUM`</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 639 * </table><br> 640 * </p> 641 * 642 * <p>Since the capabilities of camera devices vary greatly, a given camera device may support 643 * target combinations with sizes outside of these guarantees, but this can only be tested for 644 * by attempting to create a session with such targets.</p> 645 * 646 * @param device the camera device of interest. 647 * @param outputs the {@link ACaptureSessionOutputContainer} describes all output streams. 648 * @param callbacks the {@link ACameraCaptureSession_stateCallbacks capture session state callbacks}. 649 * @param session the created {@link ACameraCaptureSession} will be filled here if the method call 650 * succeeds. 651 * 652 * @return <ul> 653 * <li>{@link ACAMERA_OK} if the method call succeeds. The created capture session will be 654 * filled in session argument.</li> 655 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if any of device, outputs, callbacks or 656 * session is NULL.</li> 657 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed.</li> 658 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error.</li> 659 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error.</li> 660 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 661 */ 662 camera_status_t ACameraDevice_createCaptureSession( 663 ACameraDevice* device, 664 const ACaptureSessionOutputContainer* outputs, 665 const ACameraCaptureSession_stateCallbacks* callbacks, 666 /*out*/ACameraCaptureSession** session); 667 668 #endif /* __ANDROID_API__ >= 24 */ 669 670 #if __ANDROID_API__ >= 28 671 672 /** 673 * Create a shared ACaptureSessionOutput object. 674 * 675 * <p>The ACaptureSessionOutput is used in {@link ACaptureSessionOutputContainer_add} method to add 676 * an output {@link ANativeWindow} to ACaptureSessionOutputContainer. Use 677 * {@link ACaptureSessionOutput_free} to free the object and its memory after application no longer 678 * needs the {@link ACaptureSessionOutput}. A shared ACaptureSessionOutput can be further modified 679 * via {@link ACaptureSessionSharedOutput_add} or {@link ACaptureSessionSharedOutput_remove} and 680 * must be updated via {@link ACameraCaptureSession_updateSharedOutput}.</p> 681 * 682 * @param anw the {@link ANativeWindow} to be associated with the {@link ACaptureSessionOutput} 683 * @param output the output {@link ACaptureSessionOutput} will be stored here if the 684 * method call succeeds. 685 * 686 * @return <ul> 687 * <li>{@link ACAMERA_OK} if the method call succeeds. The created container will be 688 * filled in the output argument.</li> 689 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if anw or output is NULL.</li></ul> 690 * 691 * @see ACaptureSessionOutputContainer_add 692 */ 693 camera_status_t ACaptureSessionSharedOutput_create( 694 ANativeWindow* anw, /*out*/ACaptureSessionOutput** output); 695 696 /** 697 * Add a native window to shared ACaptureSessionOutput. 698 * 699 * The ACaptureSessionOutput must be created via {@link ACaptureSessionSharedOutput_create}. 700 * 701 * @param output the shared ACaptureSessionOutput to be extended. 702 * @param anw The new native window. 703 * 704 * @return <ul> 705 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 706 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if anw or output is NULL; or output is not 707 * shared see {@link ACaptureSessionSharedOutput_create}; or anw matches with the native 708 * window associated with ACaptureSessionOutput; or anw is already present inside 709 * ACaptureSessionOutput.</li></ul> 710 */ 711 camera_status_t ACaptureSessionSharedOutput_add(ACaptureSessionOutput *output, ANativeWindow *anw); 712 713 /** 714 * Remove a native window from shared ACaptureSessionOutput. 715 * 716 * @param output the {@link ACaptureSessionOutput} to be modified. 717 * @param anw The native window to be removed. 718 * 719 * @return <ul> 720 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 721 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if anw or output is NULL; or output is not 722 * shared see {@link ACaptureSessionSharedOutput_create}; or anw matches with the native 723 * window associated with ACaptureSessionOutput; or anw is not present inside 724 * ACaptureSessionOutput.</li></ul> 725 */ 726 camera_status_t ACaptureSessionSharedOutput_remove(ACaptureSessionOutput *output, 727 ANativeWindow* anw); 728 729 /** 730 * Create a new camera capture session similar to {@link ACameraDevice_createCaptureSession}. This 731 * function allows clients to pass additional session parameters during session initialization. For 732 * further information about session parameters see {@link ACAMERA_REQUEST_AVAILABLE_SESSION_KEYS}. 733 * 734 * @param device the camera device of interest. 735 * @param outputs the {@link ACaptureSessionOutputContainer} describes all output streams. 736 * @param sessionParameters An optional capture request that contains the initial values of session 737 * parameters advertised in 738 * {@link ACAMERA_REQUEST_AVAILABLE_SESSION_KEYS}. 739 * @param callbacks the {@link ACameraCaptureSession_stateCallbacks} 740 * capture session state callbacks. 741 * @param session the created {@link ACameraCaptureSession} will be filled here if the method call 742 * succeeds. 743 * 744 * @return <ul> 745 * <li>{@link ACAMERA_OK} if the method call succeeds. The created capture session will be 746 * filled in session argument.</li> 747 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if any of device, outputs, callbacks or 748 * session is NULL.</li> 749 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed.</li> 750 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error.</li> 751 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error. 752 * </li> 753 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 754 */ 755 camera_status_t ACameraDevice_createCaptureSessionWithSessionParameters( 756 ACameraDevice* device, 757 const ACaptureSessionOutputContainer* outputs, 758 const ACaptureRequest* sessionParameters, 759 const ACameraCaptureSession_stateCallbacks* callbacks, 760 /*out*/ACameraCaptureSession** session); 761 762 #endif /* __ANDROID_API__ >= 28 */ 763 764 __END_DECLS 765 766 #endif /* _NDK_CAMERA_DEVICE_H */ 767 768 /** @} */ 769
