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