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