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