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 /** 103 * The definition of camera capture session onWindowPrepared callback. 104 * 105 * <p>This callback is called when the buffer pre-allocation for an output window Surface is 106 * complete. </p> 107 * 108 * <p>Buffer pre-allocation for an output window is started by 109 * {@link ACameraCaptureSession_prepare} 110 * call. While allocation is underway, the output must not be used in a capture request. 111 * Once this callback is called, the output provided can be used as a target for a 112 * capture request. In case of an error during pre-allocation (such as running out of 113 * suitable-memory), this callback is still invoked after the error is encountered, though some 114 * buffers may not have been successfully pre-allocated.</p> 115 * 116 * Introduced in API 34. 117 * 118 * @param context The optional app-provided context pointer that was included in 119 * the {@link ACameraCaptureSession_setWindowPreparedCallback} method 120 * call. 121 * @param window The window that {@link ACameraCaptureSession_prepare} was called on. 122 * @param session The camera capture session on which {@link ACameraCaptureSession_prepare} was 123 * called on. 124 */ 125 typedef void (*ACameraCaptureSession_prepareCallback)( 126 void *context, 127 ANativeWindow *window, 128 ACameraCaptureSession *session); 129 130 /// Enum for describing error reason in {@link ACameraCaptureFailure} 131 enum { 132 /** 133 * The capture session has dropped this frame due to an 134 * {@link ACameraCaptureSession_abortCaptures} call. 135 */ 136 CAPTURE_FAILURE_REASON_FLUSHED = 0, 137 138 /** 139 * The capture session has dropped this frame due to an error in the framework. 140 */ 141 CAPTURE_FAILURE_REASON_ERROR 142 }; 143 144 /// Struct to describe a capture failure 145 typedef struct ACameraCaptureFailure { 146 /** 147 * The frame number associated with this failed capture. 148 * 149 * <p>Whenever a request has been processed, regardless of failed capture or success, 150 * it gets a unique frame number assigned to its future result/failed capture.</p> 151 * 152 * <p>This value monotonically increments, starting with 0, 153 * for every new result or failure; and the scope is the lifetime of the 154 * {@link ACameraDevice}.</p> 155 */ 156 int64_t frameNumber; 157 158 /** 159 * Determine why the request was dropped, whether due to an error or to a user 160 * action. 161 * 162 * @see CAPTURE_FAILURE_REASON_ERROR 163 * @see CAPTURE_FAILURE_REASON_FLUSHED 164 */ 165 int reason; 166 167 /** 168 * The sequence ID for this failed capture that was returned by the 169 * {@link ACameraCaptureSession_capture} or {@link ACameraCaptureSession_setRepeatingRequest}. 170 * 171 * <p>The sequence ID is a unique monotonically increasing value starting from 0, 172 * incremented every time a new group of requests is submitted to the ACameraDevice.</p> 173 */ 174 int sequenceId; 175 176 /** 177 * Determine if the image was captured from the camera. 178 * 179 * <p>If the image was not captured, no image buffers will be available. 180 * If the image was captured, then image buffers may be available.</p> 181 * 182 */ 183 bool wasImageCaptured; 184 } ACameraCaptureFailure; 185 186 /** 187 * The definition of camera capture start callback. 188 * 189 * @param context The optional application context provided by user in 190 * {@link ACameraCaptureSession_captureCallbacks}. 191 * @param session The camera capture session of interest. 192 * @param request The capture request that is starting. Note that this pointer points to a copy of 193 * capture request sent by application, so the address is different to what 194 * application sent but the content will match. This request will be freed by 195 * framework immediately after this callback returns. 196 * @param timestamp The timestamp when the capture is started. This timestamp will match 197 * {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 198 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted} callback. 199 */ 200 typedef void (*ACameraCaptureSession_captureCallback_start)( 201 void* context, ACameraCaptureSession* session, 202 const ACaptureRequest* request, int64_t timestamp); 203 204 /** 205 * The definition of camera capture progress/result callback. 206 * 207 * @param context The optional application context provided by user in 208 * {@link ACameraCaptureSession_captureCallbacks}. 209 * @param session The camera capture session of interest. 210 * @param request The capture request of interest. Note that this pointer points to a copy of 211 * capture request sent by application, so the address is different to what 212 * application sent but the content will match. This request will be freed by 213 * framework immediately after this callback returns. 214 * @param result The capture result metadata reported by camera device. The memory is managed by 215 * camera framework. Do not access this pointer after this callback returns. 216 */ 217 typedef void (*ACameraCaptureSession_captureCallback_result)( 218 void* context, ACameraCaptureSession* session, 219 ACaptureRequest* request, const ACameraMetadata* result); 220 221 /** 222 * The definition of camera capture failure 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 request The capture request of interest. Note that this pointer points to a copy of 228 * capture request sent by application, so the address is different to what 229 * application sent but the content will match. This request will be freed by 230 * framework immediately after this callback returns. 231 * @param failure The {@link ACameraCaptureFailure} describes the capture failure. The memory is 232 * managed by camera framework. Do not access this pointer after this callback 233 * returns. 234 */ 235 typedef void (*ACameraCaptureSession_captureCallback_failed)( 236 void* context, ACameraCaptureSession* session, 237 ACaptureRequest* request, ACameraCaptureFailure* failure); 238 239 /** 240 * The definition of camera sequence end callback. 241 * 242 * @param context The optional application context provided by user in 243 * {@link ACameraCaptureSession_captureCallbacks}. 244 * @param session The camera capture session of interest. 245 * @param sequenceId The capture sequence ID of the finished sequence. 246 * @param frameNumber The frame number of the last frame of this sequence. 247 */ 248 typedef void (*ACameraCaptureSession_captureCallback_sequenceEnd)( 249 void* context, ACameraCaptureSession* session, 250 int sequenceId, int64_t frameNumber); 251 252 /** 253 * The definition of camera sequence aborted callback. 254 * 255 * @param context The optional application context provided by user in 256 * {@link ACameraCaptureSession_captureCallbacks}. 257 * @param session The camera capture session of interest. 258 * @param sequenceId The capture sequence ID of the aborted sequence. 259 */ 260 typedef void (*ACameraCaptureSession_captureCallback_sequenceAbort)( 261 void* context, ACameraCaptureSession* session, 262 int sequenceId); 263 264 /** 265 * The definition of camera buffer lost callback. 266 * 267 * @param context The optional application context provided by user in 268 * {@link ACameraCaptureSession_captureCallbacks}. 269 * @param session The camera capture session of interest. 270 * @param request The capture request of interest. Note that this pointer points to a copy of 271 * capture request sent by application, so the address is different to what 272 * application sent but the content will match. This request will be freed by 273 * framework immediately after this callback returns. 274 * @param window The {@link ANativeWindow} that the lost buffer would have been sent to. 275 * @param frameNumber The frame number of the lost buffer. 276 */ 277 typedef void (*ACameraCaptureSession_captureCallback_bufferLost)( 278 void* context, ACameraCaptureSession* session, 279 ACaptureRequest* request, ANativeWindow* window, int64_t frameNumber); 280 281 /** 282 * ACaptureCaptureSession_captureCallbacks structure used in 283 * {@link ACameraCaptureSession_capture} and {@link ACameraCaptureSession_setRepeatingRequest}. 284 */ 285 typedef struct ACameraCaptureSession_captureCallbacks { 286 /// optional application context. 287 void* context; 288 289 /** 290 * This callback is called when the camera device has started capturing 291 * the output image for the request, at the beginning of image exposure. 292 * 293 * <p>This callback is invoked right as 294 * the capture of a frame begins, so it is the most appropriate time 295 * for playing a shutter sound, or triggering UI indicators of capture.</p> 296 * 297 * <p>The request that is being used for this capture is provided, along 298 * with the actual timestamp for the start of exposure. 299 * This timestamp matches the timestamps that will be 300 * included in {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 301 * {@link onCaptureCompleted} callback, 302 * and in the buffers sent to each output ANativeWindow. These buffer 303 * timestamps are accessible through, for example, 304 * {@link AImage_getTimestamp} or 305 * <a href="http://developer.android.com/reference/android/graphics/SurfaceTexture.html#getTimestamp()"> 306 * android.graphics.SurfaceTexture#getTimestamp()</a>.</p> 307 * 308 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 309 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 310 * 311 */ 312 ACameraCaptureSession_captureCallback_start onCaptureStarted; 313 314 /** 315 * This callback is called when an image capture makes partial forward progress; some 316 * (but not all) results from an image capture are available. 317 * 318 * <p>The result provided here will contain some subset of the fields of 319 * a full result. Multiple {@link onCaptureProgressed} calls may happen per 320 * capture; a given result field will only be present in one partial 321 * capture at most. The final {@link onCaptureCompleted} call will always 322 * contain all the fields (in particular, the union of all the fields of all 323 * the partial results composing the total result).</p> 324 * 325 * <p>For each request, some result data might be available earlier than others. The typical 326 * delay between each partial result (per request) is a single frame interval. 327 * For performance-oriented use-cases, applications should query the metadata they need 328 * to make forward progress from the partial results and avoid waiting for the completed 329 * result.</p> 330 * 331 * <p>For a particular request, {@link onCaptureProgressed} may happen before or after 332 * {@link onCaptureStarted}.</p> 333 * 334 * <p>Each request will generate at least `1` partial results, and at most 335 * {@link ACAMERA_REQUEST_PARTIAL_RESULT_COUNT} partial results.</p> 336 * 337 * <p>Depending on the request settings, the number of partial results per request 338 * will vary, although typically the partial count could be the same as long as the 339 * camera device subsystems enabled stay the same.</p> 340 * 341 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 342 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 343 */ 344 ACameraCaptureSession_captureCallback_result onCaptureProgressed; 345 346 /** 347 * This callback is called when an image capture has fully completed and all the 348 * result metadata is available. 349 * 350 * <p>This callback will always fire after the last {@link onCaptureProgressed}; 351 * in other words, no more partial results will be delivered once the completed result 352 * is available.</p> 353 * 354 * <p>For performance-intensive use-cases where latency is a factor, consider 355 * using {@link onCaptureProgressed} instead.</p> 356 * 357 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 358 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 359 */ 360 ACameraCaptureSession_captureCallback_result onCaptureCompleted; 361 362 /** 363 * This callback is called instead of {@link onCaptureCompleted} when the 364 * camera device failed to produce a capture result for the 365 * request. 366 * 367 * <p>Other requests are unaffected, and some or all image buffers from 368 * the capture may have been pushed to their respective output 369 * streams.</p> 370 * 371 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 372 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 373 * 374 * @see ACameraCaptureFailure 375 */ 376 ACameraCaptureSession_captureCallback_failed onCaptureFailed; 377 378 /** 379 * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, 380 * when a capture sequence finishes and all capture result 381 * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. 382 * 383 * <p>In total, there will be at least one result/failure returned by this listener 384 * before this callback is invoked. If the capture sequence is aborted before any 385 * requests have been processed, {@link onCaptureSequenceAborted} is invoked instead.</p> 386 */ 387 ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; 388 389 /** 390 * This callback is called independently of the others in {@link ACameraCaptureSession_captureCallbacks}, 391 * when a capture sequence aborts before any capture result 392 * or capture failure for it have been returned via this {@link ACameraCaptureSession_captureCallbacks}. 393 * 394 * <p>Due to the asynchronous nature of the camera device, not all submitted captures 395 * are immediately processed. It is possible to clear out the pending requests 396 * by a variety of operations such as {@link ACameraCaptureSession_stopRepeating} or 397 * {@link ACameraCaptureSession_abortCaptures}. When such an event happens, 398 * {@link onCaptureSequenceCompleted} will not be called.</p> 399 */ 400 ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; 401 402 /** 403 * This callback is called if a single buffer for a capture could not be sent to its 404 * destination ANativeWindow. 405 * 406 * <p>If the whole capture failed, then {@link onCaptureFailed} will be called instead. If 407 * some but not all buffers were captured but the result metadata will not be available, 408 * then onCaptureFailed will be invoked with {@link ACameraCaptureFailure#wasImageCaptured} 409 * returning true, along with one or more calls to {@link onCaptureBufferLost} for the 410 * failed outputs.</p> 411 * 412 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 413 * submitted, but the contents the ACaptureRequest will match what application submitted. 414 * The ANativeWindow pointer will always match what application submitted in 415 * {@link ACameraDevice_createCaptureSession}</p> 416 * 417 */ 418 ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; 419 } ACameraCaptureSession_captureCallbacks; 420 421 enum { 422 CAPTURE_SEQUENCE_ID_NONE = -1 423 }; 424 425 /** 426 * Close this capture session. 427 * 428 * <p>Closing a session frees up the target output Surfaces of the session for reuse with either 429 * a new session, or to other APIs that can draw to Surfaces.</p> 430 * 431 * <p>Note that creating a new capture session with {@link ACameraDevice_createCaptureSession} 432 * will close any existing capture session automatically, and call the older session listener's 433 * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback. Using 434 * {@link ACameraDevice_createCaptureSession} directly without closing is the recommended approach 435 * for quickly switching to a new session, since unchanged target outputs can be reused more 436 * efficiently.</p> 437 * 438 * <p>After a session is closed and before {@link ACameraCaptureSession_stateCallbacks#onClosed} 439 * is called, all methods invoked on the session will return {@link ACAMERA_ERROR_SESSION_CLOSED}, 440 * and any repeating requests are stopped (as if {@link ACameraCaptureSession_stopRepeating} was 441 * called). However, any in-progress capture requests submitted to the session will be completed as 442 * normal; once all captures have completed and the session has been torn down, 443 * {@link ACameraCaptureSession_stateCallbacks#onClosed} callback will be called and the session 444 * will be removed from memory.</p> 445 * 446 * <p>Closing a session is idempotent; closing more than once has no effect.</p> 447 * 448 * @param session the capture session of interest 449 */ 450 void ACameraCaptureSession_close(ACameraCaptureSession* session); 451 452 /** 453 * ACameraDevice is opaque type that provides access to a camera device. 454 * A pointer can be obtained using {@link ACameraManager_openCamera} method. 455 */ 456 typedef struct ACameraDevice ACameraDevice; 457 458 /** 459 * Get the ACameraDevice pointer associated with this capture session in the device argument 460 * if the method succeeds. 461 * 462 * @param session the capture session of interest 463 * @param device the {@link ACameraDevice} associated with session. Will be set to NULL 464 * if the session is closed or this method fails. 465 * @return <ul><li> 466 * {@link ACAMERA_OK} if the method call succeeds. The {@link ACameraDevice} 467 * will be stored in device argument</li> 468 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or device is NULL</li> 469 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 470 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 471 * 472 */ 473 camera_status_t ACameraCaptureSession_getDevice( 474 ACameraCaptureSession* session, /*out*/ACameraDevice** device) __INTRODUCED_IN(24); 475 476 /** 477 * Submit an array of requests to be captured in sequence as a burst in the minimum of time possible. 478 * 479 * <p>The burst will be captured in the minimum amount of time possible, and will not be 480 * interleaved with requests submitted by other capture or repeat calls.</p> 481 * 482 * <p>Each capture produces one {@link ACameraMetadata} as a capture result and image buffers for 483 * one or more target {@link ANativeWindow}s. The target ANativeWindows (set with 484 * {@link ACaptureRequest_addTarget}) must be a subset of the ANativeWindow provided when 485 * this capture session was created.</p> 486 * 487 * @param session the capture session of interest 488 * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated this capture 489 * sequence. No capture callback will be fired if this is set to NULL. 490 * @param numRequests number of requests in requests argument. Must be at least 1. 491 * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least 492 * numRequests. 493 * @param captureSequenceId the capture sequence ID associated with this capture method invocation 494 * will be stored here if this argument is not NULL and the method call succeeds. 495 * When this argument is set to NULL, the capture sequence ID will not be returned. 496 * 497 * @return <ul><li> 498 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 499 * if it is not NULL.</li> 500 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or requests is NULL, or 501 * if numRequests < 1</li> 502 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 503 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 504 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 505 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 506 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 507 */ 508 camera_status_t ACameraCaptureSession_capture( 509 ACameraCaptureSession* session, 510 /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, 511 int numRequests, ACaptureRequest** requests, 512 /*optional*/int* captureSequenceId) __INTRODUCED_IN(24); 513 514 /** 515 * Request endlessly repeating capture of a sequence of images by this capture session. 516 * 517 * <p>With this method, the camera device will continually capture images, 518 * cycling through the settings in the provided list of 519 * {@link ACaptureRequest}, at the maximum rate possible.</p> 520 * 521 * <p>If a request is submitted through {@link ACameraCaptureSession_capture}, 522 * the current repetition of the request list will be 523 * completed before the higher-priority request is handled. This guarantees 524 * that the application always receives a complete repeat burst captured in 525 * minimal time, instead of bursts interleaved with higher-priority 526 * captures, or incomplete captures.</p> 527 * 528 * <p>Repeating burst requests are a simple way for an application to 529 * maintain a preview or other continuous stream of frames where each 530 * request is different in a predictable way, without having to continually 531 * submit requests through {@link ACameraCaptureSession_capture}.</p> 532 * 533 * <p>To stop the repeating capture, call {@link ACameraCaptureSession_stopRepeating}. Any 534 * ongoing burst will still be completed, however. Calling 535 * {@link ACameraCaptureSession_abortCaptures} will also clear the request.</p> 536 * 537 * <p>Calling this method will replace a previously-set repeating requests 538 * set up by this method, although any in-progress burst will be completed before the new repeat 539 * burst will be used.</p> 540 * 541 * @param session the capture session of interest 542 * @param callbacks the {@link ACameraCaptureSession_captureCallbacks} to be associated with this 543 * capture sequence. No capture callback will be fired if callbacks is set to NULL. 544 * @param numRequests number of requests in requests array. Must be at least 1. 545 * @param requests an array of {@link ACaptureRequest} to be captured. Length must be at least 546 * numRequests. 547 * @param captureSequenceId the capture sequence ID associated with this capture method invocation 548 * will be stored here if this argument is not NULL and the method call succeeds. 549 * When this argument is set to NULL, the capture sequence ID will not be returned. 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 or requests is NULL, or 555 * if numRequests < 1</li> 556 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 557 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 558 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 559 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 560 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 561 */ 562 camera_status_t ACameraCaptureSession_setRepeatingRequest( 563 ACameraCaptureSession* session, 564 /*optional*/ACameraCaptureSession_captureCallbacks* callbacks, 565 int numRequests, ACaptureRequest** requests, 566 /*optional*/int* captureSequenceId) __INTRODUCED_IN(24); 567 568 /** 569 * Cancel any ongoing repeating capture set by {@link ACameraCaptureSession_setRepeatingRequest}. 570 * Has no effect on requests submitted through {@link ACameraCaptureSession_capture}. 571 * 572 * <p>Any currently in-flight captures will still complete, as will any burst that is 573 * mid-capture. To ensure that the device has finished processing all of its capture requests 574 * and is in ready state, wait for the {@link ACameraCaptureSession_stateCallbacks#onReady} callback 575 * after calling this method.</p> 576 * 577 * @param session the capture session of interest 578 * 579 * @return <ul><li> 580 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 581 * if it is not NULL.</li> 582 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session is NULL.</li> 583 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 584 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 585 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 586 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 587 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 588 */ 589 camera_status_t ACameraCaptureSession_stopRepeating(ACameraCaptureSession* session) 590 __INTRODUCED_IN(24); 591 592 /** 593 * Discard all captures currently pending and in-progress as fast as possible. 594 * 595 * <p>The camera device will discard all of its current work as fast as possible. Some in-flight 596 * captures may complete successfully and call 597 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted}, 598 * while others will trigger their {@link ACameraCaptureSession_captureCallbacks#onCaptureFailed} 599 * callbacks. If a repeating request list is set, it will be cleared.</p> 600 * 601 * <p>This method is the fastest way to switch the camera device to a new session with 602 * {@link ACameraDevice_createCaptureSession}, at the cost of discarding in-progress 603 * work. It must be called before the new session is created. Once all pending requests are 604 * either completed or thrown away, the {@link ACameraCaptureSession_stateCallbacks#onReady} 605 * callback will be called, if the session has not been closed. Otherwise, the 606 * {@link ACameraCaptureSession_stateCallbacks#onClosed} 607 * callback will be fired when a new session is created by the camera device and the previous 608 * session is being removed from memory.</p> 609 * 610 * <p>Cancelling will introduce at least a brief pause in the stream of data from the camera 611 * device, since once the camera device is emptied, the first new request has to make it through 612 * the entire camera pipeline before new output buffers are produced.</p> 613 * 614 * <p>This means that using ACameraCaptureSession_abortCaptures to simply remove pending requests is 615 * not recommended; it's best used for quickly switching output configurations, or for cancelling 616 * long in-progress requests (such as a multi-second capture).</p> 617 * 618 * @param session the capture session of interest 619 * 620 * @return <ul><li> 621 * {@link ACAMERA_OK} if the method succeeds. captureSequenceId will be filled 622 * if it is not NULL.</li> 623 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session is NULL.</li> 624 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 625 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 626 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 627 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 628 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 629 */ 630 camera_status_t ACameraCaptureSession_abortCaptures(ACameraCaptureSession* session) 631 __INTRODUCED_IN(24); 632 633 /** 634 * Opaque object for capture session output, use {@link ACaptureSessionOutput_create} or 635 * {@link ACaptureSessionSharedOutput_create} to create an instance. 636 */ 637 typedef struct ACaptureSessionOutput ACaptureSessionOutput; 638 639 /** 640 * Update shared ACaptureSessionOutput. 641 * 642 * <p>A shared ACaptureSessionOutput (see {@link ACaptureSessionSharedOutput_create}) that 643 * was modified via calls to {@link ACaptureSessionSharedOutput_add} or 644 * {@link ACaptureSessionSharedOutput_remove} must be updated by calling this method before its 645 * changes take effect. After the update call returns with {@link ACAMERA_OK}, any newly added 646 * native windows can be used as a target in subsequent capture requests.</p> 647 * 648 * <p>Native windows that get removed must not be part of any active repeating or single/burst 649 * request or have any pending results. Consider updating repeating requests via 650 * {@link ACameraCaptureSession_setRepeatingRequest} and then wait for the last frame number 651 * when the sequence completes 652 * {@link ACameraCaptureSession_captureCallbacks#onCaptureSequenceCompleted}.</p> 653 * 654 * <p>Native windows that get added must not be part of any other registered ACaptureSessionOutput 655 * and must be compatible. Compatible windows must have matching format, rotation and 656 * consumer usage.</p> 657 * 658 * <p>A shared ACameraCaptureSession can support up to 4 additional native windows.</p> 659 * 660 * @param session the capture session of interest 661 * @param output the modified output configuration 662 * 663 * @return <ul><li> 664 * {@link ACAMERA_OK} if the method succeeds.</li> 665 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or output is NULL; or output 666 * contains invalid native windows; or if an attempt was made to add 667 * a native window to a different output configuration; or new native window is not 668 * compatible; or any removed native window still has pending requests;</li> 669 * <li>{@link ACAMERA_ERROR_INVALID_OPERATION} if output configuration is not shared (see 670 * {@link ACaptureSessionSharedOutput_create}; or the number of additional 671 * native windows goes beyond the supported limit.</li> 672 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 673 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 674 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 675 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal 676 * error</li> 677 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 678 */ 679 camera_status_t ACameraCaptureSession_updateSharedOutput(ACameraCaptureSession* session, 680 ACaptureSessionOutput* output) __INTRODUCED_IN(28); 681 682 /** 683 * The definition of final capture result callback with logical multi-camera support. 684 * 685 * This has the same functionality as final ACameraCaptureSession_captureCallback_result, with 686 * added ability to return physical camera result metadata within a logical multi-camera. 687 * 688 * For a logical multi-camera, this function will be called with the Id and result metadata 689 * of the underlying physical cameras, which the corresponding capture request contains targets for. 690 * If the capture request doesn't contain targets specific to any physical camera, or the current 691 * camera device isn't a logical multi-camera, physicalResultCount will be 0. 692 * 693 * @param context The optional application context provided by user in 694 * {@link ACameraCaptureSession_captureCallbacks}. 695 * @param session The camera capture session of interest. 696 * @param request The capture request of interest. Note that this pointer points to a copy of 697 * capture request sent by application, so the address is different to what 698 * application sent but the content will match. This request will be freed by 699 * framework immediately after this callback returns. 700 * @param result The capture result metadata reported by camera device. The memory is managed by 701 * camera framework. Do not access this pointer after this callback returns. 702 * @param physicalResultCount The number of physical camera result metadata 703 * @param physicalCameraIds The array of physical camera IDs on which the 704 * physical result metadata are reported. 705 * @param physicalResults The array of capture result metadata reported by the 706 * physical camera devices. 707 */ 708 typedef void (*ACameraCaptureSession_logicalCamera_captureCallback_result)( 709 void* context, ACameraCaptureSession* session, 710 ACaptureRequest* request, const ACameraMetadata* result, 711 size_t physicalResultCount, const char** physicalCameraIds, 712 const ACameraMetadata** physicalResults); 713 714 /// Struct to describe a logical camera capture failure 715 typedef struct ALogicalCameraCaptureFailure { 716 /** 717 * The {@link ACameraCaptureFailure} contains information about regular logical device capture 718 * failure. 719 */ 720 struct ACameraCaptureFailure captureFailure; 721 722 /** 723 * The physical camera device ID in case the capture failure comes from a capture request 724 * with configured physical camera streams for a logical camera. physicalCameraId will be set 725 * to NULL in case the capture request has no associated physical camera device. 726 * 727 */ 728 const char* physicalCameraId; 729 } ALogicalCameraCaptureFailure; 730 731 /** 732 * The definition of logical camera capture failure callback. 733 * 734 * @param context The optional application context provided by user in 735 * {@link ACameraCaptureSession_captureCallbacks}. 736 * @param session The camera capture session of interest. 737 * @param request The capture request of interest. Note that this pointer points to a copy of 738 * capture request sent by application, so the address is different to what 739 * application sent but the content will match. This request will be freed by 740 * framework immediately after this callback returns. 741 * @param failure The {@link ALogicalCameraCaptureFailure} describes the capture failure. The memory 742 * is managed by camera framework. Do not access this pointer after this callback 743 * returns. 744 */ 745 typedef void (*ACameraCaptureSession_logicalCamera_captureCallback_failed)( 746 void* context, ACameraCaptureSession* session, 747 ACaptureRequest* request, ALogicalCameraCaptureFailure* failure); 748 749 /** 750 * This has the same functionality as ACameraCaptureSession_captureCallbacks, 751 * with the exception that an onLogicalCameraCaptureCompleted callback is 752 * used, instead of onCaptureCompleted, to support logical multi-camera. 753 */ 754 typedef struct ACameraCaptureSession_logicalCamera_captureCallbacks { 755 /** 756 * Same as ACameraCaptureSession_captureCallbacks 757 */ 758 void* context; 759 760 /** 761 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureStarted}. 762 */ 763 ACameraCaptureSession_captureCallback_start onCaptureStarted; 764 765 /** 766 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureProgressed}. 767 */ 768 ACameraCaptureSession_captureCallback_result onCaptureProgressed; 769 770 /** 771 * This callback is called when an image capture has fully completed and all the 772 * result metadata is available. For a logical multi-camera, this callback 773 * also returns the result metadata for all physical cameras being 774 * explicitly requested on. 775 * 776 * <p>This callback will always fire after the last {@link onCaptureProgressed}; 777 * in other words, no more partial results will be delivered once the completed result 778 * is available.</p> 779 * 780 * <p>For performance-intensive use-cases where latency is a factor, consider 781 * using {@link onCaptureProgressed} instead.</p> 782 * 783 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 784 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 785 */ 786 ACameraCaptureSession_logicalCamera_captureCallback_result onLogicalCameraCaptureCompleted; 787 788 /** 789 * This callback is called instead of {@link onLogicalCameraCaptureCompleted} when the 790 * camera device failed to produce a capture result for the 791 * request. 792 * 793 * <p>Other requests are unaffected, and some or all image buffers from 794 * the capture may have been pushed to their respective output 795 * streams.</p> 796 * 797 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 798 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 799 * 800 * @see ALogicalCameraCaptureFailure 801 */ 802 ACameraCaptureSession_logicalCamera_captureCallback_failed onLogicalCameraCaptureFailed; 803 804 /** 805 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureSequenceCompleted}. 806 */ 807 ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; 808 809 /** 810 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureSequenceAborted}. 811 */ 812 ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; 813 814 /** 815 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureBufferLost}. 816 */ 817 ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; 818 } ACameraCaptureSession_logicalCamera_captureCallbacks; 819 820 /** 821 * This has the same functionality as ACameraCaptureSession_capture, with added 822 * support for logical multi-camera where the capture callbacks supports result metadata for 823 * physical cameras. 824 */ 825 camera_status_t ACameraCaptureSession_logicalCamera_capture( 826 ACameraCaptureSession* session, 827 /*optional*/ACameraCaptureSession_logicalCamera_captureCallbacks* callbacks, 828 int numRequests, ACaptureRequest** requests, 829 /*optional*/int* captureSequenceId) __INTRODUCED_IN(29); 830 831 /** 832 * This has the same functionality as ACameraCaptureSession_setRepeatingRequest, with added 833 * support for logical multi-camera where the capture callbacks supports result metadata for 834 * physical cameras. 835 */ 836 camera_status_t ACameraCaptureSession_logicalCamera_setRepeatingRequest( 837 ACameraCaptureSession* session, 838 /*optional*/ACameraCaptureSession_logicalCamera_captureCallbacks* callbacks, 839 int numRequests, ACaptureRequest** requests, 840 /*optional*/int* captureSequenceId) __INTRODUCED_IN(29); 841 842 /** 843 * The definition of camera capture start callback. The same as 844 * {@link ACameraCaptureSession_captureCallbacks#onCaptureStarted}, except that 845 * it has the frame number of the capture as well. 846 * 847 * @param context The optional application context provided by user in 848 * {@link ACameraCaptureSession_captureCallbacks}. 849 * @param session The camera capture session of interest. 850 * @param request The capture request that is starting. Note that this pointer points to a copy of 851 * capture request sent by application, so the address is different to what 852 * application sent but the content will match. This request will be freed by 853 * framework immediately after this callback returns. 854 * @param timestamp The timestamp when the capture is started. This timestamp will match 855 * {@link ACAMERA_SENSOR_TIMESTAMP} of the {@link ACameraMetadata} in 856 * {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted} callback. 857 * @param frameNumber the frame number of the capture started 858 */ 859 typedef void (*ACameraCaptureSession_captureCallback_startV2)( 860 void* context, ACameraCaptureSession* session, 861 const ACaptureRequest* request, int64_t timestamp, int64_t frameNumber); 862 /** 863 * This has the same functionality as ACameraCaptureSession_captureCallbacks, 864 * with the exception that captureCallback_startV2 callback is 865 * used, instead of captureCallback_start, to support retrieving the frame number. 866 */ 867 typedef struct ACameraCaptureSession_captureCallbacksV2 { 868 /** 869 * Same as ACameraCaptureSession_captureCallbacks 870 */ 871 void* context; 872 873 /** 874 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureStarted}, 875 * except that it has the frame number of the capture added in the parameter 876 * list. 877 */ 878 ACameraCaptureSession_captureCallback_startV2 onCaptureStarted; 879 880 /** 881 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureProgressed}. 882 */ 883 ACameraCaptureSession_captureCallback_result onCaptureProgressed; 884 885 /** 886 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureCompleted}. 887 */ 888 ACameraCaptureSession_captureCallback_result onCaptureCompleted; 889 890 /** 891 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureFailed}. 892 */ 893 ACameraCaptureSession_captureCallback_failed onCaptureFailed; 894 895 /** 896 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureSequenceCompleted}. 897 */ 898 ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; 899 900 /** 901 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureSequenceAborted}. 902 */ 903 ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; 904 905 /** 906 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureBufferLost}. 907 */ 908 ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; 909 910 911 } ACameraCaptureSession_captureCallbacksV2; 912 913 /** 914 * This has the same functionality as ACameraCaptureSession_logicalCamera_captureCallbacks, 915 * with the exception that an captureCallback_startV2 callback is 916 * used, instead of captureCallback_start, to support retrieving frame number. 917 */ 918 typedef struct ACameraCaptureSession_logicalCamera_captureCallbacksV2 { 919 /** 920 * Same as ACameraCaptureSession_captureCallbacks 921 */ 922 void* context; 923 924 /** 925 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureStarted}, 926 * except that it has the frame number of the capture added in the parameter 927 * list. 928 */ 929 ACameraCaptureSession_captureCallback_startV2 onCaptureStarted; 930 931 932 /** 933 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureProgressed}. 934 */ 935 ACameraCaptureSession_captureCallback_result onCaptureProgressed; 936 937 /** 938 * Same as 939 * {@link ACameraCaptureSession_logicalCamera_captureCallbacks#onLogicalCaptureCompleted}. 940 */ 941 ACameraCaptureSession_logicalCamera_captureCallback_result onLogicalCameraCaptureCompleted; 942 943 /** 944 * This callback is called instead of {@link onLogicalCameraCaptureCompleted} when the 945 * camera device failed to produce a capture result for the 946 * request. 947 * 948 * <p>Other requests are unaffected, and some or all image buffers from 949 * the capture may have been pushed to their respective output 950 * streams.</p> 951 * 952 * <p>Note that the ACaptureRequest pointer in the callback will not match what application has 953 * submitted, but the contents the ACaptureRequest will match what application submitted.</p> 954 * 955 * @see ALogicalCameraCaptureFailure 956 */ 957 ACameraCaptureSession_logicalCamera_captureCallback_failed onLogicalCameraCaptureFailed; 958 959 /** 960 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureSequenceCompleted}. 961 */ 962 ACameraCaptureSession_captureCallback_sequenceEnd onCaptureSequenceCompleted; 963 964 /** 965 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureSequenceAborted}. 966 */ 967 ACameraCaptureSession_captureCallback_sequenceAbort onCaptureSequenceAborted; 968 969 /** 970 * Same as {@link ACameraCaptureSession_captureCallbacks#onCaptureBufferLost}. 971 */ 972 ACameraCaptureSession_captureCallback_bufferLost onCaptureBufferLost; 973 974 } ACameraCaptureSession_logicalCamera_captureCallbacksV2; 975 976 /** 977 * This has the same functionality as ACameraCaptureSession_capture, with added 978 * support for v2 of camera callbacks, where the onCaptureStarted callback 979 * adds frame number in its parameter list. 980 */ 981 camera_status_t ACameraCaptureSession_captureV2( 982 ACameraCaptureSession* session, 983 /*optional*/ACameraCaptureSession_captureCallbacksV2* callbacks, 984 int numRequests, ACaptureRequest** requests, 985 /*optional*/int* captureSequenceId) __INTRODUCED_IN(33); 986 987 /** 988 * This has the same functionality as ACameraCaptureSession_logical_setRepeatingRequest, with added 989 * support for v2 of logical multi-camera callbacks where the onCaptureStarted 990 * callback adds frame number in its parameter list. 991 */ 992 camera_status_t ACameraCaptureSession_setRepeatingRequestV2( 993 ACameraCaptureSession* session, 994 /*optional*/ACameraCaptureSession_captureCallbacksV2* callbacks, 995 int numRequests, ACaptureRequest** requests, 996 /*optional*/int* captureSequenceId) __INTRODUCED_IN(33); 997 998 /** 999 * This has the same functionality as ACameraCaptureSession_logical_capture, with added 1000 * support for v2 of logical multi-camera callbacks where the onCaptureStarted callback 1001 * adds frame number in its parameter list. 1002 */ 1003 camera_status_t ACameraCaptureSession_logicalCamera_captureV2( 1004 ACameraCaptureSession* session, 1005 /*optional*/ACameraCaptureSession_logicalCamera_captureCallbacksV2* callbacks, 1006 int numRequests, ACaptureRequest** requests, 1007 /*optional*/int* captureSequenceId) __INTRODUCED_IN(33); 1008 1009 /** 1010 * This has the same functionality as ACameraCaptureSession_logical_setRepeatingRequest, with added 1011 * support for v2 of logical multi-camera callbacks where the onCaptureStarted 1012 * callback adds frame number in its parameter list. 1013 */ 1014 camera_status_t ACameraCaptureSession_logicalCamera_setRepeatingRequestV2( 1015 ACameraCaptureSession* session, 1016 /*optional*/ACameraCaptureSession_logicalCamera_captureCallbacksV2* callbacks, 1017 int numRequests, ACaptureRequest** requests, 1018 /*optional*/int* captureSequenceId) __INTRODUCED_IN(33); 1019 1020 /** 1021 * Set the callback that is called when the output window for which the client has requested 1022 * pre-allocation of buffers through the {@link ACameraCaptureSession_prepareWindow} call has 1023 * completed the pre-allocation of buffers. 1024 * @param session the ACameraCaptureSession on which ACameraCaptureSession_prepareWindow was called. 1025 * @param context optional application provided context. This will be passed into the context 1026 * parameter of the {@link onWindowPrepared} callback. 1027 * @param callback the callback to be called when the output window's buffer pre-allocation is 1028 * complete. 1029 * @return <ul><li> {@link ACAMERA_OK} if the method succeeds</li> 1030 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session or callbacks is 1031 * NULL. Or if the session has not been configured with the window</li> 1032 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 1033 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 1034 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 1035 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} the camera service encounters fatal error</li> 1036 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 1037 */ 1038 camera_status_t ACameraCaptureSession_setWindowPreparedCallback( 1039 ACameraCaptureSession* session, 1040 void *context, 1041 ACameraCaptureSession_prepareCallback callback) __INTRODUCED_IN(34); 1042 1043 /** 1044 * 1045 * <p>Pre-allocate all buffers for an output window.</p> 1046 * 1047 * <p>Normally, the image buffers for a given output window are allocated on-demand, 1048 * to minimize startup latency and memory overhead.</p> 1049 * 1050 * <p>However, in some cases, it may be desirable for the buffers to be allocated before 1051 * any requests targeting the window are actually submitted to the device. Large buffers 1052 * may take some time to allocate, which can result in delays in submitting requests until 1053 * sufficient buffers are allocated to reach steady-state behavior. Such delays can cause 1054 * bursts to take longer than desired, or cause skips or stutters in preview output.</p> 1055 * 1056 * <p>The ACameraCaptureSession_prepare() call can be used to perform this pre-allocation. 1057 * It may only be called for a given output window before that window is used as a target for a 1058 * request. The number of buffers allocated is the sum of the count needed by the consumer providing 1059 * the output window, and the maximum number needed by the camera device to fill its pipeline. 1060 * Since this may be a larger number than what is actually required for steady-state operation, 1061 * using this call may result in higher memory consumption than the normal on-demand behavior 1062 * results in. This method will also delay the time to first output to a given Surface, in exchange 1063 * for smoother frame rate once the allocation is complete.</p> 1064 * 1065 * <p>For example, an application that creates an 1066 * {@link AImageReader} with a maxImages argument of 10, 1067 * but only uses 3 simultaneous {@link AImage}s at once, would normally only cause those 3 images 1068 * to be allocated (plus what is needed by the camera device for smooth operation). But using 1069 * ACameraCaptureSession_prepare() on the {@link AImageReader}'s window will result in all 10 1070 * {@link AImage}s being allocated. So applications using this method should take care to request 1071 * only the number of buffers actually necessary for their application.</p> 1072 * 1073 * <p>If the same output window is used in consecutive sessions (without closing the first 1074 * session explicitly), then its already-allocated buffers are carried over, and if it was 1075 * used as a target of a capture request in the first session, prepare cannot be called on it 1076 * in the second session. If it is, {@link ACAMERA_ERROR_INVALID_PARAMETER} will 1077 * be returned by the method</p> 1078 * 1079 * <p>Once allocation is complete, {@link ACameraCaptureSession_prepareCallback#onWindowPrepared} 1080 * will be invoked with the output provided to this method. Between the prepare call and the 1081 * {@link ACameraCaptureSession_prepareCallback#onWindowPrepared} call, 1082 * the output provided to prepare must not be used as a target of a capture request submitted 1083 * to this session.</p> 1084 * 1085 * <p>{@link android.hardware.camera2.CameraCharacteristics#INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} 1086 * devices cannot pre-allocate output buffers; for those devices, 1087 * {@link ACameraCaptureSession_prepareCallback#onWindowPrepared} will be immediately called, 1088 * and no pre-allocation is done.</p> 1089 * 1090 * @param session the {@link ACameraCaptureSession} that needs to prepare output buffers. 1091 * @param window the {@link ANativeWindow} for which the output buffers need to be prepared. 1092 * 1093 * @return <ul><li> 1094 * {@link ACAMERA_OK} if the method succeeds</li> 1095 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if session/ window is 1096 * NULL. Or if the session has not been configured with the window</li> 1097 * <li>{@link ACAMERA_ERROR_SESSION_CLOSED} if the capture session has been closed</li> 1098 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed</li> 1099 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error</li> 1100 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error</li> 1101 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons</li></ul> 1102 */ 1103 camera_status_t ACameraCaptureSession_prepareWindow( 1104 ACameraCaptureSession* session, 1105 ANativeWindow *window) __INTRODUCED_IN(34); 1106 __END_DECLS 1107 1108 #endif /* _NDK_CAMERA_CAPTURE_SESSION_H */ 1109 1110 /** @} */ 1111