StreamConfigurationMap.java revision b0056642cab30647d1f72190d864622bf4728ea0
1/* 2 * Copyright (C) 2014 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 17package android.hardware.camera2.params; 18 19import android.graphics.ImageFormat; 20import android.graphics.PixelFormat; 21import android.hardware.camera2.CameraCharacteristics; 22import android.hardware.camera2.CameraDevice; 23import android.hardware.camera2.CaptureRequest; 24import android.hardware.camera2.utils.HashCodeHelpers; 25import android.view.Surface; 26import android.util.Log; 27import android.util.Range; 28import android.util.Size; 29 30import java.util.Arrays; 31import java.util.HashMap; 32import java.util.Objects; 33import java.util.Set; 34 35import static com.android.internal.util.Preconditions.*; 36 37/** 38 * Immutable class to store the available stream 39 * {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP configurations} to set up 40 * {@link android.view.Surface Surfaces} for creating a 41 * {@link android.hardware.camera2.CameraCaptureSession capture session} with 42 * {@link android.hardware.camera2.CameraDevice#createCaptureSession}. 43 * <!-- TODO: link to input stream configuration --> 44 * 45 * <p>This is the authoritative list for all <!-- input/ -->output formats (and sizes respectively 46 * for that format) that are supported by a camera device.</p> 47 * 48 * <p>This also contains the minimum frame durations and stall durations for each format/size 49 * combination that can be used to calculate effective frame rate when submitting multiple captures. 50 * </p> 51 * 52 * <p>An instance of this object is available from {@link CameraCharacteristics} using 53 * the {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP} key and the 54 * {@link CameraCharacteristics#get} method.</p> 55 * 56 * <pre><code>{@code 57 * CameraCharacteristics characteristics = cameraManager.getCameraCharacteristics(cameraId); 58 * StreamConfigurationMap configs = characteristics.get( 59 * CameraCharacteristics.SCALER_STREAM_CONFIGURATION_MAP); 60 * }</code></pre> 61 * 62 * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP 63 * @see CameraDevice#createCaptureSession 64 */ 65public final class StreamConfigurationMap { 66 67 private static final String TAG = "StreamConfigurationMap"; 68 69 /** 70 * Indicates that a minimum frame duration is not available for a particular configuration. 71 */ 72 public static final long NO_MIN_FRAME_DURATION = 0; 73 74 /** 75 * Create a new {@link StreamConfigurationMap}. 76 * 77 * <p>The array parameters ownership is passed to this object after creation; do not 78 * write to them after this constructor is invoked.</p> 79 * 80 * @param configurations a non-{@code null} array of {@link StreamConfiguration} 81 * @param minFrameDurations a non-{@code null} array of {@link StreamConfigurationDuration} 82 * @param stallDurations a non-{@code null} array of {@link StreamConfigurationDuration} 83 * @param highSpeedVideoConfigurations an array of {@link HighSpeedVideoConfiguration}, null if 84 * camera device does not support high speed video recording 85 * 86 * @throws NullPointerException if any of the arguments except highSpeedVideoConfigurations 87 * were {@code null} or any subelements were {@code null} 88 * 89 * @hide 90 */ 91 public StreamConfigurationMap( 92 StreamConfiguration[] configurations, 93 StreamConfigurationDuration[] minFrameDurations, 94 StreamConfigurationDuration[] stallDurations, 95 HighSpeedVideoConfiguration[] highSpeedVideoConfigurations) { 96 97 mConfigurations = checkArrayElementsNotNull(configurations, "configurations"); 98 mMinFrameDurations = checkArrayElementsNotNull(minFrameDurations, "minFrameDurations"); 99 mStallDurations = checkArrayElementsNotNull(stallDurations, "stallDurations"); 100 if (highSpeedVideoConfigurations == null) { 101 mHighSpeedVideoConfigurations = new HighSpeedVideoConfiguration[0]; 102 } else { 103 mHighSpeedVideoConfigurations = checkArrayElementsNotNull( 104 highSpeedVideoConfigurations, "highSpeedVideoConfigurations"); 105 } 106 107 // For each format, track how many sizes there are available to configure 108 for (StreamConfiguration config : configurations) { 109 HashMap<Integer, Integer> map = config.isOutput() ? mOutputFormats : mInputFormats; 110 111 Integer count = map.get(config.getFormat()); 112 113 if (count == null) { 114 count = 0; 115 } 116 count = count + 1; 117 118 map.put(config.getFormat(), count); 119 } 120 121 if (!mOutputFormats.containsKey(HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED)) { 122 throw new AssertionError( 123 "At least one stream configuration for IMPLEMENTATION_DEFINED must exist"); 124 } 125 126 // For each Size/FPS range, track how many FPS range/Size there are available 127 for (HighSpeedVideoConfiguration config : mHighSpeedVideoConfigurations) { 128 Size size = config.getSize(); 129 Range<Integer> fpsRange = config.getFpsRange(); 130 Integer fpsRangeCount = mHighSpeedVideoSizeMap.get(size); 131 if (fpsRangeCount == null) { 132 fpsRangeCount = 0; 133 } 134 mHighSpeedVideoSizeMap.put(size, fpsRangeCount + 1); 135 Integer sizeCount = mHighSpeedVideoFpsRangeMap.get(fpsRange); 136 if (sizeCount == null) { 137 sizeCount = 0; 138 } 139 mHighSpeedVideoFpsRangeMap.put(fpsRange, sizeCount + 1); 140 } 141 } 142 143 /** 144 * Get the image {@code format} output formats in this stream configuration. 145 * 146 * <p>All image formats returned by this function will be defined in either {@link ImageFormat} 147 * or in {@link PixelFormat} (and there is no possibility of collision).</p> 148 * 149 * <p>Formats listed in this array are guaranteed to return true if queried with 150 * {@link #isOutputSupportedFor(int).</p> 151 * 152 * @return an array of integer format 153 * 154 * @see ImageFormat 155 * @see PixelFormat 156 */ 157 public final int[] getOutputFormats() { 158 return getPublicFormats(/*output*/true); 159 } 160 161 /** 162 * Get the image {@code format} input formats in this stream configuration. 163 * 164 * <p>All image formats returned by this function will be defined in either {@link ImageFormat} 165 * or in {@link PixelFormat} (and there is no possibility of collision).</p> 166 * 167 * @return an array of integer format 168 * 169 * @see ImageFormat 170 * @see PixelFormat 171 * 172 * @hide 173 */ 174 public final int[] getInputFormats() { 175 return getPublicFormats(/*output*/false); 176 } 177 178 /** 179 * Get the supported input sizes for this input format. 180 * 181 * <p>The format must have come from {@link #getInputFormats}; otherwise 182 * {@code null} is returned.</p> 183 * 184 * @param format a format from {@link #getInputFormats} 185 * @return a non-empty array of sizes, or {@code null} if the format was not available. 186 * 187 * @hide 188 */ 189 public Size[] getInputSizes(final int format) { 190 return getPublicFormatSizes(format, /*output*/false); 191 } 192 193 /** 194 * Determine whether or not output surfaces with a particular user-defined format can be passed 195 * {@link CameraDevice#createCaptureSession createCaptureSession}. 196 * 197 * <p>This method determines that the output {@code format} is supported by the camera device; 198 * each output {@code surface} target may or may not itself support that {@code format}. 199 * Refer to the class which provides the surface for additional documentation.</p> 200 * 201 * <p>Formats for which this returns {@code true} are guaranteed to exist in the result 202 * returned by {@link #getOutputSizes}.</p> 203 * 204 * @param format an image format from either {@link ImageFormat} or {@link PixelFormat} 205 * @return 206 * {@code true} iff using a {@code surface} with this {@code format} will be 207 * supported with {@link CameraDevice#createCaptureSession} 208 * 209 * @throws IllegalArgumentException 210 * if the image format was not a defined named constant 211 * from either {@link ImageFormat} or {@link PixelFormat} 212 * 213 * @see ImageFormat 214 * @see PixelFormat 215 * @see CameraDevice#createCaptureSession 216 */ 217 public boolean isOutputSupportedFor(int format) { 218 checkArgumentFormat(format); 219 220 format = imageFormatToInternal(format); 221 return getFormatsMap(/*output*/true).containsKey(format); 222 } 223 224 /** 225 * Determine whether or not output streams can be configured with a particular class 226 * as a consumer. 227 * 228 * <p>The following list is generally usable for outputs: 229 * <ul> 230 * <li>{@link android.media.ImageReader} - 231 * Recommended for image processing or streaming to external resources (such as a file or 232 * network) 233 * <li>{@link android.media.MediaRecorder} - 234 * Recommended for recording video (simple to use) 235 * <li>{@link android.media.MediaCodec} - 236 * Recommended for recording video (more complicated to use, with more flexibility) 237 * <li>{@link android.renderscript.Allocation} - 238 * Recommended for image processing with {@link android.renderscript RenderScript} 239 * <li>{@link android.view.SurfaceHolder} - 240 * Recommended for low-power camera preview with {@link android.view.SurfaceView} 241 * <li>{@link android.graphics.SurfaceTexture} - 242 * Recommended for OpenGL-accelerated preview processing or compositing with 243 * {@link android.view.TextureView} 244 * </ul> 245 * </p> 246 * 247 * <p>Generally speaking this means that creating a {@link Surface} from that class <i>may</i> 248 * provide a producer endpoint that is suitable to be used with 249 * {@link CameraDevice#createCaptureSession}.</p> 250 * 251 * <p>Since not all of the above classes support output of all format and size combinations, 252 * the particular combination should be queried with {@link #isOutputSupportedFor(Surface)}.</p> 253 * 254 * @param klass a non-{@code null} {@link Class} object reference 255 * @return {@code true} if this class is supported as an output, {@code false} otherwise 256 * 257 * @throws NullPointerException if {@code klass} was {@code null} 258 * 259 * @see CameraDevice#createCaptureSession 260 * @see #isOutputSupportedFor(Surface) 261 */ 262 public static <T> boolean isOutputSupportedFor(Class<T> klass) { 263 checkNotNull(klass, "klass must not be null"); 264 265 if (klass == android.media.ImageReader.class) { 266 return true; 267 } else if (klass == android.media.MediaRecorder.class) { 268 return true; 269 } else if (klass == android.media.MediaCodec.class) { 270 return true; 271 } else if (klass == android.renderscript.Allocation.class) { 272 return true; 273 } else if (klass == android.view.SurfaceHolder.class) { 274 return true; 275 } else if (klass == android.graphics.SurfaceTexture.class) { 276 return true; 277 } 278 279 return false; 280 } 281 282 /** 283 * Determine whether or not the {@code surface} in its current state is suitable to be included 284 * in a {@link CameraDevice#createCaptureSession capture session} as an output. 285 * 286 * <p>Not all surfaces are usable with the {@link CameraDevice}, and not all configurations 287 * of that {@code surface} are compatible. Some classes that provide the {@code surface} are 288 * compatible with the {@link CameraDevice} in general 289 * (see {@link #isOutputSupportedFor(Class)}, but it is the caller's responsibility to put the 290 * {@code surface} into a state that will be compatible with the {@link CameraDevice}.</p> 291 * 292 * <p>Reasons for a {@code surface} being specifically incompatible might be: 293 * <ul> 294 * <li>Using a format that's not listed by {@link #getOutputFormats} 295 * <li>Using a format/size combination that's not listed by {@link #getOutputSizes} 296 * <li>The {@code surface} itself is not in a state where it can service a new producer.</p> 297 * </li> 298 * </ul> 299 * 300 * This is not an exhaustive list; see the particular class's documentation for further 301 * possible reasons of incompatibility.</p> 302 * 303 * @param surface a non-{@code null} {@link Surface} object reference 304 * @return {@code true} if this is supported, {@code false} otherwise 305 * 306 * @throws NullPointerException if {@code surface} was {@code null} 307 * 308 * @see CameraDevice#createCaptureSession 309 * @see #isOutputSupportedFor(Class) 310 */ 311 public boolean isOutputSupportedFor(Surface surface) { 312 checkNotNull(surface, "surface must not be null"); 313 314 throw new UnsupportedOperationException("Not implemented yet"); 315 316 // TODO: JNI function that checks the Surface's IGraphicBufferProducer state 317 } 318 319 /** 320 * Get a list of sizes compatible with {@code klass} to use as an output. 321 * 322 * <p>Since some of the supported classes may support additional formats beyond 323 * an opaque/implementation-defined (under-the-hood) format; this function only returns 324 * sizes for the implementation-defined format.</p> 325 * 326 * <p>Some classes such as {@link android.media.ImageReader} may only support user-defined 327 * formats; in particular {@link #isOutputSupportedFor(Class)} will return {@code true} for 328 * that class and this method will return an empty array (but not {@code null}).</p> 329 * 330 * <p>If a well-defined format such as {@code NV21} is required, use 331 * {@link #getOutputSizes(int)} instead.</p> 332 * 333 * <p>The {@code klass} should be a supported output, that querying 334 * {@code #isOutputSupportedFor(Class)} should return {@code true}.</p> 335 * 336 * @param klass 337 * a non-{@code null} {@link Class} object reference 338 * @return 339 * an array of supported sizes for implementation-defined formats, 340 * or {@code null} iff the {@code klass} is not a supported output 341 * 342 * @throws NullPointerException if {@code klass} was {@code null} 343 * 344 * @see #isOutputSupportedFor(Class) 345 */ 346 public <T> Size[] getOutputSizes(Class<T> klass) { 347 if (isOutputSupportedFor(klass) == false) { 348 return null; 349 } 350 351 return getInternalFormatSizes(HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, /*output*/true); 352 } 353 354 /** 355 * Get a list of sizes compatible with the requested image {@code format}. 356 * 357 * <p>The {@code format} should be a supported format (one of the formats returned by 358 * {@link #getOutputFormats}).</p> 359 * 360 * @param format an image format from {@link ImageFormat} or {@link PixelFormat} 361 * @return 362 * an array of supported sizes, 363 * or {@code null} if the {@code format} is not a supported output 364 * 365 * @see ImageFormat 366 * @see PixelFormat 367 * @see #getOutputFormats 368 */ 369 public Size[] getOutputSizes(int format) { 370 return getPublicFormatSizes(format, /*output*/true); 371 } 372 373 /** 374 * Get a list of supported high speed video recording sizes. 375 * 376 * <p> When HIGH_SPEED_VIDEO is supported in 377 * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES available scene modes}, this 378 * method will list the supported high speed video size configurations. All the sizes listed 379 * will be a subset of the sizes reported by {@link #getOutputSizes} for processed non-stalling 380 * formats (typically ImageFormat#YUV_420_888, ImageFormat#NV21, ImageFormat#YV12)</p> 381 * 382 * <p> To enable high speed video recording, application must set 383 * {@link CaptureRequest#CONTROL_SCENE_MODE} to 384 * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture 385 * requests and select the video size from this method and 386 * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS range} from 387 * {@link #getHighSpeedVideoFpsRangesFor} to configure the recording and preview streams and 388 * setup the recording requests. For example, if the application intends to do high speed 389 * recording, it can select the maximum size reported by this method to configure output 390 * streams. Note that for the use case of multiple output streams, application must select one 391 * unique size from this method to use. Otherwise a request error might occur. Once the size is 392 * selected, application can get the supported FPS ranges by 393 * {@link #getHighSpeedVideoFpsRangesFor}, and use these FPS ranges to setup the recording 394 * requests.</p> 395 * 396 * @return 397 * an array of supported high speed video recording sizes 398 * 399 * @see #getHighSpeedVideoFpsRangesFor(Size) 400 */ 401 public Size[] getHighSpeedVideoSizes() { 402 Set<Size> keySet = mHighSpeedVideoSizeMap.keySet(); 403 return keySet.toArray(new Size[keySet.size()]); 404 } 405 406 /** 407 * Get the frame per second ranges (fpsMin, fpsMax) for input high speed video size. 408 * 409 * <p> See {@link #getHighSpeedVideoSizes} for how to enable high speed recording.</p> 410 * 411 * <p> For normal video recording use case, where some application will NOT set 412 * {@link CaptureRequest#CONTROL_SCENE_MODE} to 413 * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture 414 * requests, the {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS ranges} reported in 415 * this method must not be used to setup capture requests, or it will cause request error.</p> 416 * 417 * @param size one of the sizes returned by {@link #getHighSpeedVideoSizes()} 418 * @return 419 * An array of FPS range to use with 420 * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE TARGET_FPS_RANGE} when using 421 * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} scene 422 * mode. 423 * The upper bound of returned ranges is guaranteed to be larger or equal to 60. 424 * 425 * @throws IllegalArgumentException if input size does not exist in the return value of 426 * getHighSpeedVideoSizes 427 * @see #getHighSpeedVideoSizes() 428 */ 429 public Range<Integer>[] getHighSpeedVideoFpsRangesFor(Size size) { 430 Integer fpsRangeCount = mHighSpeedVideoSizeMap.get(size); 431 if (fpsRangeCount == null || fpsRangeCount == 0) { 432 throw new IllegalArgumentException(String.format( 433 "Size %s does not support high speed video recording", size)); 434 } 435 436 @SuppressWarnings("unchecked") 437 Range<Integer>[] fpsRanges = new Range[fpsRangeCount]; 438 int i = 0; 439 for (HighSpeedVideoConfiguration config : mHighSpeedVideoConfigurations) { 440 if (size.equals(config.getSize())) { 441 fpsRanges[i++] = config.getFpsRange(); 442 } 443 } 444 return fpsRanges; 445 } 446 447 /** 448 * Get a list of supported high speed video recording FPS ranges. 449 * 450 * <p> When HIGH_SPEED_VIDEO is supported in 451 * {@link CameraCharacteristics#CONTROL_AVAILABLE_SCENE_MODES available scene modes}, this 452 * method will list the supported high speed video FPS range configurations. Application can 453 * then use {@link #getHighSpeedVideoSizesFor} to query available sizes for one of returned 454 * FPS range.</p> 455 * 456 * <p> To enable high speed video recording, application must set 457 * {@link CaptureRequest#CONTROL_SCENE_MODE} to 458 * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture 459 * requests and select the video size from {@link #getHighSpeedVideoSizesFor} and 460 * {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS range} from 461 * this method to configure the recording and preview streams and setup the recording requests. 462 * For example, if the application intends to do high speed recording, it can select one FPS 463 * range reported by this method, query the video sizes corresponding to this FPS range by 464 * {@link #getHighSpeedVideoSizesFor} and select one of reported sizes to configure output 465 * streams. Note that for the use case of multiple output streams, application must select one 466 * unique size from {@link #getHighSpeedVideoSizesFor}, and use it for all output streams. 467 * Otherwise a request error might occur when attempting to enable 468 * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO}. 469 * Once the stream is configured, application can set the FPS range in the recording requests. 470 * </p> 471 * 472 * @return 473 * an array of supported high speed video recording FPS ranges 474 * The upper bound of returned ranges is guaranteed to be larger or equal to 60. 475 * 476 * @see #getHighSpeedVideoSizesFor 477 */ 478 @SuppressWarnings("unchecked") 479 public Range<Integer>[] getHighSpeedVideoFpsRanges() { 480 Set<Range<Integer>> keySet = mHighSpeedVideoFpsRangeMap.keySet(); 481 return keySet.toArray(new Range[keySet.size()]); 482 } 483 484 /** 485 * Get the supported video sizes for input FPS range. 486 * 487 * <p> See {@link #getHighSpeedVideoFpsRanges} for how to enable high speed recording.</p> 488 * 489 * <p> For normal video recording use case, where the application will NOT set 490 * {@link CaptureRequest#CONTROL_SCENE_MODE} to 491 * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} in capture 492 * requests, the {@link CaptureRequest#CONTROL_AE_TARGET_FPS_RANGE FPS ranges} reported in 493 * this method must not be used to setup capture requests, or it will cause request error.</p> 494 * 495 * @param fpsRange one of the FPS range returned by {@link #getHighSpeedVideoFpsRanges()} 496 * @return 497 * An array of video sizes to configure output stream when using 498 * {@link CaptureRequest#CONTROL_SCENE_MODE_HIGH_SPEED_VIDEO HIGH_SPEED_VIDEO} scene 499 * mode. 500 * 501 * @throws IllegalArgumentException if input FPS range does not exist in the return value of 502 * getHighSpeedVideoFpsRanges 503 * @see #getHighSpeedVideoFpsRanges() 504 */ 505 public Size[] getHighSpeedVideoSizesFor(Range<Integer> fpsRange) { 506 Integer sizeCount = mHighSpeedVideoFpsRangeMap.get(fpsRange); 507 if (sizeCount == null || sizeCount == 0) { 508 throw new IllegalArgumentException(String.format( 509 "FpsRange %s does not support high speed video recording", fpsRange)); 510 } 511 512 Size[] sizes = new Size[sizeCount]; 513 int i = 0; 514 for (HighSpeedVideoConfiguration config : mHighSpeedVideoConfigurations) { 515 if (fpsRange.equals(config.getFpsRange())) { 516 sizes[i++] = config.getSize(); 517 } 518 } 519 return sizes; 520 } 521 522 /** 523 * Get the minimum {@link CaptureRequest#SENSOR_FRAME_DURATION frame duration} 524 * for the format/size combination (in nanoseconds). 525 * 526 * <p>{@code format} should be one of the ones returned by {@link #getOutputFormats()}.</p> 527 * <p>{@code size} should be one of the ones returned by 528 * {@link #getOutputSizes(int)}.</p> 529 * 530 * <p>This should correspond to the frame duration when only that stream is active, with all 531 * processing (typically in {@code android.*.mode}) set to either {@code OFF} or {@code FAST}. 532 * </p> 533 * 534 * <p>When multiple streams are used in a request, the minimum frame duration will be 535 * {@code max(individual stream min durations)}.</p> 536 * 537 * <p>For devices that do not support manual sensor control 538 * ({@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR}), 539 * this function may return {@link #NO_MIN_FRAME_DURATION}.</p> 540 * 541 * <!-- 542 * TODO: uncomment after adding input stream support 543 * <p>The minimum frame duration of a stream (of a particular format, size) is the same 544 * regardless of whether the stream is input or output.</p> 545 * --> 546 * 547 * @param format an image format from {@link ImageFormat} or {@link PixelFormat} 548 * @param size an output-compatible size 549 * @return a minimum frame duration {@code >} 0 in nanoseconds, or 550 * {@link #NO_MIN_FRAME_DURATION} if the minimum frame duration is not available. 551 * 552 * @throws IllegalArgumentException if {@code format} or {@code size} was not supported 553 * @throws NullPointerException if {@code size} was {@code null} 554 * 555 * @see CaptureRequest#SENSOR_FRAME_DURATION 556 * @see #getOutputStallDuration(int, Size) 557 * @see ImageFormat 558 * @see PixelFormat 559 */ 560 public long getOutputMinFrameDuration(int format, Size size) { 561 checkNotNull(size, "size must not be null"); 562 checkArgumentFormatSupported(format, /*output*/true); 563 564 return getInternalFormatDuration(imageFormatToInternal(format), size, DURATION_MIN_FRAME); 565 } 566 567 /** 568 * Get the minimum {@link CaptureRequest#SENSOR_FRAME_DURATION frame duration} 569 * for the class/size combination (in nanoseconds). 570 * 571 * <p>This assumes a the {@code klass} is set up to use an implementation-defined format. 572 * For user-defined formats, use {@link #getOutputMinFrameDuration(int, Size)}.</p> 573 * 574 * <p>{@code klass} should be one of the ones which is supported by 575 * {@link #isOutputSupportedFor(Class)}.</p> 576 * 577 * <p>{@code size} should be one of the ones returned by 578 * {@link #getOutputSizes(int)}.</p> 579 * 580 * <p>This should correspond to the frame duration when only that stream is active, with all 581 * processing (typically in {@code android.*.mode}) set to either {@code OFF} or {@code FAST}. 582 * </p> 583 * 584 * <p>When multiple streams are used in a request, the minimum frame duration will be 585 * {@code max(individual stream min durations)}.</p> 586 * 587 * <p>For devices that do not support manual sensor control 588 * ({@link android.hardware.camera2.CameraMetadata#REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR}), 589 * this function may return {@link #NO_MIN_FRAME_DURATION}.</p> 590 * 591 * <!-- 592 * TODO: uncomment after adding input stream support 593 * <p>The minimum frame duration of a stream (of a particular format, size) is the same 594 * regardless of whether the stream is input or output.</p> 595 * --> 596 * 597 * @param klass 598 * a class which is supported by {@link #isOutputSupportedFor(Class)} and has a 599 * non-empty array returned by {@link #getOutputSizes(Class)} 600 * @param size an output-compatible size 601 * @return a minimum frame duration {@code >} 0 in nanoseconds, or 602 * {@link #NO_MIN_FRAME_DURATION} if the minimum frame duration is not available. 603 * 604 * @throws IllegalArgumentException if {@code klass} or {@code size} was not supported 605 * @throws NullPointerException if {@code size} or {@code klass} was {@code null} 606 * 607 * @see CaptureRequest#SENSOR_FRAME_DURATION 608 * @see ImageFormat 609 * @see PixelFormat 610 */ 611 public <T> long getOutputMinFrameDuration(final Class<T> klass, final Size size) { 612 if (!isOutputSupportedFor(klass)) { 613 throw new IllegalArgumentException("klass was not supported"); 614 } 615 616 return getInternalFormatDuration(HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 617 size, DURATION_MIN_FRAME); 618 } 619 620 /** 621 * Get the stall duration for the format/size combination (in nanoseconds). 622 * 623 * <p>{@code format} should be one of the ones returned by {@link #getOutputFormats()}.</p> 624 * <p>{@code size} should be one of the ones returned by 625 * {@link #getOutputSizes(int)}.</p> 626 * 627 * <p> 628 * A stall duration is how much extra time would get added to the normal minimum frame duration 629 * for a repeating request that has streams with non-zero stall. 630 * 631 * <p>For example, consider JPEG captures which have the following characteristics: 632 * 633 * <ul> 634 * <li>JPEG streams act like processed YUV streams in requests for which they are not included; 635 * in requests in which they are directly referenced, they act as JPEG streams. 636 * This is because supporting a JPEG stream requires the underlying YUV data to always be ready 637 * for use by a JPEG encoder, but the encoder will only be used (and impact frame duration) on 638 * requests that actually reference a JPEG stream. 639 * <li>The JPEG processor can run concurrently to the rest of the camera pipeline, but cannot 640 * process more than 1 capture at a time. 641 * </ul> 642 * 643 * <p>In other words, using a repeating YUV request would result in a steady frame rate 644 * (let's say it's 30 FPS). If a single JPEG request is submitted periodically, 645 * the frame rate will stay at 30 FPS (as long as we wait for the previous JPEG to return each 646 * time). If we try to submit a repeating YUV + JPEG request, then the frame rate will drop from 647 * 30 FPS.</p> 648 * 649 * <p>In general, submitting a new request with a non-0 stall time stream will <em>not</em> cause a 650 * frame rate drop unless there are still outstanding buffers for that stream from previous 651 * requests.</p> 652 * 653 * <p>Submitting a repeating request with streams (call this {@code S}) is the same as setting 654 * the minimum frame duration from the normal minimum frame duration corresponding to {@code S}, 655 * added with the maximum stall duration for {@code S}.</p> 656 * 657 * <p>If interleaving requests with and without a stall duration, a request will stall by the 658 * maximum of the remaining times for each can-stall stream with outstanding buffers.</p> 659 * 660 * <p>This means that a stalling request will not have an exposure start until the stall has 661 * completed.</p> 662 * 663 * <p>This should correspond to the stall duration when only that stream is active, with all 664 * processing (typically in {@code android.*.mode}) set to {@code FAST} or {@code OFF}. 665 * Setting any of the processing modes to {@code HIGH_QUALITY} effectively results in an 666 * indeterminate stall duration for all streams in a request (the regular stall calculation 667 * rules are ignored).</p> 668 * 669 * <p>The following formats may always have a stall duration: 670 * <ul> 671 * <li>{@link ImageFormat#JPEG JPEG} 672 * <li>{@link ImageFormat#RAW_SENSOR RAW16} 673 * </ul> 674 * </p> 675 * 676 * <p>The following formats will never have a stall duration: 677 * <ul> 678 * <li>{@link ImageFormat#YUV_420_888 YUV_420_888} 679 * <li>{@link #isOutputSupportedFor(Class) Implementation-Defined} 680 * </ul></p> 681 * 682 * <p> 683 * All other formats may or may not have an allowed stall duration on a per-capability basis; 684 * refer to {@link CameraCharacteristics#REQUEST_AVAILABLE_CAPABILITIES 685 * android.request.availableCapabilities} for more details.</p> 686 * </p> 687 * 688 * <p>See {@link CaptureRequest#SENSOR_FRAME_DURATION android.sensor.frameDuration} 689 * for more information about calculating the max frame rate (absent stalls).</p> 690 * 691 * @param format an image format from {@link ImageFormat} or {@link PixelFormat} 692 * @param size an output-compatible size 693 * @return a stall duration {@code >=} 0 in nanoseconds 694 * 695 * @throws IllegalArgumentException if {@code format} or {@code size} was not supported 696 * @throws NullPointerException if {@code size} was {@code null} 697 * 698 * @see CaptureRequest#SENSOR_FRAME_DURATION 699 * @see ImageFormat 700 * @see PixelFormat 701 */ 702 public long getOutputStallDuration(int format, Size size) { 703 checkArgumentFormatSupported(format, /*output*/true); 704 705 return getInternalFormatDuration(imageFormatToInternal(format), 706 size, DURATION_STALL); 707 } 708 709 /** 710 * Get the stall duration for the class/size combination (in nanoseconds). 711 * 712 * <p>This assumes a the {@code klass} is set up to use an implementation-defined format. 713 * For user-defined formats, use {@link #getOutputMinFrameDuration(int, Size)}.</p> 714 * 715 * <p>{@code klass} should be one of the ones with a non-empty array returned by 716 * {@link #getOutputSizes(Class)}.</p> 717 * 718 * <p>{@code size} should be one of the ones returned by 719 * {@link #getOutputSizes(Class)}.</p> 720 * 721 * <p>See {@link #getOutputStallDuration(int, Size)} for a definition of a 722 * <em>stall duration</em>.</p> 723 * 724 * @param klass 725 * a class which is supported by {@link #isOutputSupportedFor(Class)} and has a 726 * non-empty array returned by {@link #getOutputSizes(Class)} 727 * @param size an output-compatible size 728 * @return a minimum frame duration {@code >=} 0 in nanoseconds 729 * 730 * @throws IllegalArgumentException if {@code klass} or {@code size} was not supported 731 * @throws NullPointerException if {@code size} or {@code klass} was {@code null} 732 * 733 * @see CaptureRequest#SENSOR_FRAME_DURATION 734 * @see ImageFormat 735 * @see PixelFormat 736 */ 737 public <T> long getOutputStallDuration(final Class<T> klass, final Size size) { 738 if (!isOutputSupportedFor(klass)) { 739 throw new IllegalArgumentException("klass was not supported"); 740 } 741 742 return getInternalFormatDuration(HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED, 743 size, DURATION_STALL); 744 } 745 746 /** 747 * Check if this {@link StreamConfigurationMap} is equal to another 748 * {@link StreamConfigurationMap}. 749 * 750 * <p>Two vectors are only equal if and only if each of the respective elements is equal.</p> 751 * 752 * @return {@code true} if the objects were equal, {@code false} otherwise 753 */ 754 @Override 755 public boolean equals(final Object obj) { 756 if (obj == null) { 757 return false; 758 } 759 if (this == obj) { 760 return true; 761 } 762 if (obj instanceof StreamConfigurationMap) { 763 final StreamConfigurationMap other = (StreamConfigurationMap) obj; 764 // XX: do we care about order? 765 return Arrays.equals(mConfigurations, other.mConfigurations) && 766 Arrays.equals(mMinFrameDurations, other.mMinFrameDurations) && 767 Arrays.equals(mStallDurations, other.mStallDurations) && 768 Arrays.equals(mHighSpeedVideoConfigurations, 769 other.mHighSpeedVideoConfigurations); 770 } 771 return false; 772 } 773 774 /** 775 * {@inheritDoc} 776 */ 777 @Override 778 public int hashCode() { 779 // XX: do we care about order? 780 return HashCodeHelpers.hashCode( 781 mConfigurations, mMinFrameDurations, 782 mStallDurations, mHighSpeedVideoConfigurations); 783 } 784 785 // Check that the argument is supported by #getOutputFormats or #getInputFormats 786 private int checkArgumentFormatSupported(int format, boolean output) { 787 checkArgumentFormat(format); 788 789 int[] formats = output ? getOutputFormats() : getInputFormats(); 790 for (int i = 0; i < formats.length; ++i) { 791 if (format == formats[i]) { 792 return format; 793 } 794 } 795 796 throw new IllegalArgumentException(String.format( 797 "format %x is not supported by this stream configuration map", format)); 798 } 799 800 /** 801 * Ensures that the format is either user-defined or implementation defined. 802 * 803 * <p>If a format has a different internal representation than the public representation, 804 * passing in the public representation here will fail.</p> 805 * 806 * <p>For example if trying to use {@link ImageFormat#JPEG}: 807 * it has a different public representation than the internal representation 808 * {@code HAL_PIXEL_FORMAT_BLOB}, this check will fail.</p> 809 * 810 * <p>Any invalid/undefined formats will raise an exception.</p> 811 * 812 * @param format image format 813 * @return the format 814 * 815 * @throws IllegalArgumentException if the format was invalid 816 */ 817 static int checkArgumentFormatInternal(int format) { 818 switch (format) { 819 case HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED: 820 case HAL_PIXEL_FORMAT_BLOB: 821 return format; 822 case ImageFormat.JPEG: 823 throw new IllegalArgumentException( 824 "ImageFormat.JPEG is an unknown internal format"); 825 default: 826 return checkArgumentFormat(format); 827 } 828 } 829 830 /** 831 * Ensures that the format is publicly user-defined in either ImageFormat or PixelFormat. 832 * 833 * <p>If a format has a different public representation than the internal representation, 834 * passing in the internal representation here will fail.</p> 835 * 836 * <p>For example if trying to use {@code HAL_PIXEL_FORMAT_BLOB}: 837 * it has a different internal representation than the public representation 838 * {@link ImageFormat#JPEG}, this check will fail.</p> 839 * 840 * <p>Any invalid/undefined formats will raise an exception, including implementation-defined. 841 * </p> 842 * 843 * <p>Note that {@code @hide} and deprecated formats will not pass this check.</p> 844 * 845 * @param format image format 846 * @return the format 847 * 848 * @throws IllegalArgumentException if the format was not user-defined 849 */ 850 static int checkArgumentFormat(int format) { 851 // TODO: remove this hack , CTS shouldn't have been using internal constants 852 if (format == HAL_PIXEL_FORMAT_RAW_OPAQUE) { 853 Log.w(TAG, "RAW_OPAQUE is not yet a published format; allowing it anyway"); 854 return format; 855 } 856 857 if (!ImageFormat.isPublicFormat(format) && !PixelFormat.isPublicFormat(format)) { 858 throw new IllegalArgumentException(String.format( 859 "format 0x%x was not defined in either ImageFormat or PixelFormat", format)); 860 } 861 862 return format; 863 } 864 865 /** 866 * Convert a public-visible {@code ImageFormat} into an internal format 867 * compatible with {@code graphics.h}. 868 * 869 * <p>In particular these formats are converted: 870 * <ul> 871 * <li>HAL_PIXEL_FORMAT_BLOB => ImageFormat.JPEG 872 * </ul> 873 * </p> 874 * 875 * <p>Passing in an implementation-defined format which has no public equivalent will fail; 876 * as will passing in a public format which has a different internal format equivalent. 877 * See {@link #checkArgumentFormat} for more details about a legal public format.</p> 878 * 879 * <p>All other formats are returned as-is, no further invalid check is performed.</p> 880 * 881 * <p>This function is the dual of {@link #imageFormatToInternal}.</p> 882 * 883 * @param format image format from {@link ImageFormat} or {@link PixelFormat} 884 * @return the converted image formats 885 * 886 * @throws IllegalArgumentException 887 * if {@code format} is {@code HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED} or 888 * {@link ImageFormat#JPEG} 889 * 890 * @see ImageFormat 891 * @see PixelFormat 892 * @see #checkArgumentFormat 893 */ 894 static int imageFormatToPublic(int format) { 895 switch (format) { 896 case HAL_PIXEL_FORMAT_BLOB: 897 return ImageFormat.JPEG; 898 case ImageFormat.JPEG: 899 throw new IllegalArgumentException( 900 "ImageFormat.JPEG is an unknown internal format"); 901 case HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED: 902 throw new IllegalArgumentException( 903 "IMPLEMENTATION_DEFINED must not leak to public API"); 904 default: 905 return format; 906 } 907 } 908 909 /** 910 * Convert image formats from internal to public formats (in-place). 911 * 912 * @param formats an array of image formats 913 * @return {@code formats} 914 * 915 * @see #imageFormatToPublic 916 */ 917 static int[] imageFormatToPublic(int[] formats) { 918 if (formats == null) { 919 return null; 920 } 921 922 for (int i = 0; i < formats.length; ++i) { 923 formats[i] = imageFormatToPublic(formats[i]); 924 } 925 926 return formats; 927 } 928 929 /** 930 * Convert a public format compatible with {@code ImageFormat} to an internal format 931 * from {@code graphics.h}. 932 * 933 * <p>In particular these formats are converted: 934 * <ul> 935 * <li>ImageFormat.JPEG => HAL_PIXEL_FORMAT_BLOB 936 * </ul> 937 * </p> 938 * 939 * <p>Passing in an implementation-defined format here will fail (it's not a public format); 940 * as will passing in an internal format which has a different public format equivalent. 941 * See {@link #checkArgumentFormat} for more details about a legal public format.</p> 942 * 943 * <p>All other formats are returned as-is, no invalid check is performed.</p> 944 * 945 * <p>This function is the dual of {@link #imageFormatToPublic}.</p> 946 * 947 * @param format public image format from {@link ImageFormat} or {@link PixelFormat} 948 * @return the converted image formats 949 * 950 * @see ImageFormat 951 * @see PixelFormat 952 * 953 * @throws IllegalArgumentException 954 * if {@code format} was {@code HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED} 955 */ 956 static int imageFormatToInternal(int format) { 957 switch (format) { 958 case ImageFormat.JPEG: 959 return HAL_PIXEL_FORMAT_BLOB; 960 case HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED: 961 throw new IllegalArgumentException( 962 "IMPLEMENTATION_DEFINED is not allowed via public API"); 963 default: 964 return format; 965 } 966 } 967 968 /** 969 * Convert image formats from public to internal formats (in-place). 970 * 971 * @param formats an array of image formats 972 * @return {@code formats} 973 * 974 * @see #imageFormatToInternal 975 * 976 * @hide 977 */ 978 public static int[] imageFormatToInternal(int[] formats) { 979 if (formats == null) { 980 return null; 981 } 982 983 for (int i = 0; i < formats.length; ++i) { 984 formats[i] = imageFormatToInternal(formats[i]); 985 } 986 987 return formats; 988 } 989 990 private Size[] getPublicFormatSizes(int format, boolean output) { 991 try { 992 checkArgumentFormatSupported(format, output); 993 } catch (IllegalArgumentException e) { 994 return null; 995 } 996 997 format = imageFormatToInternal(format); 998 999 return getInternalFormatSizes(format, output); 1000 } 1001 1002 private Size[] getInternalFormatSizes(int format, boolean output) { 1003 HashMap<Integer, Integer> formatsMap = getFormatsMap(output); 1004 1005 Integer sizesCount = formatsMap.get(format); 1006 if (sizesCount == null) { 1007 throw new IllegalArgumentException("format not available"); 1008 } 1009 1010 int len = sizesCount; 1011 Size[] sizes = new Size[len]; 1012 int sizeIndex = 0; 1013 1014 for (StreamConfiguration config : mConfigurations) { 1015 if (config.getFormat() == format && config.isOutput() == output) { 1016 sizes[sizeIndex++] = config.getSize(); 1017 } 1018 } 1019 1020 if (sizeIndex != len) { 1021 throw new AssertionError( 1022 "Too few sizes (expected " + len + ", actual " + sizeIndex + ")"); 1023 } 1024 1025 return sizes; 1026 } 1027 1028 /** Get the list of publically visible output formats; does not include IMPL_DEFINED */ 1029 private int[] getPublicFormats(boolean output) { 1030 int[] formats = new int[getPublicFormatCount(output)]; 1031 1032 int i = 0; 1033 1034 for (int format : getFormatsMap(output).keySet()) { 1035 if (format != HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED) { 1036 formats[i++] = format; 1037 } 1038 } 1039 1040 if (formats.length != i) { 1041 throw new AssertionError("Too few formats " + i + ", expected " + formats.length); 1042 } 1043 1044 return imageFormatToPublic(formats); 1045 } 1046 1047 /** Get the format -> size count map for either output or input formats */ 1048 private HashMap<Integer, Integer> getFormatsMap(boolean output) { 1049 return output ? mOutputFormats : mInputFormats; 1050 } 1051 1052 private long getInternalFormatDuration(int format, Size size, int duration) { 1053 // assume format is already checked, since its internal 1054 1055 if (!arrayContains(getInternalFormatSizes(format, /*output*/true), size)) { 1056 throw new IllegalArgumentException("size was not supported"); 1057 } 1058 1059 StreamConfigurationDuration[] durations = getDurations(duration); 1060 1061 for (StreamConfigurationDuration configurationDuration : durations) { 1062 if (configurationDuration.getFormat() == format && 1063 configurationDuration.getWidth() == size.getWidth() && 1064 configurationDuration.getHeight() == size.getHeight()) { 1065 return configurationDuration.getDuration(); 1066 } 1067 } 1068 1069 return getDurationDefault(duration); 1070 } 1071 1072 /** 1073 * Get the durations array for the kind of duration 1074 * 1075 * @see #DURATION_MIN_FRAME 1076 * @see #DURATION_STALL 1077 * */ 1078 private StreamConfigurationDuration[] getDurations(int duration) { 1079 switch (duration) { 1080 case DURATION_MIN_FRAME: 1081 return mMinFrameDurations; 1082 case DURATION_STALL: 1083 return mStallDurations; 1084 default: 1085 throw new IllegalArgumentException("duration was invalid"); 1086 } 1087 } 1088 1089 private long getDurationDefault(int duration) { 1090 switch (duration) { 1091 case DURATION_MIN_FRAME: 1092 return NO_MIN_FRAME_DURATION; 1093 case DURATION_STALL: 1094 return 0L; // OK. A lack of a stall duration implies a 0 stall duration 1095 default: 1096 throw new IllegalArgumentException("duration was invalid"); 1097 } 1098 } 1099 1100 /** Count the number of publicly-visible output formats */ 1101 private int getPublicFormatCount(boolean output) { 1102 HashMap<Integer, Integer> formatsMap = getFormatsMap(output); 1103 1104 int size = formatsMap.size(); 1105 if (formatsMap.containsKey(HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED)) { 1106 size -= 1; 1107 } 1108 return size; 1109 } 1110 1111 private static <T> boolean arrayContains(T[] array, T element) { 1112 if (array == null) { 1113 return false; 1114 } 1115 1116 for (T el : array) { 1117 if (Objects.equals(el, element)) { 1118 return true; 1119 } 1120 } 1121 1122 return false; 1123 } 1124 1125 // from system/core/include/system/graphics.h 1126 private static final int HAL_PIXEL_FORMAT_BLOB = 0x21; 1127 private static final int HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED = 0x22; 1128 private static final int HAL_PIXEL_FORMAT_RAW_OPAQUE = 0x24; 1129 1130 /** 1131 * @see #getDurations(int) 1132 * @see #getDurationDefault(int) 1133 */ 1134 private static final int DURATION_MIN_FRAME = 0; 1135 private static final int DURATION_STALL = 1; 1136 1137 private final StreamConfiguration[] mConfigurations; 1138 private final StreamConfigurationDuration[] mMinFrameDurations; 1139 private final StreamConfigurationDuration[] mStallDurations; 1140 private final HighSpeedVideoConfiguration[] mHighSpeedVideoConfigurations; 1141 1142 /** ImageFormat -> num output sizes mapping */ 1143 private final HashMap</*ImageFormat*/Integer, /*Count*/Integer> mOutputFormats = 1144 new HashMap<Integer, Integer>(); 1145 /** ImageFormat -> num input sizes mapping */ 1146 private final HashMap</*ImageFormat*/Integer, /*Count*/Integer> mInputFormats = 1147 new HashMap<Integer, Integer>(); 1148 /** High speed video Size -> FPS range count mapping*/ 1149 private final HashMap</*HighSpeedVideoSize*/Size, /*Count*/Integer> mHighSpeedVideoSizeMap = 1150 new HashMap<Size, Integer>(); 1151 /** High speed video FPS range -> Size count mapping*/ 1152 private final HashMap</*HighSpeedVideoFpsRange*/Range<Integer>, /*Count*/Integer> 1153 mHighSpeedVideoFpsRangeMap = new HashMap<Range<Integer>, Integer>(); 1154 1155} 1156