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