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