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 NdkCameraDevice.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 36 #include <android/native_window.h> 37 #include "NdkCameraError.h" 38 #include "NdkCaptureRequest.h" 39 #include "NdkCameraCaptureSession.h" 40 41 #ifndef _NDK_CAMERA_DEVICE_H 42 #define _NDK_CAMERA_DEVICE_H 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * ACameraDevice is opaque type that provides access to a camera device. 50 * 51 * A pointer can be obtained using {@link ACameraManager_openCamera} method. 52 */ 53 typedef struct ACameraDevice ACameraDevice; 54 55 /// Enum for ACameraDevice_ErrorStateCallback error code 56 enum { 57 /** 58 * The camera device is in use already. 59 */ 60 ERROR_CAMERA_IN_USE = 1, 61 62 /** 63 * The system-wide limit for number of open cameras or camera resources has 64 * been reached, and more camera devices cannot be opened until previous 65 * instances are closed. 66 */ 67 ERROR_MAX_CAMERAS_IN_USE = 2, 68 69 /** 70 * The camera is disabled due to a device policy, and cannot be opened. 71 */ 72 ERROR_CAMERA_DISABLED = 3, 73 74 /** 75 * The camera device has encountered a fatal error. 76 * <p>The camera device needs to be re-opened to be used again.</p> 77 */ 78 ERROR_CAMERA_DEVICE = 4, 79 80 /** 81 * The camera service has encountered a fatal error. 82 * <p>The Android device may need to be shut down and restarted to restore 83 * camera function, or there may be a persistent hardware problem. 84 * An attempt at recovery may be possible by closing the 85 * CameraDevice and the CameraManager, and trying to acquire all resources 86 * again from scratch.</p> 87 */ 88 ERROR_CAMERA_SERVICE = 5 89 }; 90 91 /** 92 * Camera device state callbacks to be used in {@link ACameraDevice_stateCallbacks}. 93 * 94 * @param context The optional context in {@link ACameraDevice_stateCallbacks} will be 95 * passed to this callback. 96 * @param device The {@link ACameraDevice} that is being disconnected. 97 */ 98 typedef void (*ACameraDevice_StateCallback)(void* context, ACameraDevice* device); 99 100 /** 101 * Camera device error state callbacks to be used in {@link ACameraDevice_stateCallbacks}. 102 * 103 * @param context The optional context in {@link ACameraDevice_stateCallbacks} will be 104 * passed to this callback. 105 * @param device The {@link ACameraDevice} that is being disconnected. 106 * @param error The error code describes the cause of this error callback. See the folowing 107 * links for more detail. 108 * 109 * @see ERROR_CAMERA_IN_USE 110 * @see ERROR_MAX_CAMERAS_IN_USE 111 * @see ERROR_CAMERA_DISABLED 112 * @see ERROR_CAMERA_DEVICE 113 * @see ERROR_CAMERA_SERVICE 114 */ 115 typedef void (*ACameraDevice_ErrorStateCallback)(void* context, ACameraDevice* device, int error); 116 117 typedef struct ACameraDevice_StateCallbacks { 118 /// optional application context. 119 void* context; 120 121 /** 122 * The function is called when a camera device is no longer available for use. 123 * 124 * <p>Any attempt to call API methods on this ACameraDevice will return 125 * {@link ACAMERA_ERROR_CAMERA_DISCONNECTED}. The disconnection could be due to a 126 * change in security policy or permissions; the physical disconnection 127 * of a removable camera device; or the camera being needed for a 128 * higher-priority camera API client.</p> 129 * 130 * <p>Application should clean up the camera with {@link ACameraDevice_close} after 131 * this happens, as it is not recoverable until the camera can be opened 132 * again.</p> 133 * 134 */ 135 ACameraDevice_StateCallback onDisconnected; 136 137 /** 138 * The function called when a camera device has encountered a serious error. 139 * 140 * <p>This indicates a failure of the camera device or camera service in some way. 141 * Any attempt to call API methods on this ACameraDevice in the future will return 142 * {@link ACAMERA_ERROR_CAMERA_DISCONNECTED}.</p> 143 * 144 * <p>There may still be capture completion or camera stream callbacks that will be called 145 * after this error is received.</p> 146 * 147 * <p>Application should clean up the camera with {@link ACameraDevice_close} after this 148 * happens. Further attempts at recovery are error-code specific.</p> 149 * 150 */ 151 ACameraDevice_ErrorStateCallback onError; 152 } ACameraDevice_stateCallbacks; 153 154 /** 155 * Close the connection and free this ACameraDevice synchronously. Access to the ACameraDevice 156 * after calling this method will cause a crash. 157 * 158 * <p>After this call, all calls to the active ACameraCaptureSession associated to this 159 * ACameraDevice will return {@link ACAMERA_ERROR_SESSION_CLOSED} except for calls to 160 * {@link ACameraCaptureSession_close}.</p> 161 * 162 * <p>This method will stop all repeating captures sent via 163 * {@link ACameraCaptureSession_setRepeatingRequest} and block until all capture requests sent via 164 * {@link ACameraCaptureSession_capture} is complete. Once the method returns, the camera device 165 * will be removed from memory and access to the closed camera device pointer will cause a crash.</p> 166 * 167 * @param device the camera device to be closed 168 * 169 * @return <ul> 170 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 171 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if device is NULL.</li></ul> 172 */ 173 camera_status_t ACameraDevice_close(ACameraDevice* device); 174 175 /** 176 * Return the camera id associated with this camera device. 177 * 178 * @param device the camera device to be closed 179 * 180 * @return camera ID string. The returned string is managed by framework and should not be 181 * delete/free by the application. Also the returned string must not be used after the device 182 * has been closed. 183 */ 184 const char* ACameraDevice_getId(const ACameraDevice* device); 185 186 typedef enum { 187 /** 188 * Create a request suitable for a camera preview window. Specifically, this 189 * means that high frame rate is given priority over the highest-quality 190 * post-processing. These requests would normally be used with the 191 * {@link ACameraCaptureSession_setRepeatingRequest} method. 192 * This template is guaranteed to be supported on all camera devices. 193 * 194 * @see ACameraDevice_createCaptureRequest 195 */ 196 TEMPLATE_PREVIEW = 1, 197 198 /** 199 * Create a request suitable for still image capture. Specifically, this 200 * means prioritizing image quality over frame rate. These requests would 201 * commonly be used with the {@link ACameraCaptureSession_capture} method. 202 * This template is guaranteed to be supported on all camera devices. 203 * 204 * @see ACameraDevice_createCaptureRequest 205 */ 206 TEMPLATE_STILL_CAPTURE = 2, 207 208 /** 209 * Create a request suitable for video recording. Specifically, this means 210 * that a stable frame rate is used, and post-processing is set for 211 * recording quality. These requests would commonly be used with the 212 * {@link ACameraCaptureSession_setRepeatingRequest} method. 213 * This template is guaranteed to be supported on all camera devices. 214 * 215 * @see ACameraDevice_createCaptureRequest 216 */ 217 TEMPLATE_RECORD = 3, 218 219 /** 220 * Create a request suitable for still image capture while recording 221 * video. Specifically, this means maximizing image quality without 222 * disrupting the ongoing recording. These requests would commonly be used 223 * with the {@link ACameraCaptureSession_capture} method while a request based on 224 * {@link TEMPLATE_RECORD} is is in use with {@link ACameraCaptureSession_setRepeatingRequest}. 225 * This template is guaranteed to be supported on all camera devices. 226 * 227 * @see ACameraDevice_createCaptureRequest 228 */ 229 TEMPLATE_VIDEO_SNAPSHOT = 4, 230 231 /** 232 * Create a request suitable for zero shutter lag still capture. This means 233 * means maximizing image quality without compromising preview frame rate. 234 * AE/AWB/AF should be on auto mode. 235 * 236 * @see ACameraDevice_createCaptureRequest 237 */ 238 TEMPLATE_ZERO_SHUTTER_LAG = 5, 239 240 /** 241 * A basic template for direct application control of capture 242 * parameters. All automatic control is disabled (auto-exposure, auto-white 243 * balance, auto-focus), and post-processing parameters are set to preview 244 * quality. The manual capture parameters (exposure, sensitivity, and so on) 245 * are set to reasonable defaults, but should be overriden by the 246 * application depending on the intended use case. 247 * This template is guaranteed to be supported on camera devices that support the 248 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR} capability. 249 * 250 * @see ACameraDevice_createCaptureRequest 251 */ 252 TEMPLATE_MANUAL = 6, 253 } ACameraDevice_request_template; 254 255 /** 256 * Create a ACaptureRequest for capturing images, initialized with template 257 * for a target use case. 258 * 259 * <p>The settings are chosen to be the best options for this camera device, 260 * so it is not recommended to reuse the same request for a different camera device.</p> 261 * 262 * @param device the camera device of interest 263 * @param templateId the type of capture request to be created. 264 * See {@link ACameraDevice_request_template}. 265 * @param request the output request will be stored here if the method call succeeds. 266 * 267 * @return <ul> 268 * <li>{@link ACAMERA_OK} if the method call succeeds. The created capture request will be 269 * filled in request argument.</li> 270 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if device or request is NULL, templateId 271 * is undefined or camera device does not support requested template. 272 * </li> 273 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed.</li> 274 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error.</li> 275 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error.</li> 276 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 277 * 278 * @see TEMPLATE_PREVIEW 279 * @see TEMPLATE_RECORD 280 * @see TEMPLATE_STILL_CAPTURE 281 * @see TEMPLATE_VIDEO_SNAPSHOT 282 * @see TEMPLATE_MANUAL 283 */ 284 camera_status_t ACameraDevice_createCaptureRequest( 285 const ACameraDevice* device, ACameraDevice_request_template templateId, 286 /*out*/ACaptureRequest** request); 287 288 289 typedef struct ACaptureSessionOutputContainer ACaptureSessionOutputContainer; 290 291 typedef struct ACaptureSessionOutput ACaptureSessionOutput; 292 293 /** 294 * Create a capture session output container. 295 * 296 * <p>The container is used in {@link ACameraDevice_createCaptureSession} method to create a capture 297 * session. Use {@link ACaptureSessionOutputContainer_free} to free the container and its memory 298 * after application no longer needs the ACaptureSessionOutputContainer.</p> 299 * 300 * @param container the output {@link ACaptureSessionOutputContainer} will be stored here if the 301 * method call succeeds. 302 * 303 * @return <ul> 304 * <li>{@link ACAMERA_OK} if the method call succeeds. The created container will be 305 * filled in container argument.</li> 306 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if container is NULL.</li></ul> 307 */ 308 camera_status_t ACaptureSessionOutputContainer_create( 309 /*out*/ACaptureSessionOutputContainer** container); 310 311 /** 312 * Free a capture session output container. 313 * 314 * @param container the {@link ACaptureSessionOutputContainer} to be freed. 315 * 316 * @see ACaptureSessionOutputContainer_create 317 */ 318 void ACaptureSessionOutputContainer_free(ACaptureSessionOutputContainer* container); 319 320 /** 321 * Create a ACaptureSessionOutput object. 322 * 323 * <p>The ACaptureSessionOutput is used in {@link ACaptureSessionOutputContainer_add} method to add 324 * an output {@link ANativeWindow} to ACaptureSessionOutputContainer. Use 325 * {@link ACaptureSessionOutput_free} to free the object and its memory after application no longer 326 * needs the {@link ACaptureSessionOutput}.</p> 327 * 328 * @param anw the {@link ANativeWindow} to be associated with the {@link ACaptureSessionOutput} 329 * @param output the output {@link ACaptureSessionOutput} will be stored here if the 330 * method call succeeds. 331 * 332 * @return <ul> 333 * <li>{@link ACAMERA_OK} if the method call succeeds. The created container will be 334 * filled in the output argument.</li> 335 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if anw or output is NULL.</li></ul> 336 * 337 * @see ACaptureSessionOutputContainer_add 338 */ 339 camera_status_t ACaptureSessionOutput_create( 340 ANativeWindow* anw, /*out*/ACaptureSessionOutput** output); 341 342 /** 343 * Free a ACaptureSessionOutput object. 344 * 345 * @param output the {@link ACaptureSessionOutput} to be freed. 346 * 347 * @see ACaptureSessionOutput_create 348 */ 349 void ACaptureSessionOutput_free(ACaptureSessionOutput* output); 350 351 /** 352 * Add an {@link ACaptureSessionOutput} object to {@link ACaptureSessionOutputContainer}. 353 * 354 * @param container the {@link ACaptureSessionOutputContainer} of interest. 355 * @param output the output {@link ACaptureSessionOutput} to be added to container. 356 * 357 * @return <ul> 358 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 359 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if container or output is NULL.</li></ul> 360 */ 361 camera_status_t ACaptureSessionOutputContainer_add( 362 ACaptureSessionOutputContainer* container, const ACaptureSessionOutput* output); 363 364 /** 365 * Remove an {@link ACaptureSessionOutput} object from {@link ACaptureSessionOutputContainer}. 366 * 367 * <p>This method has no effect if the ACaptureSessionOutput does not exist in 368 * ACaptureSessionOutputContainer.</p> 369 * 370 * @param container the {@link ACaptureSessionOutputContainer} of interest. 371 * @param output the output {@link ACaptureSessionOutput} to be removed from container. 372 * 373 * @return <ul> 374 * <li>{@link ACAMERA_OK} if the method call succeeds.</li> 375 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if container or output is NULL.</li></ul> 376 */ 377 camera_status_t ACaptureSessionOutputContainer_remove( 378 ACaptureSessionOutputContainer* container, const ACaptureSessionOutput* output); 379 380 /** 381 * Create a new camera capture session by providing the target output set of {@link ANativeWindow} 382 * to the camera device. 383 * 384 * <p>If there is a preexisting session, the previous session will be closed 385 * automatically. However, app still needs to call {@link ACameraCaptureSession_close} on previous 386 * session. Otherwise the resources held by previous session will NOT be freed.</p> 387 * 388 * <p>The active capture session determines the set of potential output {@link ANativeWindow}s for 389 * the camera device for each capture request. A given request may use all 390 * or only some of the outputs. Once the ACameraCaptureSession is created, requests can be 391 * submitted with {@link ACameraCaptureSession_capture} or 392 * {@link ACameraCaptureSession_setRepeatingRequest}.</p> 393 * 394 * <p>Often the {@link ANativeWindow} used with this method can be obtained from a <a href= 395 * "http://developer.android.com/reference/android/view/Surface.html">Surface</a> java object by 396 * {@link ANativeWindow_fromSurface} NDK method. Surfaces or ANativeWindow suitable for inclusion as a camera 397 * output can be created for various use cases and targets:</p> 398 * 399 * <ul> 400 * 401 * <li>For drawing to a 402 * <a href="http://developer.android.com/reference/android/view/SurfaceView.html">SurfaceView</a>: 403 * Once the SurfaceView's Surface is created, set the size 404 * of the Surface with 405 * <a href="http://developer.android.com/reference/android/view/SurfaceHolder.html#setFixedSize(int, int)"> 406 * android.view.SurfaceHolder\#setFixedSize</a> to be one of the PRIVATE output sizes 407 * returned by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 408 * and then obtain the Surface by calling <a href= 409 * "http://developer.android.com/reference/android/view/SurfaceHolder.html#getSurface()"> 410 * android.view.SurfaceHolder\#getSurface</a>. If the size is not set by the application, it will 411 * be rounded to the nearest supported size less than 1080p, by the camera device.</li> 412 * 413 * <li>For accessing through an OpenGL texture via a <a href= 414 * "http://developer.android.com/reference/android/graphics/SurfaceTexture.html">SurfaceTexture</a>: 415 * Set the size of the SurfaceTexture with <a href= 416 * "http://developer.android.com/reference/android/graphics/SurfaceTexture.html#setDefaultBufferSize(int, int)"> 417 * setDefaultBufferSize</a> to be one of the PRIVATE output sizes 418 * returned by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} 419 * before creating a Surface from the SurfaceTexture with <a href= 420 * "http://developer.android.com/reference/android/view/Surface.html#Surface(android.graphics.SurfaceTexture)"> 421 * Surface\#Surface(SurfaceTextrue)</a>. If the size is not set by the application, it will be set to be the 422 * smallest supported size less than 1080p, by the camera device.</li> 423 * 424 * <li>For recording with <a href= 425 * "http://developer.android.com/reference/android/media/MediaCodec.html"> 426 * MediaCodec</a>: Call 427 * <a href= 428 * "http://developer.android.com/reference/android/media/MediaCodec.html#createInputSurface()"> 429 * android.media.MediaCodec\#createInputSurface</a> after configuring 430 * the media codec to use one of the PRIVATE output sizes 431 * returned by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}. 432 * </li> 433 * 434 * <li>For recording with <a href= 435 * "http://developer.android.com/reference/android/media/MediaRecorder.html"> 436 * MediaRecorder</a>: Call 437 * <a href="http://developer.android.com/reference/android/media/MediaRecorder.html#getSurface()"> 438 * android.media.MediaRecorder\#getSurface</a> after configuring the media recorder to use 439 * one of the PRIVATE output sizes returned by 440 * {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}, or configuring it to use one of the supported 441 * <a href="http://developer.android.com/reference/android/media/CamcorderProfile.html"> 442 * CamcorderProfiles</a>.</li> 443 * 444 * <li>For efficient YUV processing with <a href= 445 * "http://developer.android.com/reference/android/renderscript/package-summary.html"> 446 * RenderScript</a>: 447 * Create a RenderScript 448 * <a href="http://developer.android.com/reference/android/renderscript/Allocation.html"> 449 * Allocation</a> with a supported YUV 450 * type, the IO_INPUT flag, and one of the YUV output sizes returned by 451 * {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}, 452 * Then obtain the Surface with 453 * <a href="http://developer.android.com/reference/android/renderscript/Allocation.html#getSurface()"> 454 * Allocation#getSurface}</a>.</li> 455 * 456 * <li>For access to RAW, uncompressed YUV, or compressed JPEG data in the application: Create an 457 * {@link AImageReader} object using the {@link AImageReader_new} method with one of the supported 458 * output formats given by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}. Then obtain a 459 * ANativeWindow from it with {@link AImageReader_getWindow}. 460 * If the AImageReader size is not set to a supported size, it will be rounded to a supported 461 * size less than 1080p by the camera device. 462 * </li> 463 * 464 * </ul> 465 * 466 * <p>The camera device will query each ANativeWindow's size and formats upon this 467 * call, so they must be set to a valid setting at this time.</p> 468 * 469 * <p>It can take several hundred milliseconds for the session's configuration to complete, 470 * since camera hardware may need to be powered on or reconfigured.</p> 471 * 472 * <p>If a prior ACameraCaptureSession already exists when this method is called, the previous 473 * session will no longer be able to accept new capture requests and will be closed. Any 474 * in-progress capture requests made on the prior session will be completed before it's closed. 475 * To minimize the transition time, 476 * the ACameraCaptureSession_abortCaptures method can be used to discard the remaining 477 * requests for the prior capture session before a new one is created. Note that once the new 478 * session is created, the old one can no longer have its captures aborted.</p> 479 * 480 * <p>Using larger resolution outputs, or more outputs, can result in slower 481 * output rate from the device.</p> 482 * 483 * <p>Configuring a session with an empty list will close the current session, if 484 * any. This can be used to release the current session's target surfaces for another use.</p> 485 * 486 * <p>While any of the sizes from {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} can be used when 487 * a single output stream is configured, a given camera device may not be able to support all 488 * combination of sizes, formats, and targets when multiple outputs are configured at once. The 489 * tables below list the maximum guaranteed resolutions for combinations of streams and targets, 490 * given the capabilities of the camera device.</p> 491 * 492 * <p>If an application tries to create a session using a set of targets that exceed the limits 493 * described in the below tables, one of three possibilities may occur. First, the session may 494 * be successfully created and work normally. Second, the session may be successfully created, 495 * but the camera device won't meet the frame rate guarantees as described in 496 * {@link ACAMERA_SCALER_AVAILABLE_MIN_FRAME_DURATIONS}. Or third, if the output set 497 * cannot be used at all, session creation will fail entirely, with 498 * {@link ACAMERA_ERROR_STREAM_CONFIGURE_FAIL} being returned.</p> 499 * 500 * <p>For the type column `PRIV` refers to output format {@link AIMAGE_FORMAT_PRIVATE}, 501 * `YUV` refers to output format {@link AIMAGE_FORMAT_YUV_420_888}, 502 * `JPEG` refers to output format {@link AIMAGE_FORMAT_JPEG}, 503 * and `RAW` refers to output format {@link AIMAGE_FORMAT_RAW16} 504 * 505 * 506 * <p>For the maximum size column, `PREVIEW` refers to the best size match to the 507 * device's screen resolution, or to 1080p `(1920x1080)`, whichever is 508 * smaller. `RECORD` refers to the camera device's maximum supported recording resolution, 509 * as determined by <a href="http://developer.android.com/reference/android/media/CamcorderProfile.html"> 510 * android.media.CamcorderProfiles</a>. And `MAXIMUM` refers to the 511 * camera device's maximum output resolution for that format or target from 512 * {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS}.</p> 513 * 514 * <p>To use these tables, determine the number and the formats/targets of outputs needed, and 515 * find the row(s) of the table with those targets. The sizes indicate the maximum set of sizes 516 * that can be used; it is guaranteed that for those targets, the listed sizes and anything 517 * smaller from the list given by {@link ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS} can be 518 * successfully used to create a session. For example, if a row indicates that a 8 megapixel 519 * (MP) YUV_420_888 output can be used together with a 2 MP `PRIV` output, then a session 520 * can be created with targets `[8 MP YUV, 2 MP PRIV]` or targets `[2 MP YUV, 2 MP PRIV]`; 521 * but a session with targets `[8 MP YUV, 4 MP PRIV]`, targets `[4 MP YUV, 4 MP PRIV]`, 522 * or targets `[8 MP PRIV, 2 MP YUV]` would not be guaranteed to work, unless 523 * some other row of the table lists such a combination.</p> 524 * 525 * <p>Legacy devices ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 526 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY}) support at 527 * least the following stream combinations: 528 * 529 * <table> 530 * <tr><th colspan="7">LEGACY-level guaranteed configurations</th></tr> 531 * <tr> <th colspan="2" id="rb">Target 1</th> <th colspan="2" id="rb">Target 2</th> <th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 532 * <tr> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th> <th>Type</th><th id="rb">Max size</th></tr> 533 * <tr> <td>`PRIV`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>Simple preview, GPU video processing, or no-preview video recording.</td> </tr> 534 * <tr> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-viewfinder still image capture.</td> </tr> 535 * <tr> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>In-application video/image processing.</td> </tr> 536 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Standard still imaging.</td> </tr> 537 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>In-app processing plus still capture.</td> </tr> 538 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td colspan="2" id="rb"></td> <td>Standard recording.</td> </tr> 539 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td colspan="2" id="rb"></td> <td>Preview plus in-app processing.</td> </tr> 540 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>Still capture plus in-app processing.</td> </tr> 541 * </table><br> 542 * </p> 543 * 544 * <p>Limited-level ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 545 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED}) devices 546 * support at least the following stream combinations in addition to those for 547 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY LEGACY} devices: 548 * 549 * <table> 550 * <tr><th colspan="7">LIMITED-level additional guaranteed configurations</th></tr> 551 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 552 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th></tr> 553 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`RECORD `</td> <td colspan="2" id="rb"></td> <td>High-resolution video recording with preview.</td> </tr> 554 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`RECORD `</td> <td colspan="2" id="rb"></td> <td>High-resolution in-app video processing with preview.</td> </tr> 555 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`RECORD `</td> <td colspan="2" id="rb"></td> <td>Two-input in-app video processing.</td> </tr> 556 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`RECORD `</td> <td>`JPEG`</td><td id="rb">`RECORD `</td> <td>High-resolution recording with video snapshot.</td> </tr> 557 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`RECORD `</td> <td>`JPEG`</td><td id="rb">`RECORD `</td> <td>High-resolution in-app processing with video snapshot.</td> </tr> 558 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>Two-input in-app processing with still capture.</td> </tr> 559 * </table><br> 560 * </p> 561 * 562 * <p>FULL-level ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 563 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL}) devices 564 * support at least the following stream combinations in addition to those for 565 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 566 * 567 * <table> 568 * <tr><th colspan="7">FULL-level additional guaranteed configurations</th></tr> 569 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 570 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 571 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 572 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 573 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 574 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>Video recording with maximum-size video snapshot</td> </tr> 575 * <tr> <td>`YUV `</td><td id="rb">`640x480`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Standard video recording plus maximum-resolution in-app processing.</td> </tr> 576 * <tr> <td>`YUV `</td><td id="rb">`640x480`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Preview plus two-input maximum-resolution in-app processing.</td> </tr> 577 * </table><br> 578 * </p> 579 * 580 * <p>RAW-capability ({@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES} includes 581 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}) devices additionally support 582 * at least the following stream combinations on both 583 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and 584 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices: 585 * 586 * <table> 587 * <tr><th colspan="7">RAW-capability additional guaranteed configurations</th></tr> 588 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th> <th rowspan="2">Sample use case(s)</th> </tr> 589 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 590 * <tr> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td colspan="2" id="rb"></td> <td>No-preview DNG capture.</td> </tr> 591 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>Standard DNG capture.</td> </tr> 592 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td colspan="2" id="rb"></td> <td>In-app processing plus DNG capture.</td> </tr> 593 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Video recording with DNG capture.</td> </tr> 594 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Preview with in-app processing and DNG capture.</td> </tr> 595 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Two-input in-app processing plus DNG capture.</td> </tr> 596 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>Still capture with simultaneous JPEG and DNG.</td> </tr> 597 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>`RAW `</td><td id="rb">`MAXIMUM`</td> <td>In-app processing with simultaneous JPEG and DNG.</td> </tr> 598 * </table><br> 599 * </p> 600 * 601 * <p>BURST-capability ({@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES} includes 602 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_BURST_CAPTURE BURST_CAPTURE}) devices 603 * support at least the below stream combinations in addition to those for 604 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED LIMITED} devices. Note that all 605 * FULL-level devices support the BURST capability, and the below list is a strict subset of the 606 * list for FULL-level devices, so this table is only relevant for LIMITED-level devices that 607 * support the BURST_CAPTURE capability. 608 * 609 * <table> 610 * <tr><th colspan="5">BURST-capability additional guaranteed configurations</th></tr> 611 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th rowspan="2">Sample use case(s)</th> </tr> 612 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 613 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`MAXIMUM`</td> <td>Maximum-resolution GPU processing with preview.</td> </tr> 614 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Maximum-resolution in-app processing with preview.</td> </tr> 615 * <tr> <td>`YUV `</td><td id="rb">`PREVIEW`</td> <td>`YUV `</td><td id="rb">`MAXIMUM`</td> <td>Maximum-resolution two-input in-app processsing.</td> </tr> 616 * </table><br> 617 * </p> 618 * 619 * <p>LEVEL-3 ({@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL} 620 * `== `{@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_3 LEVEL_3}) 621 * support at least the following stream combinations in addition to the combinations for 622 * {@link ACAMERA_INFO_SUPPORTED_HARDWARE_LEVEL_FULL FULL} and for 623 * RAW capability ({@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES} includes 624 * {@link ACAMERA_REQUEST_AVAILABLE_CAPABILITIES_RAW RAW}): 625 * 626 * <table> 627 * <tr><th colspan="11">LEVEL-3 additional guaranteed configurations</th></tr> 628 * <tr><th colspan="2" id="rb">Target 1</th><th colspan="2" id="rb">Target 2</th><th colspan="2" id="rb">Target 3</th><th colspan="2" id="rb">Target 4</th><th rowspan="2">Sample use case(s)</th> </tr> 629 * <tr><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th><th>Type</th><th id="rb">Max size</th> </tr> 630 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`640x480`</td> <td>`YUV`</td><td id="rb">`MAXIMUM`</td> <td>`RAW`</td><td id="rb">`MAXIMUM`</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 631 * <tr> <td>`PRIV`</td><td id="rb">`PREVIEW`</td> <td>`PRIV`</td><td id="rb">`640x480`</td> <td>`JPEG`</td><td id="rb">`MAXIMUM`</td> <td>`RAW`</td><td id="rb">`MAXIMUM`</td> <td>In-app viewfinder analysis with dynamic selection of output format.</td> </tr> 632 * </table><br> 633 * </p> 634 * 635 * <p>Since the capabilities of camera devices vary greatly, a given camera device may support 636 * target combinations with sizes outside of these guarantees, but this can only be tested for 637 * by attempting to create a session with such targets.</p> 638 * 639 * @param device the camera device of interest. 640 * @param outputs the {@link ACaptureSessionOutputContainer} describes all output streams. 641 * @param callbacks the {@link ACameraCaptureSession_stateCallbacks capture session state callbacks}. 642 * @param session the created {@link ACameraCaptureSession} will be filled here if the method call 643 * succeeds. 644 * 645 * @return <ul> 646 * <li>{@link ACAMERA_OK} if the method call succeeds. The created capture session will be 647 * filled in session argument.</li> 648 * <li>{@link ACAMERA_ERROR_INVALID_PARAMETER} if any of device, outputs, callbacks or 649 * session is NULL.</li> 650 * <li>{@link ACAMERA_ERROR_CAMERA_DISCONNECTED} if the camera device is closed.</li> 651 * <li>{@link ACAMERA_ERROR_CAMERA_DEVICE} if the camera device encounters fatal error.</li> 652 * <li>{@link ACAMERA_ERROR_CAMERA_SERVICE} if the camera service encounters fatal error.</li> 653 * <li>{@link ACAMERA_ERROR_UNKNOWN} if the method fails for some other reasons.</li></ul> 654 */ 655 camera_status_t ACameraDevice_createCaptureSession( 656 ACameraDevice* device, 657 const ACaptureSessionOutputContainer* outputs, 658 const ACameraCaptureSession_stateCallbacks* callbacks, 659 /*out*/ACameraCaptureSession** session); 660 661 #ifdef __cplusplus 662 } // extern "C" 663 #endif 664 665 #endif // _NDK_CAMERA_DEVICE_H 666 667 /** @} */ 668 669