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 37 #include <android/native_window.h> 38 #include "NdkCameraError.h" 39 #include "NdkCameraMetadata.h" 40 41 #ifndef _NDK_CAMERA_CAPTURE_SESSION_H 42 #define _NDK_CAMERA_CAPTURE_SESSION_H 43 44 __BEGIN_DECLS 45 46 #if __ANDROID_API__ >= 24 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 typedef struct ACameraCaptureSession_stateCallbacks { 65 /// optional application context. 66 void* context; 67 68 /** 69 * This callback is called when the session is closed and deleted from memory. 70 * 71 * <p>A session is closed when {@link ACameraCaptureSession_close} is called, a new session 72 * is created by the parent camera device, 73 * or when the parent camera device is closed (either by the user closing the device, 74 * or due to a camera device disconnection or fatal error).</p> 75 * 76 * <p>Once this callback is called, all access to this ACameraCaptureSession object will cause 77 * a crash.</p> 78 */ 79 ACameraCaptureSession_stateCallback onClosed; 80 81 /** 82 * This callback is called every time the session has no more capture requests to process. 83 * 84 * <p>This callback will be invoked any time the session finishes processing 85 * all of its active capture requests, and no repeating request or burst is set up.</p> 86 */ 87 ACameraCaptureSession_stateCallback onReady; 88 89 /** 90 * This callback is called when the session starts actively processing capture requests. 91 * 92 * <p>If the session runs out of capture requests to process and calls {@link onReady}, 93 * then this callback will be invoked again once new requests are submitted for capture.</p> 94 */ 95 ACameraCaptureSession_stateCallback onActive; 96 } ACameraCaptureSession_stateCallbacks; 97 98 /// Enum for describing error reason in {@link ACameraCaptureFailure} 99 enum { 100 /** 101 * The capture session has dropped this frame due to an 102 * {@link ACameraCaptureSession_abortCaptures} call. 103 */ 104 CAPTURE_FAILURE_REASON_FLUSHED = 0, 105 106 /** 107 * The capture session has dropped this frame due to an error in the framework. 108 */ 109 CAPTURE_FAILURE_REASON_ERROR 110 }; 111 112 /// Struct to describe a capture failure 113 typedef struct ACameraCaptureFailure { 114 /** 115 * The frame number associated with this failed capture. 116 * 117 * <p>Whenever a request has been processed, regardless of failed capture or success, 118 * it gets a unique frame number assigned to its future result/failed capture.</p> 119 * 120 * <p>This value monotonically increments, starting with 0, 121 * for every new result or failure; and the scope is the lifetime of the 122 * {@link ACameraDevice}.</p> 123 */ 124 int64_t frameNumber; 125 126 /** 127 * Determine why the request was dropped, whether due to an error or to a user 128 * action. 129 * 130 * @see CAPTURE_FAILURE_REASON_ERROR 131 * @see CAPTURE_FAILURE_REASON_FLUSHED 132 */ 133 int reason; 134 135 /** 136 * The sequence ID for this failed capture that was returned by the 137 * {@link ACameraCaptureSession_capture} or {@link ACameraCaptureSession_setRepeatingRequest}. 138 * 139 * <p>The sequence ID is a unique monotonically increasing value starting from 0, 140 * incremented every time a new group of requests is submitted to the ACameraDevice.</p> 141 */ 142 int sequenceId; 143 144 /** 145 * Determine if the image was captured from the camera. 146 * 147 * <p>If the image was not captured, no image buffers will be available. 148 * If the image was captured, then image buffers may be available.</p> 149 * 150 */ 151 bool wasImageCaptured; 152 } ACameraCaptureFailure; 153 154 /** 155 * The definition of camera capture start callback. 156 * 157 * @param context The optional application context provided by user in 158 * {@link ACameraCaptureSession_captureCallbacks}. 159 * @param session The camera capture session of interest. 160 * @param request The capture request that is starting. Note that this pointer points to a copy of 161 * capture request sent by application, so the address is different to what 162 * application sent but the content will match. This request will be freed by 163 * framework immediately after this callback returns. 164 * @param timestamp The timestamp when the capture is started. This timestmap will match 165 * {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 166 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted} callback. 167 */ 168 typedef void (*ACameraCaptureSession_captureCallback_start)( 169 void* context, ACameraCaptureSession* session, 170 const ACaptureRequest* request, int64_t timestamp); 171 172 /** 173 * The definition of camera capture progress/result callback. 174 * 175 * @param context The optional application context provided by user in 176 * {@link ACameraCaptureSession_captureCallbacks}. 177 * @param session The camera capture session of interest. 178 * @param request The capture request of interest. Note that this pointer points to a copy of 179 * capture request sent by application, so the address is different to what 180 * application sent but the content will match. This request will be freed by 181 * framework immediately after this callback returns. 182 * @param result The capture result metadata reported by camera device. The memory is managed by 183 * camera framework. Do not access this pointer after this callback returns. 184 */ 185 typedef void (*ACameraCaptureSession_captureCallback_result)( 186 void* context, ACameraCaptureSession* session, 187 ACaptureRequest* request, const ACameraMetadata* result); 188 189 /** 190 * The definition of camera capture failure callback. 191 * 192 * @param context The optional application context provided by user in 193 * {@link ACameraCaptureSession_captureCallbacks}. 194 * @param session The camera capture session of interest. 195 * @param request The capture request of interest. Note that this pointer points to a copy of 196 * capture request sent by application, so the address is different to what 197 * application sent but the content will match. This request will be freed by 198 * framework immediately after this callback returns. 199 * @param failure The {@link ACameraCaptureFailure} desribes the capture failure. The memory is 200 * managed by camera framework. Do not access this pointer after this callback 201 * returns. 202 */ 203 typedef void (*ACameraCaptureSession_captureCallback_failed)( 204 void* context, ACameraCaptureSession* session, 205 ACaptureRequest* request, ACameraCaptureFailure* failure); 206 207 /** 208 * The definition of camera sequence end callback. 209 * 210 * @param context The optional application context provided by user in 211 * {@link ACameraCaptureSession_captureCallbacks}. 212 * @param session The camera capture session of interest. 213 * @param sequenceId The capture sequence ID of the finished sequence. 214 * @param frameNumber The frame number of the last frame of this sequence. 215 */ 216 typedef void (*ACameraCaptureSession_captureCallback_sequenceEnd)( 217 void* context, ACameraCaptureSession* session, 218 int sequenceId, int64_t frameNumber); 219 220 /** 221 * The definition of camera sequence aborted callback. 222 * 223 * @param context The optional application context provided by user in 224 * {@link ACameraCaptureSession_captureCallbacks}. 225 * @param session The camera capture session of interest. 226 * @param sequenceId The capture sequence ID of the aborted sequence. 227 */ 228 typedef void (*ACameraCaptureSession_captureCallback_sequenceAbort)( 229 void* context, ACameraCaptureSession* session, 230 int sequenceId); 231 232 /** 233 * The definition of camera buffer lost callback. 234 * 235 * @param context The optional application context provided by user in 236 * {@link ACameraCaptureSession_captureCallbacks}. 237 * @param session The camera capture session of interest. 238 * @param request The capture request of interest. Note that this pointer points to a copy of 239 * capture request sent by application, so the address is different to what 240 * application sent but the content will match. This request will be freed by 241 * framework immediately after this callback returns. 242 * @param window The {@link ANativeWindow} that the lost buffer would have been sent to. 243 * @param frameNumber The frame number of the lost buffer. 244 */ 245 typedef void (*ACameraCaptureSession_captureCallback_bufferLost)( 246 void* context, ACameraCaptureSession* session, 247 ACaptureRequest* request, ANativeWindow* window, int64_t frameNumber); 248 249 typedef struct ACameraCaptureSession_captureCallbacks { 250 /// optional application context. 251 void* context; 252 253 /** 254 * This callback is called when the camera device has started capturing 255 * the output image for the request, at the beginning of image exposure. 256 * 257 * <p>This callback is invoked right as 258 * the capture of a frame begins, so it is the most appropriate time 259 * for playing a shutter sound, or triggering UI indicators of capture.</p> 260 * 261 * <p>The request that is being used for this capture is provided, along 262 * with the actual timestamp for the start of exposure. 263 * This timestamp matches the timestamps that will be 264 * included in {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 265 * {@link onCaptureCompleted} callback, 266 * and in the buffers sent to each output ANativeWindow. These buffer 267 * timestamps are accessible through, for example, 268 * {@link AImage_getTimestamp} or 269 * <a href="http://developer.android.com/reference/android/graphics/SurfaceTexture.html#getTimestamp()"> 270 * android.graphics.SurfaceTexture#getTimestamp()</a>.</p> 271 * 272 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 273 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 274 * 275 */ 276 ACameraCaptureSession_captureCallback_start onCaptureStarted; 277 278 /** 279 * This callback is called when an image capture makes partial forward progress; some 280 * (but not all) results from an image capture are available. 281 * 282 * <p>The result provided here will contain some subset of the fields of 283 * a full result. Multiple {@link onCaptureProgressed} calls may happen per 284 * capture; a given result field will only be present in one partial 285 * capture at most. The final {@link onCaptureCompleted} call will always 286 * contain all the fields (in particular, the union of all the fields of all 287 * the partial results composing the total result).</p> 288 * 289 * <p>For each request, some result data might be available earlier than others. The typical 290 * delay between each partial result (per request) is a single frame interval. 291 * For performance-oriented use-cases, applications should query the metadata they need 292 * to make forward progress from the partial results and avoid waiting for the completed 293 * result.</p> 294 * 295 * <p>For a particular request, {@link onCaptureProgressed} may happen before or after 296 * {@link onCaptureStarted}.</p> 297 * 298 * <p>Each request will generate at least `1` partial results, and at most 299 * {@link ACAMERA_REQUEST_PARTIAL_RESULT_COUNT} partial results.</p> 300 * 301 * <p>Depending on the request settings, the number of partial results per request 302 * will vary, although typically the partial count could be the same as long as the 303 * camera device subsystems enabled stay the same.</p> 304 * 305 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 306 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 307 */ 308 ACameraCaptureSession_captureCallback_result onCaptureProgressed; 309 310 /** 311 * This callback is called when an image capture has fully completed and all the 312 * result metadata is available. 313 * 314 * <p>This callback will always fire after the last {@link onCaptureProgressed}; 315 * in other words, no more partial results will be delivered once the completed result 316 * is available.</p> 317 * 318 * <p>For performance-intensive use-cases where latency is a factor, consider 319 * using {@link onCaptureProgressed} instead.</p> 320 * 321 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 322 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 323 */ 324 ACameraCaptureSession_captureCallback_result onCaptureCompleted; 325 326 /** 327 * This callback is called instead of {@link onCaptureCompleted} when the 328 * camera device failed to produce a capture result for the 329 * request. 330 * 331 * <p>Other requests are unaffected, and some or all image buffers from 332 * the capture may have been pushed to their respective output 333 * streams.</p> 334 * 335 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 336 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 337 * 338 * @see ACameraCaptureFailure 339 */ 340 ACameraCaptureSession_captureCallback_failed onCaptureFailed; 341 342 /** 343 * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, 344 * when a capture sequence finishes and all capture result 345 * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. 346 * 347 * <p>In total, there will be at least one result/failure returned by this listener 348 * before this callback is invoked. If the capture sequence is aborted before any 349 * requests have been processed, {@link onCaptureSequenceAborted} is invoked instead.</p> 350 */ 351 ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; 352 353 /** 354 * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, 355 * when a capture sequence aborts before any capture result 356 * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. 357 * 358 * <p>Due to the asynchronous nature of the camera device, not all submitted captures 359 * are immediately processed. It is possible to clear out the pending requests 360 * by a variety of operations such as {@link ACameraCaptureSession_stopRepeating} or 361 * {@link ACameraCaptureSession_abortCaptures}. When such an event happens, 362 * {@link onCaptureSequenceCompleted} will not be called.</p> 363 */ 364 ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; 365 366 /** 367 * This callback is called if a single buffer for a capture could not be sent to its 368 * destination ANativeWindow. 369 * 370 * <p>If the whole capture failed, then {@link onCaptureFailed} will be called instead. If 371 * some but not all buffers were captured but the result metadata will not be available, 372 * then onCaptureFailed will be invoked with {@link ACameraCaptureFailure#wasImageCaptured} 373 * returning true, along with one or more calls to {@link onCaptureBufferLost} for the 374 * failed outputs.</p> 375 * 376 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 377 * submitted, but the contents the ACaptureRequest will match what application submitted. 378 * The ANativeWindow pointer will always match what application submitted in 379 * {@link ACameraDevice_createCaptureSession}</p> 380 * 381 */ 382 ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; 383 } ACameraCaptureSession_captureCallbacks; 384 385 enum { 386 CAPTURE_SEQUENCE_ID_NONE = -1 387 }; 388 389 /** 390 * Close this capture session. 391 * 392 * <p>Closing a session frees up the target output Surfaces of the session for reuse with either 393 * a new session, or to other APIs that can draw to Surfaces.</p> 394 * 395 * <p>Note that creating a new capture session with {@link ACameraDevice_createCaptureSession} 396 * will close any existing capture session automatically, and call the older session listener's 397 * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback. Using 398 * {@link ACameraDevice_createCaptureSession} directly without closing is the recommended approach 399 * for quickly switching to a new session, since unchanged target outputs can be reused more 400 * efficiently.</p> 401 * 402 * <p>After a session is closed and before {@link ACameraCaptureSession_stateCallbacks#onClosed} 403 * is called, all methods invoked on the session will return {@link ACAMERA_ERROR_SESSION_CLOSED}, 404 * and any repeating requests are stopped (as if {@link ACameraCaptureSession_stopRepeating} was 405 * called). However, any in-progress capture requests submitted to the session will be completed as 406 * normal; once all captures have completed and the session has been torn down, 407 * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback will be called and the seesion 408 * will be removed from memory.</p> 409 * 410 * <p>Closing a session is idempotent; closing more than once has no effect.</p> 411 * 412 * @param session the capture session of interest 413 */ 414 void ACameraCaptureSession_close(ACameraCaptureSession* session); 415 416 struct ACameraDevice; 417 typedef struct ACameraDevice ACameraDevice; 418 419 /** 420 * Get the ACameraDevice pointer associated with this capture session in the device argument 421 * if the method succeeds. 422 * 423 * @param session the capture session of interest 424 * @param device the {@link ACameraDevice} associated with session. Will be set to NULL 425 * if the session is closed or this method fails. 426 * @return <ul><li> 427 * {@link ACAMERA_OK} if the method call succeeds. The {@link ACameraDevice} 428 * will be stored in device argument</li> 429 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or device is NULL</li> 430 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 431 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 432 * 433 */ 434 camera_status_t ACameraCaptureSession_getDevice( 435 ACameraCaptureSession* session, /*out*/ACameraDevice** device); 436 437 /** 438 * Submit an array of requests to be captured in sequence as a burst in the minimum of time possible. 439 * 440 * <p>The burst will be captured in the minimum amount of time possible, and will not be 441 * interleaved with requests submitted by other capture or repeat calls.</p> 442 * 443 * <p>Each capture produces one {@link ACameraMetadata} as a capture result and image buffers for 444 * one or more target {@link ANativeWindow}s. The target ANativeWindows (set with 445 * {@link ACaptureRequest_addTarget}) must be a subset of the ANativeWindow provided when 446 * this capture session was created.</p> 447 * 448 * @param session the capture session of interest 449 * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated this capture 450 * sequence. No capture callback will be fired if this is set to NULL. 451 * @param numRequests number of requests in requests argument. Must be at least 1. 452 * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least 453 * numRequests. 454 * @param captureSequenceId the capture sequence ID associated with this capture method invocation 455 * will be stored here if this argument is not NULL and the method call succeeds. 456 * When this argument is set to NULL, the capture sequence ID will not be returned. 457 * 458 * @return <ul><li> 459 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 460 * if it is not NULL.</li> 461 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or requests is NULL, or 462 * if numRequests < 1</li> 463 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 464 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 465 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 466 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 467 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 468 */ 469 camera_status_t ACameraCaptureSession_capture( 470 ACameraCaptureSession* session, 471 /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, 472 int numRequests, ACaptureRequest** requests, 473 /*optional*/int* captureSequenceId); 474 475 /** 476 * Request endlessly repeating capture of a sequence of images by this capture session. 477 * 478 * <p>With this method, the camera device will continually capture images, 479 * cycling through the settings in the provided list of 480 * {@link ACaptureRequest}, at the maximum rate possible.</p> 481 * 482 * <p>If a request is submitted through {@link ACameraCaptureSession_capture}, 483 * the current repetition of the request list will be 484 * completed before the higher-priority request is handled. This guarantees 485 * that the application always receives a complete repeat burst captured in 486 * minimal time, instead of bursts interleaved with higher-priority 487 * captures, or incomplete captures.</p> 488 * 489 * <p>Repeating burst requests are a simple way for an application to 490 * maintain a preview or other continuous stream of frames where each 491 * request is different in a predicatable way, without having to continually 492 * submit requests through {@link ACameraCaptureSession_capture}.</p> 493 * 494 * <p>To stop the repeating capture, call {@link ACameraCaptureSession_stopRepeating}. Any 495 * ongoing burst will still be completed, however. Calling 496 * {@link ACameraCaptureSession_abortCaptures} will also clear the request.</p> 497 * 498 * <p>Calling this method will replace a previously-set repeating requests 499 * set up by this method, although any in-progress burst will be completed before the new repeat 500 * burst will be used.</p> 501 * 502 * @param session the capture session of interest 503 * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated with this 504 * capture sequence. No capture callback will be fired if callbacks is set to NULL. 505 * @param numRequests number of requests in requests array. Must be at least 1. 506 * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least 507 * numRequests. 508 * @param captureSequenceId the capture sequence ID associated with this capture method invocation 509 * will be stored here if this argument is not NULL and the method call succeeds. 510 * When this argument is set to NULL, the capture sequence ID will not be returned. 511 * 512 * @return <ul><li> 513 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 514 * if it is not NULL.</li> 515 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or requests is NULL, or 516 * if numRequests < 1</li> 517 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 518 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 519 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 520 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 521 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 522 */ 523 camera_status_t ACameraCaptureSession_setRepeatingRequest( 524 ACameraCaptureSession* session, 525 /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, 526 int numRequests, ACaptureRequest** requests, 527 /*optional*/int* captureSequenceId); 528 529 /** 530 * Cancel any ongoing repeating capture set by {@link ACameraCaptureSession_setRepeatingRequest}. 531 * Has no effect on requests submitted through {@link ACameraCaptureSession_capture}. 532 * 533 * <p>Any currently in-flight captures will still complete, as will any burst that is 534 * mid-capture. To ensure that the device has finished processing all of its capture requests 535 * and is in ready state, wait for the {@link ACameraCaptureSession_stateCallbacks#onReady} callback 536 * after calling this method.</p> 537 * 538 * @param session the capture session of interest 539 * 540 * @return <ul><li> 541 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 542 * if it is not NULL.</li> 543 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session is NULL.</li> 544 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 545 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 546 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 547 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 548 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 549 */ 550 camera_status_t ACameraCaptureSession_stopRepeating(ACameraCaptureSession* session); 551 552 /** 553 * Discard all captures currently pending and in-progress as fast as possible. 554 * 555 * <p>The camera device will discard all of its current work as fast as possible. Some in-flight 556 * captures may complete successfully and call 557 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted}, 558 * while others will trigger their {@link ACameraCaptureSession_captureCallbacks#onCaptureFailed} 559 * callbacks. If a repeating request list is set, it will be cleared.</p> 560 * 561 * <p>This method is the fastest way to switch the camera device to a new session with 562 * {@link ACameraDevice_createCaptureSession}, at the cost of discarding in-progress 563 * work. It must be called before the new session is created. Once all pending requests are 564 * either completed or thrown away, the {@link ACameraCaptureSession_stateCallbacks#onReady} 565 * callback will be called, if the session has not been closed. Otherwise, the 566 * {@link ACameraCaptureSession_stateCallbacks#onClosed} 567 * callback will be fired when a new session is created by the camera device and the previous 568 * session is being removed from memory.</p> 569 * 570 * <p>Cancelling will introduce at least a brief pause in the stream of data from the camera 571 * device, since once the camera device is emptied, the first new request has to make it through 572 * the entire camera pipeline before new output buffers are produced.</p> 573 * 574 * <p>This means that using ACameraCaptureSession_abortCaptures to simply remove pending requests is 575 * not recommended; it's best used for quickly switching output configurations, or for cancelling 576 * long in-progress requests (such as a multi-second capture).</p> 577 * 578 * @param session the capture session of interest 579 * 580 * @return <ul><li> 581 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 582 * if it is not NULL.</li> 583 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session is NULL.</li> 584 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 585 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 586 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 587 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 588 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 589 */ 590 camera_status_t ACameraCaptureSession_abortCaptures(ACameraCaptureSession* session); 591 592 #endif /* __ANDROID_API__ >= 24 */ 593 594 __END_DECLS 595 596 #endif /* _NDK_CAMERA_CAPTURE_SESSION_H */ 597 598 /** @} */ 599