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 NdkCameraCaptureSession.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 #include <stdbool.h> 37 38 #include "NdkCameraError.h" 39 #include "NdkCameraMetadata.h" 40 #include "NdkCaptureRequest.h" 41 #include "NdkCameraWindowType.h" 42 43 #ifndef _NDK_CAMERA_CAPTURE_SESSION_H 44 #define _NDK_CAMERA_CAPTURE_SESSION_H 45 46 __BEGIN_DECLS 47 48 #if __ANDROID_API__ >= 24 49 50 /** 51 * ACameraCaptureSession is an opaque type that manages frame captures of a camera device. 52 * 53 * A pointer can be obtained using {@link ACameraDevice_createCaptureSession} method. 54 */ 55 typedef struct ACameraCaptureSession ACameraCaptureSession; 56 57 /** 58 * The definition of camera capture session state callback. 59 * 60 * @param context The optional application context provided by user in 61 * {@link ACameraCaptureSession_stateCallbacks}. 62 * @param session The camera capture session whose state is changing. 63 */ 64 typedef void (*ACameraCaptureSession_stateCallback)(void* context, ACameraCaptureSession *session); 65 66 typedef struct ACameraCaptureSession_stateCallbacks { 67 /// optional application context. 68 void* context; 69 70 /** 71 * This callback is called when the session is closed and deleted from memory. 72 * 73 * <p>A session is closed when {@link ACameraCaptureSession_close} is called, a new session 74 * is created by the parent camera device, 75 * or when the parent camera device is closed (either by the user closing the device, 76 * or due to a camera device disconnection or fatal error).</p> 77 * 78 * <p>Once this callback is called, all access to this ACameraCaptureSession object will cause 79 * a crash.</p> 80 */ 81 ACameraCaptureSession_stateCallback onClosed; 82 83 /** 84 * This callback is called every time the session has no more capture requests to process. 85 * 86 * <p>This callback will be invoked any time the session finishes processing 87 * all of its active capture requests, and no repeating request or burst is set up.</p> 88 */ 89 ACameraCaptureSession_stateCallback onReady; 90 91 /** 92 * This callback is called when the session starts actively processing capture requests. 93 * 94 * <p>If the session runs out of capture requests to process and calls {@link onReady}, 95 * then this callback will be invoked again once new requests are submitted for capture.</p> 96 */ 97 ACameraCaptureSession_stateCallback onActive; 98 } ACameraCaptureSession_stateCallbacks; 99 100 /// Enum for describing error reason in {@link ACameraCaptureFailure} 101 enum { 102 /** 103 * The capture session has dropped this frame due to an 104 * {@link ACameraCaptureSession_abortCaptures} call. 105 */ 106 CAPTURE_FAILURE_REASON_FLUSHED = 0, 107 108 /** 109 * The capture session has dropped this frame due to an error in the framework. 110 */ 111 CAPTURE_FAILURE_REASON_ERROR 112 }; 113 114 /// Struct to describe a capture failure 115 typedef struct ACameraCaptureFailure { 116 /** 117 * The frame number associated with this failed capture. 118 * 119 * <p>Whenever a request has been processed, regardless of failed capture or success, 120 * it gets a unique frame number assigned to its future result/failed capture.</p> 121 * 122 * <p>This value monotonically increments, starting with 0, 123 * for every new result or failure; and the scope is the lifetime of the 124 * {@link ACameraDevice}.</p> 125 */ 126 int64_t frameNumber; 127 128 /** 129 * Determine why the request was dropped, whether due to an error or to a user 130 * action. 131 * 132 * @see CAPTURE_FAILURE_REASON_ERROR 133 * @see CAPTURE_FAILURE_REASON_FLUSHED 134 */ 135 int reason; 136 137 /** 138 * The sequence ID for this failed capture that was returned by the 139 * {@link ACameraCaptureSession_capture} or {@link ACameraCaptureSession_setRepeatingRequest}. 140 * 141 * <p>The sequence ID is a unique monotonically increasing value starting from 0, 142 * incremented every time a new group of requests is submitted to the ACameraDevice.</p> 143 */ 144 int sequenceId; 145 146 /** 147 * Determine if the image was captured from the camera. 148 * 149 * <p>If the image was not captured, no image buffers will be available. 150 * If the image was captured, then image buffers may be available.</p> 151 * 152 */ 153 bool wasImageCaptured; 154 } ACameraCaptureFailure; 155 156 /** 157 * The definition of camera capture start callback. 158 * 159 * @param context The optional application context provided by user in 160 * {@link ACameraCaptureSession_captureCallbacks}. 161 * @param session The camera capture session of interest. 162 * @param request The capture request that is starting. Note that this pointer points to a copy of 163 * capture request sent by application, so the address is different to what 164 * application sent but the content will match. This request will be freed by 165 * framework immediately after this callback returns. 166 * @param timestamp The timestamp when the capture is started. This timestmap will match 167 * {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 168 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted} callback. 169 */ 170 typedef void (*ACameraCaptureSession_captureCallback_start)( 171 void* context, ACameraCaptureSession* session, 172 const ACaptureRequest* request, int64_t timestamp); 173 174 /** 175 * The definition of camera capture progress/result callback. 176 * 177 * @param context The optional application context provided by user in 178 * {@link ACameraCaptureSession_captureCallbacks}. 179 * @param session The camera capture session of interest. 180 * @param request The capture request of interest. Note that this pointer points to a copy of 181 * capture request sent by application, so the address is different to what 182 * application sent but the content will match. This request will be freed by 183 * framework immediately after this callback returns. 184 * @param result The capture result metadata reported by camera device. The memory is managed by 185 * camera framework. Do not access this pointer after this callback returns. 186 */ 187 typedef void (*ACameraCaptureSession_captureCallback_result)( 188 void* context, ACameraCaptureSession* session, 189 ACaptureRequest* request, const ACameraMetadata* result); 190 191 /** 192 * The definition of camera capture failure callback. 193 * 194 * @param context The optional application context provided by user in 195 * {@link ACameraCaptureSession_captureCallbacks}. 196 * @param session The camera capture session of interest. 197 * @param request The capture request of interest. Note that this pointer points to a copy of 198 * capture request sent by application, so the address is different to what 199 * application sent but the content will match. This request will be freed by 200 * framework immediately after this callback returns. 201 * @param failure The {@link ACameraCaptureFailure} desribes the capture failure. The memory is 202 * managed by camera framework. Do not access this pointer after this callback 203 * returns. 204 */ 205 typedef void (*ACameraCaptureSession_captureCallback_failed)( 206 void* context, ACameraCaptureSession* session, 207 ACaptureRequest* request, ACameraCaptureFailure* failure); 208 209 /** 210 * The definition of camera sequence end callback. 211 * 212 * @param context The optional application context provided by user in 213 * {@link ACameraCaptureSession_captureCallbacks}. 214 * @param session The camera capture session of interest. 215 * @param sequenceId The capture sequence ID of the finished sequence. 216 * @param frameNumber The frame number of the last frame of this sequence. 217 */ 218 typedef void (*ACameraCaptureSession_captureCallback_sequenceEnd)( 219 void* context, ACameraCaptureSession* session, 220 int sequenceId, int64_t frameNumber); 221 222 /** 223 * The definition of camera sequence aborted callback. 224 * 225 * @param context The optional application context provided by user in 226 * {@link ACameraCaptureSession_captureCallbacks}. 227 * @param session The camera capture session of interest. 228 * @param sequenceId The capture sequence ID of the aborted sequence. 229 */ 230 typedef void (*ACameraCaptureSession_captureCallback_sequenceAbort)( 231 void* context, ACameraCaptureSession* session, 232 int sequenceId); 233 234 /** 235 * The definition of camera buffer lost callback. 236 * 237 * @param context The optional application context provided by user in 238 * {@link ACameraCaptureSession_captureCallbacks}. 239 * @param session The camera capture session of interest. 240 * @param request The capture request of interest. Note that this pointer points to a copy of 241 * capture request sent by application, so the address is different to what 242 * application sent but the content will match. This request will be freed by 243 * framework immediately after this callback returns. 244 * @param window The {@link ANativeWindow} that the lost buffer would have been sent to. 245 * @param frameNumber The frame number of the lost buffer. 246 */ 247 typedef void (*ACameraCaptureSession_captureCallback_bufferLost)( 248 void* context, ACameraCaptureSession* session, 249 ACaptureRequest* request, ACameraWindowType* window, int64_t frameNumber); 250 251 typedef struct ACameraCaptureSession_captureCallbacks { 252 /// optional application context. 253 void* context; 254 255 /** 256 * This callback is called when the camera device has started capturing 257 * the output image for the request, at the beginning of image exposure. 258 * 259 * <p>This callback is invoked right as 260 * the capture of a frame begins, so it is the most appropriate time 261 * for playing a shutter sound, or triggering UI indicators of capture.</p> 262 * 263 * <p>The request that is being used for this capture is provided, along 264 * with the actual timestamp for the start of exposure. 265 * This timestamp matches the timestamps that will be 266 * included in {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 267 * {@link onCaptureCompleted} callback, 268 * and in the buffers sent to each output ANativeWindow. These buffer 269 * timestamps are accessible through, for example, 270 * {@link AImage_getTimestamp} or 271 * <a href="http://developer.android.com/reference/android/graphics/SurfaceTexture.html#getTimestamp()"> 272 * android.graphics.SurfaceTexture#getTimestamp()</a>.</p> 273 * 274 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 275 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 276 * 277 */ 278 ACameraCaptureSession_captureCallback_start onCaptureStarted; 279 280 /** 281 * This callback is called when an image capture makes partial forward progress; some 282 * (but not all) results from an image capture are available. 283 * 284 * <p>The result provided here will contain some subset of the fields of 285 * a full result. Multiple {@link onCaptureProgressed} calls may happen per 286 * capture; a given result field will only be present in one partial 287 * capture at most. The final {@link onCaptureCompleted} call will always 288 * contain all the fields (in particular, the union of all the fields of all 289 * the partial results composing the total result).</p> 290 * 291 * <p>For each request, some result data might be available earlier than others. The typical 292 * delay between each partial result (per request) is a single frame interval. 293 * For performance-oriented use-cases, applications should query the metadata they need 294 * to make forward progress from the partial results and avoid waiting for the completed 295 * result.</p> 296 * 297 * <p>For a particular request, {@link onCaptureProgressed} may happen before or after 298 * {@link onCaptureStarted}.</p> 299 * 300 * <p>Each request will generate at least `1` partial results, and at most 301 * {@link ACAMERA_REQUEST_PARTIAL_RESULT_COUNT} partial results.</p> 302 * 303 * <p>Depending on the request settings, the number of partial results per request 304 * will vary, although typically the partial count could be the same as long as the 305 * camera device subsystems enabled stay the same.</p> 306 * 307 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 308 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 309 */ 310 ACameraCaptureSession_captureCallback_result onCaptureProgressed; 311 312 /** 313 * This callback is called when an image capture has fully completed and all the 314 * result metadata is available. 315 * 316 * <p>This callback will always fire after the last {@link onCaptureProgressed}; 317 * in other words, no more partial results will be delivered once the completed result 318 * is available.</p> 319 * 320 * <p>For performance-intensive use-cases where latency is a factor, consider 321 * using {@link onCaptureProgressed} instead.</p> 322 * 323 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 324 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 325 */ 326 ACameraCaptureSession_captureCallback_result onCaptureCompleted; 327 328 /** 329 * This callback is called instead of {@link onCaptureCompleted} when the 330 * camera device failed to produce a capture result for the 331 * request. 332 * 333 * <p>Other requests are unaffected, and some or all image buffers from 334 * the capture may have been pushed to their respective output 335 * streams.</p> 336 * 337 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 338 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 339 * 340 * @see ACameraCaptureFailure 341 */ 342 ACameraCaptureSession_captureCallback_failed onCaptureFailed; 343 344 /** 345 * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, 346 * when a capture sequence finishes and all capture result 347 * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. 348 * 349 * <p>In total, there will be at least one result/failure returned by this listener 350 * before this callback is invoked. If the capture sequence is aborted before any 351 * requests have been processed, {@link onCaptureSequenceAborted} is invoked instead.</p> 352 */ 353 ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; 354 355 /** 356 * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, 357 * when a capture sequence aborts before any capture result 358 * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. 359 * 360 * <p>Due to the asynchronous nature of the camera device, not all submitted captures 361 * are immediately processed. It is possible to clear out the pending requests 362 * by a variety of operations such as {@link ACameraCaptureSession_stopRepeating} or 363 * {@link ACameraCaptureSession_abortCaptures}. When such an event happens, 364 * {@link onCaptureSequenceCompleted} will not be called.</p> 365 */ 366 ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; 367 368 /** 369 * This callback is called if a single buffer for a capture could not be sent to its 370 * destination ANativeWindow. 371 * 372 * <p>If the whole capture failed, then {@link onCaptureFailed} will be called instead. If 373 * some but not all buffers were captured but the result metadata will not be available, 374 * then onCaptureFailed will be invoked with {@link ACameraCaptureFailure#wasImageCaptured} 375 * returning true, along with one or more calls to {@link onCaptureBufferLost} for the 376 * failed outputs.</p> 377 * 378 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 379 * submitted, but the contents the ACaptureRequest will match what application submitted. 380 * The ANativeWindow pointer will always match what application submitted in 381 * {@link ACameraDevice_createCaptureSession}</p> 382 * 383 */ 384 ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; 385 } ACameraCaptureSession_captureCallbacks; 386 387 enum { 388 CAPTURE_SEQUENCE_ID_NONE = -1 389 }; 390 391 /** 392 * Close this capture session. 393 * 394 * <p>Closing a session frees up the target output Surfaces of the session for reuse with either 395 * a new session, or to other APIs that can draw to Surfaces.</p> 396 * 397 * <p>Note that creating a new capture session with {@link ACameraDevice_createCaptureSession} 398 * will close any existing capture session automatically, and call the older session listener's 399 * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback. Using 400 * {@link ACameraDevice_createCaptureSession} directly without closing is the recommended approach 401 * for quickly switching to a new session, since unchanged target outputs can be reused more 402 * efficiently.</p> 403 * 404 * <p>After a session is closed and before {@link ACameraCaptureSession_stateCallbacks#onClosed} 405 * is called, all methods invoked on the session will return {@link ACAMERA_ERROR_SESSION_CLOSED}, 406 * and any repeating requests are stopped (as if {@link ACameraCaptureSession_stopRepeating} was 407 * called). However, any in-progress capture requests submitted to the session will be completed as 408 * normal; once all captures have completed and the session has been torn down, 409 * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback will be called and the seesion 410 * will be removed from memory.</p> 411 * 412 * <p>Closing a session is idempotent; closing more than once has no effect.</p> 413 * 414 * @param session the capture session of interest 415 */ 416 void ACameraCaptureSession_close(ACameraCaptureSession* session); 417 418 struct ACameraDevice; 419 typedef struct ACameraDevice ACameraDevice; 420 421 /** 422 * Get the ACameraDevice pointer associated with this capture session in the device argument 423 * if the method succeeds. 424 * 425 * @param session the capture session of interest 426 * @param device the {@link ACameraDevice} associated with session. Will be set to NULL 427 * if the session is closed or this method fails. 428 * @return <ul><li> 429 * {@link ACAMERA_OK} if the method call succeeds. The {@link ACameraDevice} 430 * will be stored in device argument</li> 431 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or device is NULL</li> 432 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 433 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 434 * 435 */ 436 camera_status_t ACameraCaptureSession_getDevice( 437 ACameraCaptureSession* session, /*out*/ACameraDevice** device) __INTRODUCED_IN(24); 438 439 /** 440 * Submit an array of requests to be captured in sequence as a burst in the minimum of time possible. 441 * 442 * <p>The burst will be captured in the minimum amount of time possible, and will not be 443 * interleaved with requests submitted by other capture or repeat calls.</p> 444 * 445 * <p>Each capture produces one {@link ACameraMetadata} as a capture result and image buffers for 446 * one or more target {@link ANativeWindow}s. The target ANativeWindows (set with 447 * {@link ACaptureRequest_addTarget}) must be a subset of the ANativeWindow provided when 448 * this capture session was created.</p> 449 * 450 * @param session the capture session of interest 451 * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated this capture 452 * sequence. No capture callback will be fired if this is set to NULL. 453 * @param numRequests number of requests in requests argument. Must be at least 1. 454 * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least 455 * numRequests. 456 * @param captureSequenceId the capture sequence ID associated with this capture method invocation 457 * will be stored here if this argument is not NULL and the method call succeeds. 458 * When this argument is set to NULL, the capture sequence ID will not be returned. 459 * 460 * @return <ul><li> 461 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 462 * if it is not NULL.</li> 463 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or requests is NULL, or 464 * if numRequests < 1</li> 465 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 466 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 467 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 468 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 469 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 470 */ 471 camera_status_t ACameraCaptureSession_capture( 472 ACameraCaptureSession* session, 473 /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, 474 int numRequests, ACaptureRequest** requests, 475 /*optional*/int* captureSequenceId) __INTRODUCED_IN(24); 476 477 /** 478 * Request endlessly repeating capture of a sequence of images by this capture session. 479 * 480 * <p>With this method, the camera device will continually capture images, 481 * cycling through the settings in the provided list of 482 * {@link ACaptureRequest}, at the maximum rate possible.</p> 483 * 484 * <p>If a request is submitted through {@link ACameraCaptureSession_capture}, 485 * the current repetition of the request list will be 486 * completed before the higher-priority request is handled. This guarantees 487 * that the application always receives a complete repeat burst captured in 488 * minimal time, instead of bursts interleaved with higher-priority 489 * captures, or incomplete captures.</p> 490 * 491 * <p>Repeating burst requests are a simple way for an application to 492 * maintain a preview or other continuous stream of frames where each 493 * request is different in a predicatable way, without having to continually 494 * submit requests through {@link ACameraCaptureSession_capture}.</p> 495 * 496 * <p>To stop the repeating capture, call {@link ACameraCaptureSession_stopRepeating}. Any 497 * ongoing burst will still be completed, however. Calling 498 * {@link ACameraCaptureSession_abortCaptures} will also clear the request.</p> 499 * 500 * <p>Calling this method will replace a previously-set repeating requests 501 * set up by this method, although any in-progress burst will be completed before the new repeat 502 * burst will be used.</p> 503 * 504 * @param session the capture session of interest 505 * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated with this 506 * capture sequence. No capture callback will be fired if callbacks is set to NULL. 507 * @param numRequests number of requests in requests array. Must be at least 1. 508 * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least 509 * numRequests. 510 * @param captureSequenceId the capture sequence ID associated with this capture method invocation 511 * will be stored here if this argument is not NULL and the method call succeeds. 512 * When this argument is set to NULL, the capture sequence ID will not be returned. 513 * 514 * @return <ul><li> 515 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 516 * if it is not NULL.</li> 517 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or requests is NULL, or 518 * if numRequests < 1</li> 519 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 520 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 521 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 522 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 523 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 524 */ 525 camera_status_t ACameraCaptureSession_setRepeatingRequest( 526 ACameraCaptureSession* session, 527 /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, 528 int numRequests, ACaptureRequest** requests, 529 /*optional*/int* captureSequenceId) __INTRODUCED_IN(24); 530 531 /** 532 * Cancel any ongoing repeating capture set by {@link ACameraCaptureSession_setRepeatingRequest}. 533 * Has no effect on requests submitted through {@link ACameraCaptureSession_capture}. 534 * 535 * <p>Any currently in-flight captures will still complete, as will any burst that is 536 * mid-capture. To ensure that the device has finished processing all of its capture requests 537 * and is in ready state, wait for the {@link ACameraCaptureSession_stateCallbacks#onReady} callback 538 * after calling this method.</p> 539 * 540 * @param session the capture session of interest 541 * 542 * @return <ul><li> 543 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 544 * if it is not NULL.</li> 545 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session is NULL.</li> 546 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 547 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 548 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 549 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 550 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 551 */ 552 camera_status_t ACameraCaptureSession_stopRepeating(ACameraCaptureSession* session) 553 __INTRODUCED_IN(24); 554 555 /** 556 * Discard all captures currently pending and in-progress as fast as possible. 557 * 558 * <p>The camera device will discard all of its current work as fast as possible. Some in-flight 559 * captures may complete successfully and call 560 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted}, 561 * while others will trigger their {@link ACameraCaptureSession_captureCallbacks#onCaptureFailed} 562 * callbacks. If a repeating request list is set, it will be cleared.</p> 563 * 564 * <p>This method is the fastest way to switch the camera device to a new session with 565 * {@link ACameraDevice_createCaptureSession}, at the cost of discarding in-progress 566 * work. It must be called before the new session is created. Once all pending requests are 567 * either completed or thrown away, the {@link ACameraCaptureSession_stateCallbacks#onReady} 568 * callback will be called, if the session has not been closed. Otherwise, the 569 * {@link ACameraCaptureSession_stateCallbacks#onClosed} 570 * callback will be fired when a new session is created by the camera device and the previous 571 * session is being removed from memory.</p> 572 * 573 * <p>Cancelling will introduce at least a brief pause in the stream of data from the camera 574 * device, since once the camera device is emptied, the first new request has to make it through 575 * the entire camera pipeline before new output buffers are produced.</p> 576 * 577 * <p>This means that using ACameraCaptureSession_abortCaptures to simply remove pending requests is 578 * not recommended; it's best used for quickly switching output configurations, or for cancelling 579 * long in-progress requests (such as a multi-second capture).</p> 580 * 581 * @param session the capture session of interest 582 * 583 * @return <ul><li> 584 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 585 * if it is not NULL.</li> 586 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session is NULL.</li> 587 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 588 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 589 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 590 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 591 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 592 */ 593 camera_status_t ACameraCaptureSession_abortCaptures(ACameraCaptureSession* session) 594 __INTRODUCED_IN(24); 595 596 #endif /* __ANDROID_API__ >= 24 */ 597 598 #if __ANDROID_API__ >= 28 599 600 typedef struct ACaptureSessionOutput ACaptureSessionOutput; 601 602 /** 603 * Update shared ACaptureSessionOutput. 604 * 605 * <p>A shared ACaptureSessionOutput (see {@link ACaptureSessionSharedOutput_create}) that 606 * was modified via calls to {@link ACaptureSessionSharedOutput_add} or 607 * {@link ACaptureSessionSharedOutput_remove} must be updated by calling this method before its 608 * changes take effect. After the update call returns with {@link ACAMERA_OK}, any newly added 609 * native windows can be used as a target in subsequent capture requests.</p> 610 * 611 * <p>Native windows that get removed must not be part of any active repeating or single/burst 612 * request or have any pending results. Consider updating repeating requests via 613 * {@link ACaptureSessionOutput_setRepeatingRequest} and then wait for the last frame number 614 * when the sequence completes 615 * {@link ACameraCaptureSession_captureCallback#onCaptureSequenceCompleted}.</p> 616 * 617 * <p>Native windows that get added must not be part of any other registered ACaptureSessionOutput 618 * and must be compatible. Compatible windows must have matching format, rotation and 619 * consumer usage.</p> 620 * 621 * <p>A shared ACameraCaptureSession can support up to 4 additional native windows.</p> 622 * 623 * @param session the capture session of interest 624 * @param output the modified output configuration 625 * 626 * @return <ul><li> 627 * {@link ACAMERA_OK} if the method succeeds.</li> 628 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or output is NULL; or output 629 * contains invalid native windows; or if an attempt was made to add 630 * a native window to a different output configuration; or new native window is not 631 * compatible; or any removed native window still has pending requests;</li> 632 * <li>{@link ACAMERA_ERROR_INVALID_OPERATION} if output configuration is not shared (see 633 * {@link ACaptureSessionSharedOutput_create}; or the number of additional 634 * native windows goes beyond the supported limit.</li> 635 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 636 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 637 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 638 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal 639 * error</li> 640 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 641 */ 642 camera_status_t ACameraCaptureSession_updateSharedOutput(ACameraCaptureSession* session, 643 ACaptureSessionOutput* output) __INTRODUCED_IN(28); 644 #endif /* __ANDROID_API__ >= 28 */ 645 646 #if __ANDROID_API__ >= 29 647 /** 648 * The definition of final capture result callback with logical multi-camera support. 649 * 650 * This has the same functionality as final ACameraCaptureSession_captureCallback_result, with 651 * added ability to return physical camera result metadata within a logical multi-camera. 652 * 653 * For a logical multi-camera, this function will be called with the Id and result metadata 654 * of the underlying physical cameras, which the corresponding capture request contains targets for. 655 * If the capture request doesn't contain targets specific to any physical camera, or the current 656 * camera device isn't a logical multi-camera, physicalResultCount will be 0. 657 * 658 * @param context The optional application context provided by user in 659 * {@link ACameraCaptureSession_captureCallbacks}. 660 * @param session The camera capture session of interest. 661 * @param request The capture request of interest. Note that this pointer points to a copy of 662 * capture request sent by application, so the address is different to what 663 * application sent but the content will match. This request will be freed by 664 * framework immediately after this callback returns. 665 * @param result The capture result metadata reported by camera device. The memory is managed by 666 * camera framework. Do not access this pointer after this callback returns. 667 * @param physicalResultCount The number of physical camera result metadata 668 * @param physicalCameraIds The array of physical camera IDs on which the 669 * physical result metadata are reported. 670 * @param physicalResults The array of capture result metadata reported by the 671 * physical camera devices. 672 */ 673 typedef void (*ACameraCaptureSession_logicalCamera_captureCallback_result)( 674 void* context, ACameraCaptureSession* session, 675 ACaptureRequest* request, const ACameraMetadata* result, 676 size_t physicalResultCount, const char** physicalCameraIds, 677 const ACameraMetadata** physicalResults); 678 679 /// Struct to describe a logical camera capture failure 680 typedef struct ALogicalCameraCaptureFailure { 681 /** 682 * The {@link ACameraCaptureFailure} contains information about regular logical device capture 683 * failure. 684 */ 685 struct ACameraCaptureFailure captureFailure; 686 687 /** 688 * The physical camera device ID in case the capture failure comes from a capture request 689 * with configured physical camera streams for a logical camera. physicalCameraId will be set 690 * to NULL in case the capture request has no associated physical camera device. 691 * 692 */ 693 const char* physicalCameraId; 694 } ALogicalCameraCaptureFailure; 695 696 /** 697 * The definition of logical camera capture failure callback. 698 * 699 * @param context The optional application context provided by user in 700 * {@link ACameraCaptureSession_captureCallbacks}. 701 * @param session The camera capture session of interest. 702 * @param request The capture request of interest. Note that this pointer points to a copy of 703 * capture request sent by application, so the address is different to what 704 * application sent but the content will match. This request will be freed by 705 * framework immediately after this callback returns. 706 * @param failure The {@link ALogicalCameraCaptureFailure} desribes the capture failure. The memory 707 * is managed by camera framework. Do not access this pointer after this callback 708 * returns. 709 */ 710 typedef void (*ACameraCaptureSession_logicalCamera_captureCallback_failed)( 711 void* context, ACameraCaptureSession* session, 712 ACaptureRequest* request, ALogicalCameraCaptureFailure* failure); 713 714 /** 715 * This has the same functionality as ACameraCaptureSession_captureCallbacks, 716 * with the exception that an onLogicalCameraCaptureCompleted callback is 717 * used, instead of onCaptureCompleted, to support logical multi-camera. 718 */ 719 typedef struct ACameraCaptureSession_logicalCamera_captureCallbacks { 720 /** 721 * Same as ACameraCaptureSession_captureCallbacks 722 */ 723 void* context; 724 ACameraCaptureSession_captureCallback_start onCaptureStarted; 725 ACameraCaptureSession_captureCallback_result onCaptureProgressed; 726 727 /** 728 * This callback is called when an image capture has fully completed and all the 729 * result metadata is available. For a logical multi-camera, this callback 730 * also returns the result metadata for all physical cameras being 731 * explicitly requested on. 732 * 733 * <p>This callback will always fire after the last {@link onCaptureProgressed}; 734 * in other words, no more partial results will be delivered once the completed result 735 * is available.</p> 736 * 737 * <p>For performance-intensive use-cases where latency is a factor, consider 738 * using {@link onCaptureProgressed} instead.</p> 739 * 740 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 741 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 742 */ 743 ACameraCaptureSession_logicalCamera_captureCallback_result onLogicalCameraCaptureCompleted; 744 745 /** 746 * This callback is called instead of {@link onLogicalCameraCaptureCompleted} when the 747 * camera device failed to produce a capture result for the 748 * request. 749 * 750 * <p>Other requests are unaffected, and some or all image buffers from 751 * the capture may have been pushed to their respective output 752 * streams.</p> 753 * 754 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 755 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 756 * 757 * @see ALogicalCameraCaptureFailure 758 */ 759 ACameraCaptureSession_logicalCamera_captureCallback_failed onLogicalCameraCaptureFailed; 760 761 /** 762 * Same as ACameraCaptureSession_captureCallbacks 763 */ 764 ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; 765 ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; 766 ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; 767 } ACameraCaptureSession_logicalCamera_captureCallbacks; 768 769 /** 770 * This has the same functionality as ACameraCaptureSession_capture, with added 771 * support for logical multi-camera where the capture callbacks supports result metadata for 772 * physical cameras. 773 */ 774 camera_status_t ACameraCaptureSession_logicalCamera_capture( 775 ACameraCaptureSession* session, 776 /*optional*/ACameraCaptureSession_logicalCamera_captureCallbacks* callbacks, 777 int numRequests, ACaptureRequest** requests, 778 /*optional*/int* captureSequenceId) __INTRODUCED_IN(29); 779 780 /** 781 * This has the same functionality as ACameraCaptureSession_setRepeatingRequest, with added 782 * support for logical multi-camera where the capture callbacks supports result metadata for 783 * physical cameras. 784 */ 785 camera_status_t ACameraCaptureSession_logicalCamera_setRepeatingRequest( 786 ACameraCaptureSession* session, 787 /*optional*/ACameraCaptureSession_logicalCamera_captureCallbacks* callbacks, 788 int numRequests, ACaptureRequest** requests, 789 /*optional*/int* captureSequenceId) __INTRODUCED_IN(29); 790 791 #endif /* __ANDROID_API__ >= 29 */ 792 793 __END_DECLS 794 795 #endif /* _NDK_CAMERA_CAPTURE_SESSION_H */ 796 797 /** @} */ 798