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 package android.hardware.camera2.params; 19 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.annotation.SystemApi; 23 import android.graphics.ImageFormat; 24 import android.hardware.camera2.CameraCaptureSession; 25 import android.hardware.camera2.CameraDevice; 26 import android.hardware.camera2.utils.HashCodeHelpers; 27 import android.hardware.camera2.utils.SurfaceUtils; 28 import android.os.Parcel; 29 import android.os.Parcelable; 30 import android.util.Log; 31 import android.util.Size; 32 import android.view.Surface; 33 34 import static com.android.internal.util.Preconditions.*; 35 36 import java.util.ArrayList; 37 import java.util.Collections; 38 import java.util.List; 39 40 /** 41 * A class for describing camera output, which contains a {@link Surface} and its specific 42 * configuration for creating capture session. 43 * 44 * <p>There are several ways to instantiate, modify and use OutputConfigurations. The most common 45 * and recommended usage patterns are summarized in the following list:</p> 46 *<ul> 47 * <li>Passing a {@link Surface} to the constructor and using the OutputConfiguration instance as 48 * argument to {@link CameraDevice#createCaptureSessionByOutputConfigurations}. This is the most 49 * frequent usage and clients should consider it first before other more complicated alternatives. 50 * </li> 51 * 52 * <li>Passing only a surface source class as an argument to the constructor. This is usually 53 * followed by a call to create a capture session 54 * (see {@link CameraDevice#createCaptureSessionByOutputConfigurations} and a {@link Surface} add 55 * call {@link #addSurface} with a valid {@link Surface}. The sequence completes with 56 * {@link CameraCaptureSession#finalizeOutputConfigurations}. This is the deferred usage case which 57 * aims to enhance performance by allowing the resource-intensive capture session create call to 58 * execute in parallel with any {@link Surface} initialization, such as waiting for a 59 * {@link android.view.SurfaceView} to be ready as part of the UI initialization.</li> 60 * 61 * <li>The third and most complex usage pattern inlvolves surface sharing. Once instantiated an 62 * OutputConfiguration can be enabled for surface sharing via {@link #enableSurfaceSharing}. This 63 * must be done before creating a new capture session and enables calls to 64 * {@link CameraCaptureSession#updateOutputConfiguration}. An OutputConfiguration with enabled 65 * surface sharing can be modified via {@link #addSurface} or {@link #removeSurface}. The updates 66 * to this OutputConfiguration will only come into effect after 67 * {@link CameraCaptureSession#updateOutputConfiguration} returns without throwing exceptions. 68 * Such updates can be done as long as the session is active. Clients should always consider the 69 * additional requirements and limitations placed on the output surfaces (for more details see 70 * {@link #enableSurfaceSharing}, {@link #addSurface}, {@link #removeSurface}, 71 * {@link CameraCaptureSession#updateOutputConfiguration}). A trade-off exists between additional 72 * complexity and flexibility. If exercised correctly surface sharing can switch between different 73 * output surfaces without interrupting any ongoing repeating capture requests. This saves time and 74 * can significantly improve the user experience.</li> 75 * 76 * <li>Surface sharing can be used in combination with deferred surfaces. The rules from both cases 77 * are combined and clients must call {@link #enableSurfaceSharing} before creating a capture 78 * session. Attach and/or remove output surfaces via {@link #addSurface}/{@link #removeSurface} and 79 * finalize the configuration using {@link CameraCaptureSession#finalizeOutputConfigurations}. 80 * {@link CameraCaptureSession#updateOutputConfiguration} can be called after the configuration 81 * finalize method returns without exceptions.</li> 82 * 83 * </ul> 84 * 85 * <p> As of {@link android.os.Build.VERSION_CODES#P Android P}, all formats can be used for 86 * sharing, subject to device support. On prior API levels, only {@link ImageFormat#PRIVATE} 87 * format may be used.</p> 88 * 89 * @see CameraDevice#createCaptureSessionByOutputConfigurations 90 * 91 */ 92 public final class OutputConfiguration implements Parcelable { 93 94 /** 95 * Rotation constant: 0 degree rotation (no rotation) 96 * 97 * @hide 98 */ 99 @SystemApi 100 public static final int ROTATION_0 = 0; 101 102 /** 103 * Rotation constant: 90 degree counterclockwise rotation. 104 * 105 * @hide 106 */ 107 @SystemApi 108 public static final int ROTATION_90 = 1; 109 110 /** 111 * Rotation constant: 180 degree counterclockwise rotation. 112 * 113 * @hide 114 */ 115 @SystemApi 116 public static final int ROTATION_180 = 2; 117 118 /** 119 * Rotation constant: 270 degree counterclockwise rotation. 120 * 121 * @hide 122 */ 123 @SystemApi 124 public static final int ROTATION_270 = 3; 125 126 /** 127 * Invalid surface group ID. 128 * 129 *<p>An {@link OutputConfiguration} with this value indicates that the included surface 130 *doesn't belong to any surface group.</p> 131 */ 132 public static final int SURFACE_GROUP_ID_NONE = -1; 133 134 /** 135 * Create a new {@link OutputConfiguration} instance with a {@link Surface}. 136 * 137 * @param surface 138 * A Surface for camera to output to. 139 * 140 * <p>This constructor creates a default configuration, with a surface group ID of 141 * {@value #SURFACE_GROUP_ID_NONE}.</p> 142 * 143 */ OutputConfiguration(@onNull Surface surface)144 public OutputConfiguration(@NonNull Surface surface) { 145 this(SURFACE_GROUP_ID_NONE, surface, ROTATION_0); 146 } 147 148 /** 149 * Unknown surface source type. 150 */ 151 private final int SURFACE_TYPE_UNKNOWN = -1; 152 153 /** 154 * The surface is obtained from {@link android.view.SurfaceView}. 155 */ 156 private final int SURFACE_TYPE_SURFACE_VIEW = 0; 157 158 /** 159 * The surface is obtained from {@link android.graphics.SurfaceTexture}. 160 */ 161 private final int SURFACE_TYPE_SURFACE_TEXTURE = 1; 162 163 /** 164 * Maximum number of surfaces supported by one {@link OutputConfiguration}. 165 * 166 * <p>The combined number of surfaces added by the constructor and 167 * {@link OutputConfiguration#addSurface} should not exceed this value.</p> 168 * 169 */ 170 private static final int MAX_SURFACES_COUNT = 4; 171 172 /** 173 * Create a new {@link OutputConfiguration} instance with a {@link Surface}, 174 * with a surface group ID. 175 * 176 * <p> 177 * A surface group ID is used to identify which surface group this output surface belongs to. A 178 * surface group is a group of output surfaces that are not intended to receive camera output 179 * buffer streams simultaneously. The {@link CameraDevice} may be able to share the buffers used 180 * by all the surfaces from the same surface group, therefore may reduce the overall memory 181 * footprint. The application should only set the same set ID for the streams that are not 182 * simultaneously streaming. A negative ID indicates that this surface doesn't belong to any 183 * surface group. The default value is {@value #SURFACE_GROUP_ID_NONE}.</p> 184 * 185 * <p>For example, a video chat application that has an adaptive output resolution feature would 186 * need two (or more) output resolutions, to switch resolutions without any output glitches. 187 * However, at any given time, only one output is active to minimize outgoing network bandwidth 188 * and encoding overhead. To save memory, the application should set the video outputs to have 189 * the same non-negative group ID, so that the camera device can share the same memory region 190 * for the alternating outputs.</p> 191 * 192 * <p>It is not an error to include output streams with the same group ID in the same capture 193 * request, but the resulting memory consumption may be higher than if the two streams were 194 * not in the same surface group to begin with, especially if the outputs have substantially 195 * different dimensions.</p> 196 * 197 * @param surfaceGroupId 198 * A group ID for this output, used for sharing memory between multiple outputs. 199 * @param surface 200 * A Surface for camera to output to. 201 * 202 */ OutputConfiguration(int surfaceGroupId, @NonNull Surface surface)203 public OutputConfiguration(int surfaceGroupId, @NonNull Surface surface) { 204 this(surfaceGroupId, surface, ROTATION_0); 205 } 206 207 /** 208 * Create a new {@link OutputConfiguration} instance. 209 * 210 * <p>This constructor takes an argument for desired camera rotation</p> 211 * 212 * @param surface 213 * A Surface for camera to output to. 214 * @param rotation 215 * The desired rotation to be applied on camera output. Value must be one of 216 * ROTATION_[0, 90, 180, 270]. Note that when the rotation is 90 or 270 degrees, 217 * application should make sure corresponding surface size has width and height 218 * transposed relative to the width and height without rotation. For example, 219 * if application needs camera to capture 1280x720 picture and rotate it by 90 degree, 220 * application should set rotation to {@code ROTATION_90} and make sure the 221 * corresponding Surface size is 720x1280. Note that {@link CameraDevice} might 222 * throw {@code IllegalArgumentException} if device cannot perform such rotation. 223 * @hide 224 */ 225 @SystemApi OutputConfiguration(@onNull Surface surface, int rotation)226 public OutputConfiguration(@NonNull Surface surface, int rotation) { 227 this(SURFACE_GROUP_ID_NONE, surface, rotation); 228 } 229 230 /** 231 * Create a new {@link OutputConfiguration} instance, with rotation and a group ID. 232 * 233 * <p>This constructor takes an argument for desired camera rotation and for the surface group 234 * ID. See {@link #OutputConfiguration(int, Surface)} for details of the group ID.</p> 235 * 236 * @param surfaceGroupId 237 * A group ID for this output, used for sharing memory between multiple outputs. 238 * @param surface 239 * A Surface for camera to output to. 240 * @param rotation 241 * The desired rotation to be applied on camera output. Value must be one of 242 * ROTATION_[0, 90, 180, 270]. Note that when the rotation is 90 or 270 degrees, 243 * application should make sure corresponding surface size has width and height 244 * transposed relative to the width and height without rotation. For example, 245 * if application needs camera to capture 1280x720 picture and rotate it by 90 degree, 246 * application should set rotation to {@code ROTATION_90} and make sure the 247 * corresponding Surface size is 720x1280. Note that {@link CameraDevice} might 248 * throw {@code IllegalArgumentException} if device cannot perform such rotation. 249 * @hide 250 */ 251 @SystemApi OutputConfiguration(int surfaceGroupId, @NonNull Surface surface, int rotation)252 public OutputConfiguration(int surfaceGroupId, @NonNull Surface surface, int rotation) { 253 checkNotNull(surface, "Surface must not be null"); 254 checkArgumentInRange(rotation, ROTATION_0, ROTATION_270, "Rotation constant"); 255 mSurfaceGroupId = surfaceGroupId; 256 mSurfaceType = SURFACE_TYPE_UNKNOWN; 257 mSurfaces = new ArrayList<Surface>(); 258 mSurfaces.add(surface); 259 mRotation = rotation; 260 mConfiguredSize = SurfaceUtils.getSurfaceSize(surface); 261 mConfiguredFormat = SurfaceUtils.getSurfaceFormat(surface); 262 mConfiguredDataspace = SurfaceUtils.getSurfaceDataspace(surface); 263 mConfiguredGenerationId = surface.getGenerationId(); 264 mIsDeferredConfig = false; 265 mIsShared = false; 266 mPhysicalCameraId = null; 267 } 268 269 /** 270 * Create a new {@link OutputConfiguration} instance, with desired Surface size and Surface 271 * source class. 272 * <p> 273 * This constructor takes an argument for desired Surface size and the Surface source class 274 * without providing the actual output Surface. This is used to setup an output configuration 275 * with a deferred Surface. The application can use this output configuration to create a 276 * session. 277 * </p> 278 * <p> 279 * However, the actual output Surface must be set via {@link #addSurface} and the deferred 280 * Surface configuration must be finalized via {@link 281 * CameraCaptureSession#finalizeOutputConfigurations} before submitting a request with this 282 * Surface target. The deferred Surface can only be obtained either from {@link 283 * android.view.SurfaceView} by calling {@link android.view.SurfaceHolder#getSurface}, or from 284 * {@link android.graphics.SurfaceTexture} via 285 * {@link android.view.Surface#Surface(android.graphics.SurfaceTexture)}). 286 * </p> 287 * 288 * @param surfaceSize Size for the deferred surface. 289 * @param klass a non-{@code null} {@link Class} object reference that indicates the source of 290 * this surface. Only {@link android.view.SurfaceHolder SurfaceHolder.class} and 291 * {@link android.graphics.SurfaceTexture SurfaceTexture.class} are supported. 292 * @throws IllegalArgumentException if the Surface source class is not supported, or Surface 293 * size is zero. 294 */ OutputConfiguration(@onNull Size surfaceSize, @NonNull Class<T> klass)295 public <T> OutputConfiguration(@NonNull Size surfaceSize, @NonNull Class<T> klass) { 296 checkNotNull(klass, "surfaceSize must not be null"); 297 checkNotNull(klass, "klass must not be null"); 298 if (klass == android.view.SurfaceHolder.class) { 299 mSurfaceType = SURFACE_TYPE_SURFACE_VIEW; 300 } else if (klass == android.graphics.SurfaceTexture.class) { 301 mSurfaceType = SURFACE_TYPE_SURFACE_TEXTURE; 302 } else { 303 mSurfaceType = SURFACE_TYPE_UNKNOWN; 304 throw new IllegalArgumentException("Unknow surface source class type"); 305 } 306 307 if (surfaceSize.getWidth() == 0 || surfaceSize.getHeight() == 0) { 308 throw new IllegalArgumentException("Surface size needs to be non-zero"); 309 } 310 311 mSurfaceGroupId = SURFACE_GROUP_ID_NONE; 312 mSurfaces = new ArrayList<Surface>(); 313 mRotation = ROTATION_0; 314 mConfiguredSize = surfaceSize; 315 mConfiguredFormat = StreamConfigurationMap.imageFormatToInternal(ImageFormat.PRIVATE); 316 mConfiguredDataspace = StreamConfigurationMap.imageFormatToDataspace(ImageFormat.PRIVATE); 317 mConfiguredGenerationId = 0; 318 mIsDeferredConfig = true; 319 mIsShared = false; 320 mPhysicalCameraId = null; 321 } 322 323 /** 324 * Enable multiple surfaces sharing the same OutputConfiguration 325 * 326 * <p>For advanced use cases, a camera application may require more streams than the combination 327 * guaranteed by {@link CameraDevice#createCaptureSession}. In this case, more than one 328 * compatible surface can be attached to an OutputConfiguration so that they map to one 329 * camera stream, and the outputs share memory buffers when possible. Due to buffer sharing 330 * clients should be careful when adding surface outputs that modify their input data. If such 331 * case exists, camera clients should have an additional mechanism to synchronize read and write 332 * access between individual consumers.</p> 333 * 334 * <p>Two surfaces are compatible in the below cases:</p> 335 * 336 * <li> Surfaces with the same size, format, dataSpace, and Surface source class. In this case, 337 * {@link CameraDevice#createCaptureSessionByOutputConfigurations} is guaranteed to succeed. 338 * 339 * <li> Surfaces with the same size, format, and dataSpace, but different Surface source classes 340 * that are generally not compatible. However, on some devices, the underlying camera device is 341 * able to use the same buffer layout for both surfaces. The only way to discover if this is the 342 * case is to create a capture session with that output configuration. For example, if the 343 * camera device uses the same private buffer format between a SurfaceView/SurfaceTexture and a 344 * MediaRecorder/MediaCodec, {@link CameraDevice#createCaptureSessionByOutputConfigurations} 345 * will succeed. Otherwise, it fails with {@link 346 * CameraCaptureSession.StateCallback#onConfigureFailed}. 347 * </ol> 348 * 349 * <p>To enable surface sharing, this function must be called before {@link 350 * CameraDevice#createCaptureSessionByOutputConfigurations} or {@link 351 * CameraDevice#createReprocessableCaptureSessionByConfigurations}. Calling this function after 352 * {@link CameraDevice#createCaptureSessionByOutputConfigurations} has no effect.</p> 353 * 354 * <p>Up to {@link #getMaxSharedSurfaceCount} surfaces can be shared for an OutputConfiguration. 355 * The supported surfaces for sharing must be of type SurfaceTexture, SurfaceView, 356 * MediaRecorder, MediaCodec, or implementation defined ImageReader.</p> 357 */ enableSurfaceSharing()358 public void enableSurfaceSharing() { 359 mIsShared = true; 360 } 361 362 /** 363 * Set the id of the physical camera for this OutputConfiguration 364 * 365 * <p>In the case one logical camera is made up of multiple physical cameras, it could be 366 * desirable for the camera application to request streams from individual physical cameras. 367 * This call achieves it by mapping the OutputConfiguration to the physical camera id.</p> 368 * 369 * <p>The valid physical camera ids can be queried by {@link 370 * android.hardware.camera2.CameraCharacteristics#getPhysicalCameraIds}. 371 * </p> 372 * 373 * <p>Passing in a null physicalCameraId means that the OutputConfiguration is for a logical 374 * stream.</p> 375 * 376 * <p>This function must be called before {@link 377 * CameraDevice#createCaptureSessionByOutputConfigurations} or {@link 378 * CameraDevice#createReprocessableCaptureSessionByConfigurations}. Calling this function 379 * after {@link CameraDevice#createCaptureSessionByOutputConfigurations} or {@link 380 * CameraDevice#createReprocessableCaptureSessionByConfigurations} has no effect.</p> 381 * 382 * <p>The surface belonging to a physical camera OutputConfiguration must not be used as input 383 * or output of a reprocessing request. </p> 384 */ setPhysicalCameraId(@ullable String physicalCameraId)385 public void setPhysicalCameraId(@Nullable String physicalCameraId) { 386 mPhysicalCameraId = physicalCameraId; 387 } 388 389 /** 390 * Check if this configuration is for a physical camera. 391 * 392 * <p>This returns true if the output configuration was for a physical camera making up a 393 * logical multi camera via {@link OutputConfiguration#setPhysicalCameraId}.</p> 394 * @hide 395 */ isForPhysicalCamera()396 public boolean isForPhysicalCamera() { 397 return (mPhysicalCameraId != null); 398 } 399 400 /** 401 * Check if this configuration has deferred configuration. 402 * 403 * <p>This will return true if the output configuration was constructed with surface deferred by 404 * {@link OutputConfiguration#OutputConfiguration(Size, Class)}. It will return true even after 405 * the deferred surface is added later by {@link OutputConfiguration#addSurface}.</p> 406 * 407 * @return true if this configuration has deferred surface. 408 * @hide 409 */ isDeferredConfiguration()410 public boolean isDeferredConfiguration() { 411 return mIsDeferredConfig; 412 } 413 414 /** 415 * Add a surface to this OutputConfiguration. 416 * 417 * <p> This function can be called before or after {@link 418 * CameraDevice#createCaptureSessionByOutputConfigurations}. If it's called after, 419 * the application must finalize the capture session with 420 * {@link CameraCaptureSession#finalizeOutputConfigurations}. It is possible to call this method 421 * after the output configurations have been finalized only in cases of enabled surface sharing 422 * see {@link #enableSurfaceSharing}. The modified output configuration must be updated with 423 * {@link CameraCaptureSession#updateOutputConfiguration}.</p> 424 * 425 * <p> If the OutputConfiguration was constructed with a deferred surface by {@link 426 * OutputConfiguration#OutputConfiguration(Size, Class)}, the added surface must be obtained 427 * from {@link android.view.SurfaceView} by calling {@link android.view.SurfaceHolder#getSurface}, 428 * or from {@link android.graphics.SurfaceTexture} via 429 * {@link android.view.Surface#Surface(android.graphics.SurfaceTexture)}).</p> 430 * 431 * <p> If the OutputConfiguration was constructed by other constructors, the added 432 * surface must be compatible with the existing surface. See {@link #enableSurfaceSharing} for 433 * details of compatible surfaces.</p> 434 * 435 * <p> If the OutputConfiguration already contains a Surface, {@link #enableSurfaceSharing} must 436 * be called before calling this function to add a new Surface.</p> 437 * 438 * @param surface The surface to be added. 439 * @throws IllegalArgumentException if the Surface is invalid, the Surface's 440 * dataspace/format doesn't match, or adding the Surface would exceed number of 441 * shared surfaces supported. 442 * @throws IllegalStateException if the Surface was already added to this OutputConfiguration, 443 * or if the OutputConfiguration is not shared and it already has a surface associated 444 * with it. 445 */ addSurface(@onNull Surface surface)446 public void addSurface(@NonNull Surface surface) { 447 checkNotNull(surface, "Surface must not be null"); 448 if (mSurfaces.contains(surface)) { 449 throw new IllegalStateException("Surface is already added!"); 450 } 451 if (mSurfaces.size() == 1 && !mIsShared) { 452 throw new IllegalStateException("Cannot have 2 surfaces for a non-sharing configuration"); 453 } 454 if (mSurfaces.size() + 1 > MAX_SURFACES_COUNT) { 455 throw new IllegalArgumentException("Exceeds maximum number of surfaces"); 456 } 457 458 // This will throw IAE is the surface was abandoned. 459 Size surfaceSize = SurfaceUtils.getSurfaceSize(surface); 460 if (!surfaceSize.equals(mConfiguredSize)) { 461 Log.w(TAG, "Added surface size " + surfaceSize + 462 " is different than pre-configured size " + mConfiguredSize + 463 ", the pre-configured size will be used."); 464 } 465 466 if (mConfiguredFormat != SurfaceUtils.getSurfaceFormat(surface)) { 467 throw new IllegalArgumentException("The format of added surface format doesn't match"); 468 } 469 470 // If the surface format is PRIVATE, do not enforce dataSpace because camera device may 471 // override it. 472 if (mConfiguredFormat != ImageFormat.PRIVATE && 473 mConfiguredDataspace != SurfaceUtils.getSurfaceDataspace(surface)) { 474 throw new IllegalArgumentException("The dataspace of added surface doesn't match"); 475 } 476 477 mSurfaces.add(surface); 478 } 479 480 /** 481 * Remove a surface from this OutputConfiguration. 482 * 483 * <p> Surfaces added via calls to {@link #addSurface} can also be removed from the 484 * OutputConfiguration. The only notable exception is the surface associated with 485 * the OutputConfigration see {@link #getSurface} which was passed as part of the constructor 486 * or was added first in the deferred case 487 * {@link OutputConfiguration#OutputConfiguration(Size, Class)}.</p> 488 * 489 * @param surface The surface to be removed. 490 * 491 * @throws IllegalArgumentException If the surface is associated with this OutputConfiguration 492 * (see {@link #getSurface}) or the surface didn't get added 493 * with {@link #addSurface}. 494 */ removeSurface(@onNull Surface surface)495 public void removeSurface(@NonNull Surface surface) { 496 if (getSurface() == surface) { 497 throw new IllegalArgumentException( 498 "Cannot remove surface associated with this output configuration"); 499 } 500 if (!mSurfaces.remove(surface)) { 501 throw new IllegalArgumentException("Surface is not part of this output configuration"); 502 } 503 } 504 505 /** 506 * Create a new {@link OutputConfiguration} instance with another {@link OutputConfiguration} 507 * instance. 508 * 509 * @param other Another {@link OutputConfiguration} instance to be copied. 510 * 511 * @hide 512 */ OutputConfiguration(@onNull OutputConfiguration other)513 public OutputConfiguration(@NonNull OutputConfiguration other) { 514 if (other == null) { 515 throw new IllegalArgumentException("OutputConfiguration shouldn't be null"); 516 } 517 518 this.mSurfaces = other.mSurfaces; 519 this.mRotation = other.mRotation; 520 this.mSurfaceGroupId = other.mSurfaceGroupId; 521 this.mSurfaceType = other.mSurfaceType; 522 this.mConfiguredDataspace = other.mConfiguredDataspace; 523 this.mConfiguredFormat = other.mConfiguredFormat; 524 this.mConfiguredSize = other.mConfiguredSize; 525 this.mConfiguredGenerationId = other.mConfiguredGenerationId; 526 this.mIsDeferredConfig = other.mIsDeferredConfig; 527 this.mIsShared = other.mIsShared; 528 this.mPhysicalCameraId = other.mPhysicalCameraId; 529 } 530 531 /** 532 * Create an OutputConfiguration from Parcel. 533 */ OutputConfiguration(@onNull Parcel source)534 private OutputConfiguration(@NonNull Parcel source) { 535 int rotation = source.readInt(); 536 int surfaceSetId = source.readInt(); 537 int surfaceType = source.readInt(); 538 int width = source.readInt(); 539 int height = source.readInt(); 540 boolean isDeferred = source.readInt() == 1; 541 boolean isShared = source.readInt() == 1; 542 ArrayList<Surface> surfaces = new ArrayList<Surface>(); 543 source.readTypedList(surfaces, Surface.CREATOR); 544 String physicalCameraId = source.readString(); 545 546 checkArgumentInRange(rotation, ROTATION_0, ROTATION_270, "Rotation constant"); 547 548 mSurfaceGroupId = surfaceSetId; 549 mRotation = rotation; 550 mSurfaces = surfaces; 551 mConfiguredSize = new Size(width, height); 552 mIsDeferredConfig = isDeferred; 553 mIsShared = isShared; 554 mSurfaces = surfaces; 555 if (mSurfaces.size() > 0) { 556 mSurfaceType = SURFACE_TYPE_UNKNOWN; 557 mConfiguredFormat = SurfaceUtils.getSurfaceFormat(mSurfaces.get(0)); 558 mConfiguredDataspace = SurfaceUtils.getSurfaceDataspace(mSurfaces.get(0)); 559 mConfiguredGenerationId = mSurfaces.get(0).getGenerationId(); 560 } else { 561 mSurfaceType = surfaceType; 562 mConfiguredFormat = StreamConfigurationMap.imageFormatToInternal(ImageFormat.PRIVATE); 563 mConfiguredDataspace = 564 StreamConfigurationMap.imageFormatToDataspace(ImageFormat.PRIVATE); 565 mConfiguredGenerationId = 0; 566 } 567 mPhysicalCameraId = physicalCameraId; 568 } 569 570 /** 571 * Get the maximum supported shared {@link Surface} count. 572 * 573 * @return the maximum number of surfaces that can be added per each OutputConfiguration. 574 * 575 * @see #enableSurfaceSharing 576 */ getMaxSharedSurfaceCount()577 public int getMaxSharedSurfaceCount() { 578 return MAX_SURFACES_COUNT; 579 } 580 581 /** 582 * Get the {@link Surface} associated with this {@link OutputConfiguration}. 583 * 584 * If more than one surface is associated with this {@link OutputConfiguration}, return the 585 * first one as specified in the constructor or {@link OutputConfiguration#addSurface}. 586 */ getSurface()587 public @Nullable Surface getSurface() { 588 if (mSurfaces.size() == 0) { 589 return null; 590 } 591 592 return mSurfaces.get(0); 593 } 594 595 /** 596 * Get the immutable list of surfaces associated with this {@link OutputConfiguration}. 597 * 598 * @return the list of surfaces associated with this {@link OutputConfiguration} as specified in 599 * the constructor and {@link OutputConfiguration#addSurface}. The list should not be modified. 600 */ 601 @NonNull getSurfaces()602 public List<Surface> getSurfaces() { 603 return Collections.unmodifiableList(mSurfaces); 604 } 605 606 /** 607 * Get the rotation associated with this {@link OutputConfiguration}. 608 * 609 * @return the rotation associated with this {@link OutputConfiguration}. 610 * Value will be one of ROTATION_[0, 90, 180, 270] 611 * 612 * @hide 613 */ 614 @SystemApi getRotation()615 public int getRotation() { 616 return mRotation; 617 } 618 619 /** 620 * Get the surface group ID associated with this {@link OutputConfiguration}. 621 * 622 * @return the surface group ID associated with this {@link OutputConfiguration}. 623 * The default value is {@value #SURFACE_GROUP_ID_NONE}. 624 */ getSurfaceGroupId()625 public int getSurfaceGroupId() { 626 return mSurfaceGroupId; 627 } 628 629 public static final Parcelable.Creator<OutputConfiguration> CREATOR = 630 new Parcelable.Creator<OutputConfiguration>() { 631 @Override 632 public OutputConfiguration createFromParcel(Parcel source) { 633 try { 634 OutputConfiguration outputConfiguration = new OutputConfiguration(source); 635 return outputConfiguration; 636 } catch (Exception e) { 637 Log.e(TAG, "Exception creating OutputConfiguration from parcel", e); 638 return null; 639 } 640 } 641 642 @Override 643 public OutputConfiguration[] newArray(int size) { 644 return new OutputConfiguration[size]; 645 } 646 }; 647 648 @Override describeContents()649 public int describeContents() { 650 return 0; 651 } 652 653 @Override writeToParcel(Parcel dest, int flags)654 public void writeToParcel(Parcel dest, int flags) { 655 if (dest == null) { 656 throw new IllegalArgumentException("dest must not be null"); 657 } 658 dest.writeInt(mRotation); 659 dest.writeInt(mSurfaceGroupId); 660 dest.writeInt(mSurfaceType); 661 dest.writeInt(mConfiguredSize.getWidth()); 662 dest.writeInt(mConfiguredSize.getHeight()); 663 dest.writeInt(mIsDeferredConfig ? 1 : 0); 664 dest.writeInt(mIsShared ? 1 : 0); 665 dest.writeTypedList(mSurfaces); 666 dest.writeString(mPhysicalCameraId); 667 } 668 669 /** 670 * Check if this {@link OutputConfiguration} is equal to another {@link OutputConfiguration}. 671 * 672 * <p>Two output configurations are only equal if and only if the underlying surfaces, surface 673 * properties (width, height, format, dataspace) when the output configurations are created, 674 * and all other configuration parameters are equal. </p> 675 * 676 * @return {@code true} if the objects were equal, {@code false} otherwise 677 */ 678 @Override equals(Object obj)679 public boolean equals(Object obj) { 680 if (obj == null) { 681 return false; 682 } else if (this == obj) { 683 return true; 684 } else if (obj instanceof OutputConfiguration) { 685 final OutputConfiguration other = (OutputConfiguration) obj; 686 if (mRotation != other.mRotation || 687 !mConfiguredSize.equals(other.mConfiguredSize) || 688 mConfiguredFormat != other.mConfiguredFormat || 689 mSurfaceGroupId != other.mSurfaceGroupId || 690 mSurfaceType != other.mSurfaceType || 691 mIsDeferredConfig != other.mIsDeferredConfig || 692 mIsShared != other.mIsShared || 693 mConfiguredFormat != other.mConfiguredFormat || 694 mConfiguredDataspace != other.mConfiguredDataspace || 695 mConfiguredGenerationId != other.mConfiguredGenerationId) 696 return false; 697 698 int minLen = Math.min(mSurfaces.size(), other.mSurfaces.size()); 699 for (int i = 0; i < minLen; i++) { 700 if (mSurfaces.get(i) != other.mSurfaces.get(i)) 701 return false; 702 } 703 704 return true; 705 } 706 return false; 707 } 708 709 /** 710 * {@inheritDoc} 711 */ 712 @Override hashCode()713 public int hashCode() { 714 // Need ensure that the hashcode remains unchanged after adding a deferred surface. Otherwise 715 // the deferred output configuration will be lost in the camera streammap after the deferred 716 // surface is set. 717 if (mIsDeferredConfig) { 718 return HashCodeHelpers.hashCode( 719 mRotation, mConfiguredSize.hashCode(), mConfiguredFormat, mConfiguredDataspace, 720 mSurfaceGroupId, mSurfaceType, mIsShared ? 1 : 0, 721 mPhysicalCameraId == null ? 0 : mPhysicalCameraId.hashCode()); 722 } 723 724 return HashCodeHelpers.hashCode( 725 mRotation, mSurfaces.hashCode(), mConfiguredGenerationId, 726 mConfiguredSize.hashCode(), mConfiguredFormat, 727 mConfiguredDataspace, mSurfaceGroupId, mIsShared ? 1 : 0, 728 mPhysicalCameraId == null ? 0 : mPhysicalCameraId.hashCode()); 729 } 730 731 private static final String TAG = "OutputConfiguration"; 732 private ArrayList<Surface> mSurfaces; 733 private final int mRotation; 734 private final int mSurfaceGroupId; 735 // Surface source type, this is only used by the deferred surface configuration objects. 736 private final int mSurfaceType; 737 738 // The size, format, and dataspace of the surface when OutputConfiguration is created. 739 private final Size mConfiguredSize; 740 private final int mConfiguredFormat; 741 private final int mConfiguredDataspace; 742 // Surface generation ID to distinguish changes to Surface native internals 743 private final int mConfiguredGenerationId; 744 // Flag indicating if this config has deferred surface. 745 private final boolean mIsDeferredConfig; 746 // Flag indicating if this config has shared surfaces 747 private boolean mIsShared; 748 // The physical camera id that this output configuration is for. 749 private String mPhysicalCameraId; 750 } 751