1 /* 2 * Copyright (C) 2012 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 package android.hardware.display; 18 19 import static android.view.Display.DEFAULT_DISPLAY; 20 import static android.view.Display.HdrCapabilities.HdrType; 21 22 import android.Manifest; 23 import android.annotation.FloatRange; 24 import android.annotation.IntDef; 25 import android.annotation.IntRange; 26 import android.annotation.LongDef; 27 import android.annotation.NonNull; 28 import android.annotation.Nullable; 29 import android.annotation.RequiresPermission; 30 import android.annotation.SystemApi; 31 import android.annotation.SystemService; 32 import android.annotation.TestApi; 33 import android.app.KeyguardManager; 34 import android.compat.annotation.UnsupportedAppUsage; 35 import android.content.Context; 36 import android.content.res.Resources; 37 import android.graphics.Point; 38 import android.media.projection.MediaProjection; 39 import android.os.Build; 40 import android.os.Handler; 41 import android.os.HandlerExecutor; 42 import android.os.Looper; 43 import android.util.Pair; 44 import android.util.Slog; 45 import android.util.SparseArray; 46 import android.view.Display; 47 import android.view.Surface; 48 49 import java.lang.annotation.Retention; 50 import java.lang.annotation.RetentionPolicy; 51 import java.util.ArrayList; 52 import java.util.List; 53 import java.util.concurrent.Executor; 54 55 56 /** 57 * Manages the properties of attached displays. 58 */ 59 @SystemService(Context.DISPLAY_SERVICE) 60 public final class DisplayManager { 61 private static final String TAG = "DisplayManager"; 62 private static final boolean DEBUG = false; 63 64 private final Context mContext; 65 private final DisplayManagerGlobal mGlobal; 66 67 private final Object mLock = new Object(); 68 private final SparseArray<Display> mDisplays = new SparseArray<Display>(); 69 70 private final ArrayList<Display> mTempDisplays = new ArrayList<Display>(); 71 72 /** 73 * Broadcast receiver that indicates when the Wifi display status changes. 74 * <p> 75 * The status is provided as a {@link WifiDisplayStatus} object in the 76 * {@link #EXTRA_WIFI_DISPLAY_STATUS} extra. 77 * </p><p> 78 * This broadcast is only sent to registered receivers and can only be sent by the system. 79 * </p> 80 * @hide 81 */ 82 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 83 public static final String ACTION_WIFI_DISPLAY_STATUS_CHANGED = 84 "android.hardware.display.action.WIFI_DISPLAY_STATUS_CHANGED"; 85 86 /** 87 * Contains a {@link WifiDisplayStatus} object. 88 * @hide 89 */ 90 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 91 public static final String EXTRA_WIFI_DISPLAY_STATUS = 92 "android.hardware.display.extra.WIFI_DISPLAY_STATUS"; 93 94 /** 95 * Display category: Presentation displays. 96 * <p> 97 * This category can be used to identify secondary displays that are suitable for 98 * use as presentation displays such as external or wireless displays. Applications 99 * may automatically project their content to presentation displays to provide 100 * richer second screen experiences. 101 * </p> 102 * 103 * @see android.app.Presentation 104 * @see Display#FLAG_PRESENTATION 105 * @see #getDisplays(String) 106 */ 107 public static final String DISPLAY_CATEGORY_PRESENTATION = 108 "android.hardware.display.category.PRESENTATION"; 109 110 /** 111 * Display category: All displays, including disabled displays. 112 * <p> 113 * This returns all displays, including currently disabled and inaccessible displays. 114 * 115 * @see #getDisplays(String) 116 * @hide 117 */ 118 public static final String DISPLAY_CATEGORY_ALL_INCLUDING_DISABLED = 119 "android.hardware.display.category.ALL_INCLUDING_DISABLED"; 120 121 /** @hide **/ 122 @IntDef(prefix = "VIRTUAL_DISPLAY_FLAG_", flag = true, value = { 123 VIRTUAL_DISPLAY_FLAG_PUBLIC, 124 VIRTUAL_DISPLAY_FLAG_PRESENTATION, 125 VIRTUAL_DISPLAY_FLAG_SECURE, 126 VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY, 127 VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR, 128 VIRTUAL_DISPLAY_FLAG_CAN_SHOW_WITH_INSECURE_KEYGUARD, 129 VIRTUAL_DISPLAY_FLAG_SUPPORTS_TOUCH, 130 VIRTUAL_DISPLAY_FLAG_ROTATES_WITH_CONTENT, 131 VIRTUAL_DISPLAY_FLAG_DESTROY_CONTENT_ON_REMOVAL, 132 VIRTUAL_DISPLAY_FLAG_SHOULD_SHOW_SYSTEM_DECORATIONS, 133 VIRTUAL_DISPLAY_FLAG_TRUSTED, 134 VIRTUAL_DISPLAY_FLAG_OWN_DISPLAY_GROUP, 135 VIRTUAL_DISPLAY_FLAG_ALWAYS_UNLOCKED, 136 VIRTUAL_DISPLAY_FLAG_TOUCH_FEEDBACK_DISABLED 137 }) 138 @Retention(RetentionPolicy.SOURCE) 139 public @interface VirtualDisplayFlag {} 140 141 /** 142 * Virtual display flag: Create a public display. 143 * 144 * <h3>Public virtual displays</h3> 145 * <p> 146 * When this flag is set, the virtual display is public. 147 * </p><p> 148 * A public virtual display behaves just like most any other display that is connected 149 * to the system such as an external or wireless display. Applications can open 150 * windows on the display and the system may mirror the contents of other displays 151 * onto it. 152 * </p><p> 153 * Creating a public virtual display that isn't restricted to own-content only implicitly 154 * creates an auto-mirroring display. See {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR} for 155 * restrictions on who is allowed to create an auto-mirroring display. 156 * </p> 157 * 158 * <h3>Private virtual displays</h3> 159 * <p> 160 * When this flag is not set, the virtual display is private as defined by the 161 * {@link Display#FLAG_PRIVATE} display flag. 162 * </p> 163 * 164 * <p> 165 * A private virtual display belongs to the application that created it. Only the a owner of a 166 * private virtual display and the apps that are already on that display are allowed to place 167 * windows upon it. The private virtual display also does not participate in display mirroring: 168 * it will neither receive mirrored content from another display nor allow its own content to be 169 * mirrored elsewhere. More precisely, the only processes that are allowed to enumerate or 170 * interact with the private display are those that have the same UID as the application that 171 * originally created the private virtual display or as the activities that are already on that 172 * display. 173 * </p> 174 * 175 * @see #createVirtualDisplay 176 * @see #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY 177 * @see #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR 178 */ 179 public static final int VIRTUAL_DISPLAY_FLAG_PUBLIC = 1 << 0; 180 181 /** 182 * Virtual display flag: Create a presentation display. 183 * 184 * <h3>Presentation virtual displays</h3> 185 * <p> 186 * When this flag is set, the virtual display is registered as a presentation 187 * display in the {@link #DISPLAY_CATEGORY_PRESENTATION presentation display category}. 188 * Applications may automatically project their content to presentation displays 189 * to provide richer second screen experiences. 190 * </p> 191 * 192 * <h3>Non-presentation virtual displays</h3> 193 * <p> 194 * When this flag is not set, the virtual display is not registered as a presentation 195 * display. Applications can still project their content on the display but they 196 * will typically not do so automatically. This option is appropriate for 197 * more special-purpose displays. 198 * </p> 199 * 200 * @see android.app.Presentation 201 * @see #createVirtualDisplay 202 * @see #DISPLAY_CATEGORY_PRESENTATION 203 * @see Display#FLAG_PRESENTATION 204 */ 205 public static final int VIRTUAL_DISPLAY_FLAG_PRESENTATION = 1 << 1; 206 207 /** 208 * Virtual display flag: Create a secure display. 209 * 210 * <h3>Secure virtual displays</h3> 211 * <p> 212 * When this flag is set, the virtual display is considered secure as defined 213 * by the {@link Display#FLAG_SECURE} display flag. The caller promises to take 214 * reasonable measures, such as over-the-air encryption, to prevent the contents 215 * of the display from being intercepted or recorded on a persistent medium. 216 * </p><p> 217 * Creating a secure virtual display requires the CAPTURE_SECURE_VIDEO_OUTPUT permission. 218 * This permission is reserved for use by system components and is not available to 219 * third-party applications. 220 * </p> 221 * 222 * <h3>Non-secure virtual displays</h3> 223 * <p> 224 * When this flag is not set, the virtual display is considered unsecure. 225 * The content of secure windows will be blanked if shown on this display. 226 * </p> 227 * 228 * @see Display#FLAG_SECURE 229 * @see #createVirtualDisplay 230 */ 231 public static final int VIRTUAL_DISPLAY_FLAG_SECURE = 1 << 2; 232 233 /** 234 * Virtual display flag: Only show this display's own content; do not mirror 235 * the content of another display. 236 * 237 * <p> 238 * This flag is used in conjunction with {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}. 239 * Ordinarily public virtual displays will automatically mirror the content of the 240 * default display if they have no windows of their own. When this flag is 241 * specified, the virtual display will only ever show its own content and 242 * will be blanked instead if it has no windows. 243 * </p> 244 * 245 * <p> 246 * This flag is mutually exclusive with {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR}. If both 247 * flags are specified then the own-content only behavior will be applied. 248 * </p> 249 * 250 * <p> 251 * This behavior of this flag is implied whenever neither {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC} 252 * nor {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR} have been set. This flag is only required to 253 * override the default behavior when creating a public display. 254 * </p> 255 * 256 * @see #createVirtualDisplay 257 */ 258 public static final int VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY = 1 << 3; 259 260 261 /** 262 * Virtual display flag: Allows content to be mirrored on private displays when no content is 263 * being shown. 264 * 265 * <p> 266 * This flag is mutually exclusive with {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}. 267 * If both flags are specified then the own-content only behavior will be applied. 268 * </p> 269 * 270 * <p> 271 * The behavior of this flag is implied whenever {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC} is set 272 * and {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY} has not been set. This flag is only 273 * required to override the default behavior when creating a private display. 274 * </p> 275 * 276 * <p> 277 * Creating an auto-mirroing virtual display requires the CAPTURE_VIDEO_OUTPUT 278 * or CAPTURE_SECURE_VIDEO_OUTPUT permission. 279 * These permissions are reserved for use by system components and are not available to 280 * third-party applications. 281 * 282 * Alternatively, an appropriate {@link MediaProjection} may be used to create an 283 * auto-mirroring virtual display. 284 * </p> 285 * 286 * @see #createVirtualDisplay 287 */ 288 public static final int VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR = 1 << 4; 289 290 /** 291 * Virtual display flag: Allows content to be displayed on private virtual displays when 292 * keyguard is shown but is insecure. 293 * 294 * <p> 295 * This might be used in a case when the content of a virtual display is captured and sent to an 296 * external hardware display that is not visible to the system directly. This flag will allow 297 * the continued display of content while other displays will be covered by a keyguard which 298 * doesn't require providing credentials to unlock. This means that there is either no password 299 * or other authentication method set, or the device is in a trusted state - 300 * {@link android.service.trust.TrustAgentService} has available and active trust agent. 301 * </p><p> 302 * This flag can only be applied to private displays as defined by the 303 * {@link Display#FLAG_PRIVATE} display flag. It is mutually exclusive with 304 * {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}. If both flags are specified then this flag's behavior 305 * will not be applied. 306 * </p> 307 * 308 * @see #createVirtualDisplay 309 * @see KeyguardManager#isDeviceSecure() 310 * @see KeyguardManager#isDeviceLocked() 311 * @hide 312 */ 313 // TODO (b/114338689): Remove the flag and use IWindowManager#shouldShowWithInsecureKeyguard 314 // TODO: Update name and documentation and un-hide the flag. Don't change the value before that. 315 public static final int VIRTUAL_DISPLAY_FLAG_CAN_SHOW_WITH_INSECURE_KEYGUARD = 1 << 5; 316 317 /** 318 * Virtual display flag: Specifies that the virtual display can be associated with a 319 * touchpad device that matches its uniqueId. 320 * 321 * @see #createVirtualDisplay 322 * @hide 323 */ 324 public static final int VIRTUAL_DISPLAY_FLAG_SUPPORTS_TOUCH = 1 << 6; 325 326 /** 327 * Virtual display flag: Indicates that the orientation of this display device is coupled to 328 * the rotation of its associated logical display. 329 * 330 * @see #createVirtualDisplay 331 * @hide 332 */ 333 public static final int VIRTUAL_DISPLAY_FLAG_ROTATES_WITH_CONTENT = 1 << 7; 334 335 /** 336 * Virtual display flag: Indicates that the contents will be destroyed once 337 * the display is removed. 338 * 339 * Public virtual displays without this flag will move their content to main display 340 * stack once they're removed. Private vistual displays will always destroy their 341 * content on removal even without this flag. 342 * 343 * @see #createVirtualDisplay 344 * @hide 345 */ 346 // TODO (b/114338689): Remove the flag and use WindowManager#REMOVE_CONTENT_MODE_DESTROY 347 public static final int VIRTUAL_DISPLAY_FLAG_DESTROY_CONTENT_ON_REMOVAL = 1 << 8; 348 349 /** 350 * Virtual display flag: Indicates that the display should support system decorations. Virtual 351 * displays without this flag shouldn't show home, IME or any other system decorations. 352 * <p>This flag doesn't work without {@link #VIRTUAL_DISPLAY_FLAG_TRUSTED}</p> 353 * 354 * @see #createVirtualDisplay 355 * @see #VIRTUAL_DISPLAY_FLAG_TRUSTED 356 * @hide 357 */ 358 // TODO (b/114338689): Remove the flag and use IWindowManager#setShouldShowSystemDecors 359 @TestApi 360 public static final int VIRTUAL_DISPLAY_FLAG_SHOULD_SHOW_SYSTEM_DECORATIONS = 1 << 9; 361 362 /** 363 * Virtual display flags: Indicates that the display is trusted to show system decorations and 364 * receive inputs without users' touch. 365 * 366 * @see #createVirtualDisplay 367 * @see #VIRTUAL_DISPLAY_FLAG_SHOULD_SHOW_SYSTEM_DECORATIONS 368 * @hide 369 */ 370 @SystemApi 371 public static final int VIRTUAL_DISPLAY_FLAG_TRUSTED = 1 << 10; 372 373 /** 374 * Virtual display flags: Indicates that the display should not be a part of the default 375 * DisplayGroup and instead be part of a new DisplayGroup. 376 * 377 * @see #createVirtualDisplay 378 * @hide 379 */ 380 public static final int VIRTUAL_DISPLAY_FLAG_OWN_DISPLAY_GROUP = 1 << 11; 381 382 /** 383 * Virtual display flags: Indicates that the virtual display should always be unlocked and not 384 * have keyguard displayed on it. Only valid for virtual displays that aren't in the default 385 * display group. 386 * 387 * @see #createVirtualDisplay 388 * @see #VIRTUAL_DISPLAY_FLAG_OWN_DISPLAY_GROUP 389 * @hide 390 */ 391 public static final int VIRTUAL_DISPLAY_FLAG_ALWAYS_UNLOCKED = 1 << 12; 392 393 /** 394 * Virtual display flags: Indicates that the display should not play sound effects or perform 395 * haptic feedback when the user touches the screen. 396 * 397 * @see #createVirtualDisplay 398 * @hide 399 */ 400 public static final int VIRTUAL_DISPLAY_FLAG_TOUCH_FEEDBACK_DISABLED = 1 << 13; 401 402 /** @hide */ 403 @IntDef(prefix = {"MATCH_CONTENT_FRAMERATE_"}, value = { 404 MATCH_CONTENT_FRAMERATE_UNKNOWN, 405 MATCH_CONTENT_FRAMERATE_NEVER, 406 MATCH_CONTENT_FRAMERATE_SEAMLESSS_ONLY, 407 MATCH_CONTENT_FRAMERATE_ALWAYS, 408 }) 409 @Retention(RetentionPolicy.SOURCE) 410 public @interface MatchContentFrameRateType {} 411 412 /** 413 * Match content frame rate user preference is unknown. 414 */ 415 public static final int MATCH_CONTENT_FRAMERATE_UNKNOWN = -1; 416 417 /** 418 * No mode switching is allowed. 419 */ 420 public static final int MATCH_CONTENT_FRAMERATE_NEVER = 0; 421 422 /** 423 * Only refresh rate switches without visual interruptions are allowed. 424 */ 425 public static final int MATCH_CONTENT_FRAMERATE_SEAMLESSS_ONLY = 1; 426 427 /** 428 * Refresh rate switches between all refresh rates are allowed even if they have visual 429 * interruptions for the user. 430 */ 431 public static final int MATCH_CONTENT_FRAMERATE_ALWAYS = 2; 432 433 /** @hide */ 434 @IntDef(prefix = {"SWITCHING_TYPE_"}, value = { 435 SWITCHING_TYPE_NONE, 436 SWITCHING_TYPE_WITHIN_GROUPS, 437 SWITCHING_TYPE_ACROSS_AND_WITHIN_GROUPS, 438 }) 439 @Retention(RetentionPolicy.SOURCE) 440 public @interface SwitchingType {} 441 442 /** 443 * No mode switching will happen. 444 * @hide 445 */ 446 @TestApi 447 public static final int SWITCHING_TYPE_NONE = 0; 448 449 /** 450 * Allow only refresh rate switching between modes in the same configuration group. This way 451 * only switches without visual interruptions for the user will be allowed. 452 * @hide 453 */ 454 @TestApi 455 public static final int SWITCHING_TYPE_WITHIN_GROUPS = 1; 456 457 /** 458 * Allow refresh rate switching between all refresh rates even if the switch with have visual 459 * interruptions for the user. 460 * @hide 461 */ 462 @TestApi 463 public static final int SWITCHING_TYPE_ACROSS_AND_WITHIN_GROUPS = 2; 464 465 /** 466 * @hide 467 */ 468 @LongDef(flag = true, prefix = {"EVENT_FLAG_"}, value = { 469 EVENT_FLAG_DISPLAY_ADDED, 470 EVENT_FLAG_DISPLAY_CHANGED, 471 EVENT_FLAG_DISPLAY_REMOVED, 472 EVENT_FLAG_DISPLAY_BRIGHTNESS 473 }) 474 @Retention(RetentionPolicy.SOURCE) 475 public @interface EventsMask {} 476 477 /** 478 * Event type for when a new display is added. 479 * 480 * @see #registerDisplayListener(DisplayListener, Handler, long) 481 * 482 * @hide 483 */ 484 public static final long EVENT_FLAG_DISPLAY_ADDED = 1L << 0; 485 486 /** 487 * Event type for when a display is removed. 488 * 489 * @see #registerDisplayListener(DisplayListener, Handler, long) 490 * 491 * @hide 492 */ 493 public static final long EVENT_FLAG_DISPLAY_REMOVED = 1L << 1; 494 495 /** 496 * Event type for when a display is changed. 497 * 498 * @see #registerDisplayListener(DisplayListener, Handler, long) 499 * 500 * @hide 501 */ 502 public static final long EVENT_FLAG_DISPLAY_CHANGED = 1L << 2; 503 504 /** 505 * Event flag to register for a display's brightness changes. This notification is sent 506 * through the {@link DisplayListener#onDisplayChanged} callback method. New brightness 507 * values can be retrieved via {@link android.view.Display#getBrightnessInfo()}. 508 * 509 * @see #registerDisplayListener(DisplayListener, Handler, long) 510 * 511 * @hide 512 */ 513 public static final long EVENT_FLAG_DISPLAY_BRIGHTNESS = 1L << 3; 514 515 /** @hide */ DisplayManager(Context context)516 public DisplayManager(Context context) { 517 mContext = context; 518 mGlobal = DisplayManagerGlobal.getInstance(); 519 } 520 521 /** 522 * Gets information about a logical display. 523 * 524 * The display metrics may be adjusted to provide compatibility 525 * for legacy applications. 526 * 527 * @param displayId The logical display id. 528 * @return The display object, or null if there is no valid display with the given id. 529 */ getDisplay(int displayId)530 public Display getDisplay(int displayId) { 531 synchronized (mLock) { 532 return getOrCreateDisplayLocked(displayId, false /*assumeValid*/); 533 } 534 } 535 536 /** 537 * Gets all currently valid logical displays. 538 * 539 * @return An array containing all displays. 540 */ getDisplays()541 public Display[] getDisplays() { 542 return getDisplays(null); 543 } 544 545 /** 546 * Gets all currently valid logical displays of the specified category. 547 * <p> 548 * When there are multiple displays in a category the returned displays are sorted 549 * of preference. For example, if the requested category is 550 * {@link #DISPLAY_CATEGORY_PRESENTATION} and there are multiple presentation displays 551 * then the displays are sorted so that the first display in the returned array 552 * is the most preferred presentation display. The application may simply 553 * use the first display or allow the user to choose. 554 * </p> 555 * 556 * @param category The requested display category or null to return all displays. 557 * @return An array containing all displays sorted by order of preference. 558 * 559 * @see #DISPLAY_CATEGORY_PRESENTATION 560 */ getDisplays(String category)561 public Display[] getDisplays(String category) { 562 boolean includeDisabled = (category != null 563 && category.equals(DISPLAY_CATEGORY_ALL_INCLUDING_DISABLED)); 564 final int[] displayIds = mGlobal.getDisplayIds(includeDisabled); 565 synchronized (mLock) { 566 try { 567 if (DISPLAY_CATEGORY_PRESENTATION.equals(category)) { 568 addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_WIFI); 569 addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_EXTERNAL); 570 addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_OVERLAY); 571 addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_VIRTUAL); 572 addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_INTERNAL); 573 } else if (category == null 574 || DISPLAY_CATEGORY_ALL_INCLUDING_DISABLED.equals(category)) { 575 addAllDisplaysLocked(mTempDisplays, displayIds); 576 } 577 return mTempDisplays.toArray(new Display[mTempDisplays.size()]); 578 } finally { 579 mTempDisplays.clear(); 580 } 581 } 582 } 583 addAllDisplaysLocked(ArrayList<Display> displays, int[] displayIds)584 private void addAllDisplaysLocked(ArrayList<Display> displays, int[] displayIds) { 585 for (int i = 0; i < displayIds.length; i++) { 586 Display display = getOrCreateDisplayLocked(displayIds[i], true /*assumeValid*/); 587 if (display != null) { 588 displays.add(display); 589 } 590 } 591 } 592 addPresentationDisplaysLocked( ArrayList<Display> displays, int[] displayIds, int matchType)593 private void addPresentationDisplaysLocked( 594 ArrayList<Display> displays, int[] displayIds, int matchType) { 595 for (int i = 0; i < displayIds.length; i++) { 596 if (displayIds[i] == DEFAULT_DISPLAY) { 597 continue; 598 } 599 Display display = getOrCreateDisplayLocked(displayIds[i], true /*assumeValid*/); 600 if (display != null 601 && (display.getFlags() & Display.FLAG_PRESENTATION) != 0 602 && display.getType() == matchType) { 603 displays.add(display); 604 } 605 } 606 } 607 getOrCreateDisplayLocked(int displayId, boolean assumeValid)608 private Display getOrCreateDisplayLocked(int displayId, boolean assumeValid) { 609 Display display = mDisplays.get(displayId); 610 if (display == null) { 611 // TODO: We cannot currently provide any override configurations for metrics on displays 612 // other than the display the context is associated with. 613 final Resources resources = mContext.getDisplayId() == displayId 614 ? mContext.getResources() : null; 615 616 display = mGlobal.getCompatibleDisplay(displayId, resources); 617 if (display != null) { 618 mDisplays.put(displayId, display); 619 } 620 } else if (!assumeValid && !display.isValid()) { 621 display = null; 622 } 623 return display; 624 } 625 626 /** 627 * Registers a display listener to receive notifications about when 628 * displays are added, removed or changed. 629 * 630 * @param listener The listener to register. 631 * @param handler The handler on which the listener should be invoked, or null 632 * if the listener should be invoked on the calling thread's looper. 633 * 634 * @see #unregisterDisplayListener 635 */ registerDisplayListener(DisplayListener listener, Handler handler)636 public void registerDisplayListener(DisplayListener listener, Handler handler) { 637 registerDisplayListener(listener, handler, EVENT_FLAG_DISPLAY_ADDED 638 | EVENT_FLAG_DISPLAY_CHANGED | EVENT_FLAG_DISPLAY_REMOVED); 639 } 640 641 /** 642 * Registers a display listener to receive notifications about given display event types. 643 * 644 * @param listener The listener to register. 645 * @param handler The handler on which the listener should be invoked, or null 646 * if the listener should be invoked on the calling thread's looper. 647 * @param eventsMask A bitmask of the event types for which this listener is subscribed. 648 * 649 * @see #EVENT_FLAG_DISPLAY_ADDED 650 * @see #EVENT_FLAG_DISPLAY_CHANGED 651 * @see #EVENT_FLAG_DISPLAY_REMOVED 652 * @see #EVENT_FLAG_DISPLAY_BRIGHTNESS 653 * @see #registerDisplayListener(DisplayListener, Handler) 654 * @see #unregisterDisplayListener 655 * 656 * @hide 657 */ registerDisplayListener(@onNull DisplayListener listener, @Nullable Handler handler, @EventsMask long eventsMask)658 public void registerDisplayListener(@NonNull DisplayListener listener, 659 @Nullable Handler handler, @EventsMask long eventsMask) { 660 mGlobal.registerDisplayListener(listener, handler, eventsMask); 661 } 662 663 /** 664 * Unregisters a display listener. 665 * 666 * @param listener The listener to unregister. 667 * 668 * @see #registerDisplayListener 669 */ unregisterDisplayListener(DisplayListener listener)670 public void unregisterDisplayListener(DisplayListener listener) { 671 mGlobal.unregisterDisplayListener(listener); 672 } 673 674 /** 675 * Starts scanning for available Wifi displays. 676 * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast. 677 * <p> 678 * Calls to this method nest and must be matched by an equal number of calls to 679 * {@link #stopWifiDisplayScan()}. 680 * </p><p> 681 * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. 682 * </p> 683 * 684 * @hide 685 */ 686 @UnsupportedAppUsage startWifiDisplayScan()687 public void startWifiDisplayScan() { 688 mGlobal.startWifiDisplayScan(); 689 } 690 691 /** 692 * Stops scanning for available Wifi displays. 693 * <p> 694 * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. 695 * </p> 696 * 697 * @hide 698 */ 699 @UnsupportedAppUsage stopWifiDisplayScan()700 public void stopWifiDisplayScan() { 701 mGlobal.stopWifiDisplayScan(); 702 } 703 704 /** 705 * Connects to a Wifi display. 706 * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast. 707 * <p> 708 * Automatically remembers the display after a successful connection, if not 709 * already remembered. 710 * </p><p> 711 * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. 712 * </p> 713 * 714 * @param deviceAddress The MAC address of the device to which we should connect. 715 * @hide 716 */ 717 @UnsupportedAppUsage connectWifiDisplay(String deviceAddress)718 public void connectWifiDisplay(String deviceAddress) { 719 mGlobal.connectWifiDisplay(deviceAddress); 720 } 721 722 /** @hide */ 723 @UnsupportedAppUsage pauseWifiDisplay()724 public void pauseWifiDisplay() { 725 mGlobal.pauseWifiDisplay(); 726 } 727 728 /** @hide */ 729 @UnsupportedAppUsage resumeWifiDisplay()730 public void resumeWifiDisplay() { 731 mGlobal.resumeWifiDisplay(); 732 } 733 734 /** 735 * Disconnects from the current Wifi display. 736 * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast. 737 * @hide 738 */ 739 @UnsupportedAppUsage disconnectWifiDisplay()740 public void disconnectWifiDisplay() { 741 mGlobal.disconnectWifiDisplay(); 742 } 743 744 /** 745 * Renames a Wifi display. 746 * <p> 747 * The display must already be remembered for this call to succeed. In other words, 748 * we must already have successfully connected to the display at least once and then 749 * not forgotten it. 750 * </p><p> 751 * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. 752 * </p> 753 * 754 * @param deviceAddress The MAC address of the device to rename. 755 * @param alias The alias name by which to remember the device, or null 756 * or empty if no alias should be used. 757 * @hide 758 */ 759 @UnsupportedAppUsage renameWifiDisplay(String deviceAddress, String alias)760 public void renameWifiDisplay(String deviceAddress, String alias) { 761 mGlobal.renameWifiDisplay(deviceAddress, alias); 762 } 763 764 /** 765 * Forgets a previously remembered Wifi display. 766 * <p> 767 * Automatically disconnects from the display if currently connected to it. 768 * </p><p> 769 * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. 770 * </p> 771 * 772 * @param deviceAddress The MAC address of the device to forget. 773 * @hide 774 */ 775 @UnsupportedAppUsage forgetWifiDisplay(String deviceAddress)776 public void forgetWifiDisplay(String deviceAddress) { 777 mGlobal.forgetWifiDisplay(deviceAddress); 778 } 779 780 /** 781 * Gets the current Wifi display status. 782 * Watch for changes in the status by registering a broadcast receiver for 783 * {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED}. 784 * 785 * @return The current Wifi display status. 786 * @hide 787 */ 788 @UnsupportedAppUsage getWifiDisplayStatus()789 public WifiDisplayStatus getWifiDisplayStatus() { 790 return mGlobal.getWifiDisplayStatus(); 791 } 792 793 /** 794 * Set the level of color saturation to apply to the display. 795 * @param level The amount of saturation to apply, between 0 and 1 inclusive. 796 * 0 produces a grayscale image, 1 is normal. 797 * 798 * @hide 799 * @deprecated use {@link ColorDisplayManager#setSaturationLevel(int)} instead. The level passed 800 * as a parameter here will be rounded to the nearest hundredth. 801 */ 802 @SystemApi 803 @RequiresPermission(Manifest.permission.CONTROL_DISPLAY_SATURATION) setSaturationLevel(float level)804 public void setSaturationLevel(float level) { 805 if (level < 0f || level > 1f) { 806 throw new IllegalArgumentException("Saturation level must be between 0 and 1"); 807 } 808 final ColorDisplayManager cdm = mContext.getSystemService(ColorDisplayManager.class); 809 cdm.setSaturationLevel(Math.round(level * 100f)); 810 } 811 812 /** 813 * Sets the HDR types that have been disabled by user. 814 * @param userDisabledTypes the HDR types to disable. 815 * @hide 816 */ 817 @TestApi 818 @RequiresPermission(Manifest.permission.WRITE_SECURE_SETTINGS) setUserDisabledHdrTypes(@onNull @drType int[] userDisabledTypes)819 public void setUserDisabledHdrTypes(@NonNull @HdrType int[] userDisabledTypes) { 820 mGlobal.setUserDisabledHdrTypes(userDisabledTypes); 821 } 822 823 /** 824 * Sets whether or not the user disabled HDR types are returned from 825 * {@link Display#getHdrCapabilities}. 826 * 827 * @param areUserDisabledHdrTypesAllowed If true, the user-disabled types 828 * are ignored and returned, if the display supports them. If false, the 829 * user-disabled types are taken into consideration and are never returned, 830 * even if the display supports them. 831 * @hide 832 */ 833 @TestApi 834 @RequiresPermission(Manifest.permission.WRITE_SECURE_SETTINGS) setAreUserDisabledHdrTypesAllowed(boolean areUserDisabledHdrTypesAllowed)835 public void setAreUserDisabledHdrTypesAllowed(boolean areUserDisabledHdrTypesAllowed) { 836 mGlobal.setAreUserDisabledHdrTypesAllowed(areUserDisabledHdrTypesAllowed); 837 } 838 839 /** 840 * Returns whether or not the user-disabled HDR types are returned from 841 * {@link Display#getHdrCapabilities}. 842 * 843 * @hide 844 */ 845 @TestApi areUserDisabledHdrTypesAllowed()846 public boolean areUserDisabledHdrTypesAllowed() { 847 return mGlobal.areUserDisabledHdrTypesAllowed(); 848 } 849 850 /** 851 * Returns the HDR formats disabled by the user. 852 * 853 * @hide 854 */ 855 @TestApi getUserDisabledHdrTypes()856 public @NonNull int[] getUserDisabledHdrTypes() { 857 return mGlobal.getUserDisabledHdrTypes(); 858 } 859 860 861 /** 862 * Creates a virtual display. 863 * 864 * @see #createVirtualDisplay(String, int, int, int, Surface, int, 865 * VirtualDisplay.Callback, Handler) 866 */ createVirtualDisplay(@onNull String name, @IntRange(from = 1) int width, @IntRange(from = 1) int height, @IntRange(from = 1) int densityDpi, @Nullable Surface surface, @VirtualDisplayFlag int flags)867 public VirtualDisplay createVirtualDisplay(@NonNull String name, 868 @IntRange(from = 1) int width, 869 @IntRange(from = 1) int height, 870 @IntRange(from = 1) int densityDpi, 871 @Nullable Surface surface, 872 @VirtualDisplayFlag int flags) { 873 return createVirtualDisplay(name, width, height, densityDpi, surface, flags, null, null); 874 } 875 876 /** 877 * Creates a virtual display. 878 * <p> 879 * The content of a virtual display is rendered to a {@link Surface} provided 880 * by the application. 881 * </p><p> 882 * The virtual display should be {@link VirtualDisplay#release released} 883 * when no longer needed. Because a virtual display renders to a surface 884 * provided by the application, it will be released automatically when the 885 * process terminates and all remaining windows on it will be forcibly removed. 886 * </p><p> 887 * The behavior of the virtual display depends on the flags that are provided 888 * to this method. By default, virtual displays are created to be private, 889 * non-presentation and unsecure. Permissions may be required to use certain flags. 890 * </p><p> 891 * As of {@link android.os.Build.VERSION_CODES#KITKAT_WATCH}, the surface may 892 * be attached or detached dynamically using {@link VirtualDisplay#setSurface}. 893 * Previously, the surface had to be non-null when {@link #createVirtualDisplay} 894 * was called and could not be changed for the lifetime of the display. 895 * </p><p> 896 * Detaching the surface that backs a virtual display has a similar effect to 897 * turning off the screen. 898 * </p> 899 * 900 * @param name The name of the virtual display, must be non-empty. 901 * @param width The width of the virtual display in pixels, must be greater than 0. 902 * @param height The height of the virtual display in pixels, must be greater than 0. 903 * @param densityDpi The density of the virtual display in dpi, must be greater than 0. 904 * @param surface The surface to which the content of the virtual display should 905 * be rendered, or null if there is none initially. 906 * @param flags A combination of virtual display flags: 907 * {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}, {@link #VIRTUAL_DISPLAY_FLAG_PRESENTATION}, 908 * {@link #VIRTUAL_DISPLAY_FLAG_SECURE}, {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}, 909 * or {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR}. 910 * @param callback Callback to call when the state of the {@link VirtualDisplay} changes 911 * @param handler The handler on which the listener should be invoked, or null 912 * if the listener should be invoked on the calling thread's looper. 913 * @return The newly created virtual display, or null if the application could 914 * not create the virtual display. 915 * 916 * @throws SecurityException if the caller does not have permission to create 917 * a virtual display with the specified flags. 918 */ createVirtualDisplay(@onNull String name, @IntRange(from = 1) int width, @IntRange(from = 1) int height, @IntRange(from = 1) int densityDpi, @Nullable Surface surface, @VirtualDisplayFlag int flags, @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler)919 public VirtualDisplay createVirtualDisplay(@NonNull String name, 920 @IntRange(from = 1) int width, 921 @IntRange(from = 1) int height, 922 @IntRange(from = 1) int densityDpi, 923 @Nullable Surface surface, 924 @VirtualDisplayFlag int flags, 925 @Nullable VirtualDisplay.Callback callback, 926 @Nullable Handler handler) { 927 final VirtualDisplayConfig.Builder builder = new VirtualDisplayConfig.Builder(name, width, 928 height, densityDpi); 929 builder.setFlags(flags); 930 if (surface != null) { 931 builder.setSurface(surface); 932 } 933 return createVirtualDisplay(null /* projection */, builder.build(), callback, handler, 934 null /* windowContext */); 935 } 936 937 // TODO : Remove this hidden API after remove all callers. (Refer to MultiDisplayService) 938 /** @hide */ createVirtualDisplay( @ullable MediaProjection projection, @NonNull String name, @IntRange(from = 1) int width, @IntRange(from = 1) int height, @IntRange(from = 1) int densityDpi, @Nullable Surface surface, @VirtualDisplayFlag int flags, @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler, @Nullable String uniqueId)939 public VirtualDisplay createVirtualDisplay( 940 @Nullable MediaProjection projection, 941 @NonNull String name, 942 @IntRange(from = 1) int width, 943 @IntRange(from = 1) int height, 944 @IntRange(from = 1) int densityDpi, 945 @Nullable Surface surface, 946 @VirtualDisplayFlag int flags, 947 @Nullable VirtualDisplay.Callback callback, 948 @Nullable Handler handler, 949 @Nullable String uniqueId) { 950 final VirtualDisplayConfig.Builder builder = new VirtualDisplayConfig.Builder(name, width, 951 height, densityDpi); 952 builder.setFlags(flags); 953 if (uniqueId != null) { 954 builder.setUniqueId(uniqueId); 955 } 956 if (surface != null) { 957 builder.setSurface(surface); 958 } 959 return createVirtualDisplay(projection, builder.build(), callback, handler, 960 null /* windowContext */); 961 } 962 963 /** @hide */ createVirtualDisplay(@ullable MediaProjection projection, @NonNull VirtualDisplayConfig virtualDisplayConfig, @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler, @Nullable Context windowContext)964 public VirtualDisplay createVirtualDisplay(@Nullable MediaProjection projection, 965 @NonNull VirtualDisplayConfig virtualDisplayConfig, 966 @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler, 967 @Nullable Context windowContext) { 968 Executor executor = null; 969 // If callback is null, the executor will not be used. Avoid creating the handler and the 970 // handler executor. 971 if (callback != null) { 972 executor = new HandlerExecutor( 973 Handler.createAsync(handler != null ? handler.getLooper() : Looper.myLooper())); 974 } 975 return mGlobal.createVirtualDisplay(mContext, projection, virtualDisplayConfig, callback, 976 executor, windowContext); 977 } 978 979 /** 980 * Gets the stable device display size, in pixels. 981 * 982 * This should really only be used for things like server-side filtering of available 983 * applications. Most applications don't need the level of stability guaranteed by this and 984 * should instead query either the size of the display they're currently running on or the 985 * size of the default display. 986 * @hide 987 */ 988 @SystemApi getStableDisplaySize()989 public Point getStableDisplaySize() { 990 return mGlobal.getStableDisplaySize(); 991 } 992 993 /** 994 * Fetch {@link BrightnessChangeEvent}s. 995 * @hide until we make it a system api. 996 */ 997 @SystemApi 998 @RequiresPermission(Manifest.permission.BRIGHTNESS_SLIDER_USAGE) getBrightnessEvents()999 public List<BrightnessChangeEvent> getBrightnessEvents() { 1000 return mGlobal.getBrightnessEvents(mContext.getOpPackageName()); 1001 } 1002 1003 /** 1004 * Fetch {@link AmbientBrightnessDayStats}s. 1005 * 1006 * @hide until we make it a system api 1007 */ 1008 @SystemApi 1009 @RequiresPermission(Manifest.permission.ACCESS_AMBIENT_LIGHT_STATS) getAmbientBrightnessStats()1010 public List<AmbientBrightnessDayStats> getAmbientBrightnessStats() { 1011 return mGlobal.getAmbientBrightnessStats(); 1012 } 1013 1014 /** 1015 * Sets the global display brightness configuration. 1016 * 1017 * @hide 1018 */ 1019 @SystemApi 1020 @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS) setBrightnessConfiguration(BrightnessConfiguration c)1021 public void setBrightnessConfiguration(BrightnessConfiguration c) { 1022 setBrightnessConfigurationForUser(c, mContext.getUserId(), mContext.getPackageName()); 1023 } 1024 1025 /** 1026 * Sets the brightness configuration for the specified display. 1027 * If the specified display doesn't exist, then this will return and do nothing. 1028 * 1029 * @hide 1030 */ 1031 @SystemApi 1032 @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS) setBrightnessConfigurationForDisplay(@onNull BrightnessConfiguration c, @NonNull String uniqueId)1033 public void setBrightnessConfigurationForDisplay(@NonNull BrightnessConfiguration c, 1034 @NonNull String uniqueId) { 1035 mGlobal.setBrightnessConfigurationForDisplay(c, uniqueId, mContext.getUserId(), 1036 mContext.getPackageName()); 1037 } 1038 1039 /** 1040 * Gets the brightness configuration for the specified display and default user. 1041 * Returns the default configuration if unset or display is invalid. 1042 * 1043 * @hide 1044 */ 1045 @Nullable 1046 @SystemApi 1047 @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS) getBrightnessConfigurationForDisplay( @onNull String uniqueId)1048 public BrightnessConfiguration getBrightnessConfigurationForDisplay( 1049 @NonNull String uniqueId) { 1050 return mGlobal.getBrightnessConfigurationForDisplay(uniqueId, mContext.getUserId()); 1051 } 1052 1053 /** 1054 * Sets the global display brightness configuration for a specific user. 1055 * 1056 * Note this requires the INTERACT_ACROSS_USERS permission if setting the configuration for a 1057 * user other than the one you're currently running as. 1058 * 1059 * @hide 1060 */ setBrightnessConfigurationForUser(BrightnessConfiguration c, int userId, String packageName)1061 public void setBrightnessConfigurationForUser(BrightnessConfiguration c, int userId, 1062 String packageName) { 1063 mGlobal.setBrightnessConfigurationForUser(c, userId, packageName); 1064 } 1065 1066 /** 1067 * Gets the global display brightness configuration or the default curve if one hasn't been set. 1068 * 1069 * @hide 1070 */ 1071 @SystemApi 1072 @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS) getBrightnessConfiguration()1073 public BrightnessConfiguration getBrightnessConfiguration() { 1074 return getBrightnessConfigurationForUser(mContext.getUserId()); 1075 } 1076 1077 /** 1078 * Gets the global display brightness configuration or the default curve if one hasn't been set 1079 * for a specific user. 1080 * 1081 * Note this requires the INTERACT_ACROSS_USERS permission if getting the configuration for a 1082 * user other than the one you're currently running as. 1083 * 1084 * @hide 1085 */ getBrightnessConfigurationForUser(int userId)1086 public BrightnessConfiguration getBrightnessConfigurationForUser(int userId) { 1087 return mGlobal.getBrightnessConfigurationForUser(userId); 1088 } 1089 1090 /** 1091 * Gets the default global display brightness configuration or null one hasn't 1092 * been configured. 1093 * 1094 * @hide 1095 */ 1096 @SystemApi 1097 @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS) 1098 @Nullable getDefaultBrightnessConfiguration()1099 public BrightnessConfiguration getDefaultBrightnessConfiguration() { 1100 return mGlobal.getDefaultBrightnessConfiguration(); 1101 } 1102 1103 1104 /** 1105 * Gets the last requested minimal post processing setting for the display with displayId. 1106 * 1107 * @hide 1108 */ 1109 @TestApi isMinimalPostProcessingRequested(int displayId)1110 public boolean isMinimalPostProcessingRequested(int displayId) { 1111 return mGlobal.isMinimalPostProcessingRequested(displayId); 1112 } 1113 1114 /** 1115 * Temporarily sets the brightness of the display. 1116 * <p> 1117 * Requires the {@link android.Manifest.permission#CONTROL_DISPLAY_BRIGHTNESS} permission. 1118 * </p> 1119 * 1120 * @param brightness The brightness value from 0.0f to 1.0f. 1121 * 1122 * @hide Requires signature permission. 1123 */ setTemporaryBrightness(int displayId, float brightness)1124 public void setTemporaryBrightness(int displayId, float brightness) { 1125 mGlobal.setTemporaryBrightness(displayId, brightness); 1126 } 1127 1128 1129 /** 1130 * Sets the brightness of the specified display. 1131 * <p> 1132 * Requires the {@link android.Manifest.permission#CONTROL_DISPLAY_BRIGHTNESS} 1133 * permission. 1134 * </p> 1135 * 1136 * @param displayId the logical display id 1137 * @param brightness The brightness value from 0.0f to 1.0f. 1138 * 1139 * @hide 1140 */ 1141 @RequiresPermission(Manifest.permission.CONTROL_DISPLAY_BRIGHTNESS) setBrightness(int displayId, @FloatRange(from = 0f, to = 1f) float brightness)1142 public void setBrightness(int displayId, @FloatRange(from = 0f, to = 1f) float brightness) { 1143 mGlobal.setBrightness(displayId, brightness); 1144 } 1145 1146 1147 /** 1148 * Gets the brightness of the specified display. 1149 * <p> 1150 * Requires the {@link android.Manifest.permission#CONTROL_DISPLAY_BRIGHTNESS} 1151 * permission. 1152 * </p> 1153 * 1154 * @param displayId The display of which brightness value to get from. 1155 * 1156 * @hide 1157 */ 1158 @RequiresPermission(Manifest.permission.CONTROL_DISPLAY_BRIGHTNESS) 1159 @FloatRange(from = 0f, to = 1f) getBrightness(int displayId)1160 public float getBrightness(int displayId) { 1161 return mGlobal.getBrightness(displayId); 1162 } 1163 1164 1165 /** 1166 * Temporarily sets the auto brightness adjustment factor. 1167 * <p> 1168 * Requires the {@link android.Manifest.permission#CONTROL_DISPLAY_BRIGHTNESS} permission. 1169 * </p> 1170 * 1171 * @param adjustment The adjustment factor from -1.0 to 1.0. 1172 * 1173 * @hide Requires signature permission. 1174 */ setTemporaryAutoBrightnessAdjustment(float adjustment)1175 public void setTemporaryAutoBrightnessAdjustment(float adjustment) { 1176 mGlobal.setTemporaryAutoBrightnessAdjustment(adjustment); 1177 } 1178 1179 /** 1180 * Returns the minimum brightness curve, which guarantess that any brightness curve that dips 1181 * below it is rejected by the system. 1182 * This prevent auto-brightness from setting the screen so dark as to prevent the user from 1183 * resetting or disabling it, and maps lux to the absolute minimum nits that are still readable 1184 * in that ambient brightness. 1185 * 1186 * @return The minimum brightness curve (as lux values and their corresponding nits values). 1187 * 1188 * @hide 1189 */ 1190 @SystemApi getMinimumBrightnessCurve()1191 public Pair<float[], float[]> getMinimumBrightnessCurve() { 1192 return mGlobal.getMinimumBrightnessCurve(); 1193 } 1194 1195 /** 1196 * Sets the global default {@link Display.Mode}. The display mode includes preference for 1197 * resolution and refresh rate. The mode change is applied globally, i.e. to all the connected 1198 * displays. If the mode specified is not supported by a connected display, then no mode change 1199 * occurs for that display. 1200 * 1201 * @param mode The {@link Display.Mode} to set, which can include resolution and/or 1202 * refresh-rate. It is created using {@link Display.Mode.Builder}. 1203 *` 1204 * @hide 1205 */ 1206 @TestApi 1207 @RequiresPermission(Manifest.permission.MODIFY_USER_PREFERRED_DISPLAY_MODE) setGlobalUserPreferredDisplayMode(@onNull Display.Mode mode)1208 public void setGlobalUserPreferredDisplayMode(@NonNull Display.Mode mode) { 1209 // Create a new object containing default values for the unused fields like mode ID and 1210 // alternative refresh rates. 1211 Display.Mode preferredMode = new Display.Mode(mode.getPhysicalWidth(), 1212 mode.getPhysicalHeight(), mode.getRefreshRate()); 1213 mGlobal.setUserPreferredDisplayMode(Display.INVALID_DISPLAY, preferredMode); 1214 } 1215 1216 /** 1217 * Removes the global user preferred display mode. 1218 * User preferred display mode is cleared for all the connected displays. 1219 * 1220 * @hide 1221 */ 1222 @TestApi 1223 @RequiresPermission(Manifest.permission.MODIFY_USER_PREFERRED_DISPLAY_MODE) clearGlobalUserPreferredDisplayMode()1224 public void clearGlobalUserPreferredDisplayMode() { 1225 mGlobal.setUserPreferredDisplayMode(Display.INVALID_DISPLAY, null); 1226 } 1227 1228 /** 1229 * Returns the global user preferred display mode. 1230 * If no user preferred mode has been set, or it has been cleared, this method returns null. 1231 * 1232 * @hide 1233 */ 1234 @TestApi 1235 @Nullable getGlobalUserPreferredDisplayMode()1236 public Display.Mode getGlobalUserPreferredDisplayMode() { 1237 return mGlobal.getUserPreferredDisplayMode(Display.INVALID_DISPLAY); 1238 } 1239 1240 /** 1241 * When enabled the app requested mode is always selected regardless of user settings and 1242 * policies for low brightness, low battery, etc. 1243 * 1244 * @hide 1245 */ 1246 @TestApi 1247 @RequiresPermission(Manifest.permission.OVERRIDE_DISPLAY_MODE_REQUESTS) setShouldAlwaysRespectAppRequestedMode(boolean enabled)1248 public void setShouldAlwaysRespectAppRequestedMode(boolean enabled) { 1249 mGlobal.setShouldAlwaysRespectAppRequestedMode(enabled); 1250 } 1251 1252 /** 1253 * Returns whether we are running in a mode which always selects the app requested display mode 1254 * and ignores user settings and policies for low brightness, low battery etc. 1255 * 1256 * @hide 1257 */ 1258 @TestApi 1259 @RequiresPermission(Manifest.permission.OVERRIDE_DISPLAY_MODE_REQUESTS) shouldAlwaysRespectAppRequestedMode()1260 public boolean shouldAlwaysRespectAppRequestedMode() { 1261 return mGlobal.shouldAlwaysRespectAppRequestedMode(); 1262 } 1263 1264 /** 1265 * Sets the refresh rate switching type. 1266 * This matches {@link android.provider.Settings.Secure.MATCH_CONTENT_FRAME_RATE} 1267 * 1268 * @hide 1269 */ 1270 @TestApi 1271 @RequiresPermission(Manifest.permission.MODIFY_REFRESH_RATE_SWITCHING_TYPE) setRefreshRateSwitchingType(@witchingType int newValue)1272 public void setRefreshRateSwitchingType(@SwitchingType int newValue) { 1273 mGlobal.setRefreshRateSwitchingType(newValue); 1274 } 1275 1276 /** 1277 * Returns the user preference for "Match content frame rate". 1278 * <p> 1279 * Never: Even if the app requests it, the device will never try to match its output to the 1280 * original frame rate of the content. 1281 * </p><p> 1282 * Seamless: If the app requests it, the device will match its output to the original frame 1283 * rate of the content, ONLY if the display can transition seamlessly. 1284 * </p><p> 1285 * Always: If the app requests it, the device will match its output to the original 1286 * frame rate of the content. This may cause the screen to go blank for a 1287 * second when exiting or entering a video playback. 1288 * </p> 1289 */ getMatchContentFrameRateUserPreference()1290 @MatchContentFrameRateType public int getMatchContentFrameRateUserPreference() { 1291 return toMatchContentFrameRateSetting(mGlobal.getRefreshRateSwitchingType()); 1292 } 1293 1294 @MatchContentFrameRateType toMatchContentFrameRateSetting(@witchingType int switchingType)1295 private int toMatchContentFrameRateSetting(@SwitchingType int switchingType) { 1296 switch (switchingType) { 1297 case SWITCHING_TYPE_NONE: 1298 return MATCH_CONTENT_FRAMERATE_NEVER; 1299 case SWITCHING_TYPE_WITHIN_GROUPS: 1300 return MATCH_CONTENT_FRAMERATE_SEAMLESSS_ONLY; 1301 case SWITCHING_TYPE_ACROSS_AND_WITHIN_GROUPS: 1302 return MATCH_CONTENT_FRAMERATE_ALWAYS; 1303 default: 1304 Slog.e(TAG, switchingType + " is not a valid value of switching type."); 1305 return MATCH_CONTENT_FRAMERATE_UNKNOWN; 1306 } 1307 } 1308 1309 /** 1310 * Listens for changes in available display devices. 1311 */ 1312 public interface DisplayListener { 1313 /** 1314 * Called whenever a logical display has been added to the system. 1315 * Use {@link DisplayManager#getDisplay} to get more information about 1316 * the display. 1317 * 1318 * @param displayId The id of the logical display that was added. 1319 */ onDisplayAdded(int displayId)1320 void onDisplayAdded(int displayId); 1321 1322 /** 1323 * Called whenever a logical display has been removed from the system. 1324 * 1325 * @param displayId The id of the logical display that was removed. 1326 */ onDisplayRemoved(int displayId)1327 void onDisplayRemoved(int displayId); 1328 1329 /** 1330 * Called whenever the properties of a logical {@link android.view.Display}, 1331 * such as size and density, have changed. 1332 * 1333 * @param displayId The id of the logical display that changed. 1334 */ onDisplayChanged(int displayId)1335 void onDisplayChanged(int displayId); 1336 } 1337 1338 /** 1339 * Interface for accessing keys belonging to {@link 1340 * android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER}. 1341 * @hide 1342 */ 1343 public interface DeviceConfig { 1344 1345 /** 1346 * Key for refresh rate in the low zone defined by thresholds. 1347 * 1348 * Note that the name and value don't match because they were added before we had a high 1349 * zone to consider. 1350 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1351 * @see android.R.integer#config_defaultZoneBehavior 1352 */ 1353 String KEY_REFRESH_RATE_IN_LOW_ZONE = "refresh_rate_in_zone"; 1354 1355 /** 1356 * Key for accessing the low display brightness thresholds for the configured refresh 1357 * rate zone. 1358 * The value will be a pair of comma separated integers representing the minimum and maximum 1359 * thresholds of the zone, respectively, in display backlight units (i.e. [0, 255]). 1360 * 1361 * Note that the name and value don't match because they were added before we had a high 1362 * zone to consider. 1363 * 1364 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1365 * @see android.R.array#config_brightnessThresholdsOfPeakRefreshRate 1366 * @hide 1367 */ 1368 String KEY_FIXED_REFRESH_RATE_LOW_DISPLAY_BRIGHTNESS_THRESHOLDS = 1369 "peak_refresh_rate_brightness_thresholds"; 1370 1371 /** 1372 * Key for accessing the low ambient brightness thresholds for the configured refresh 1373 * rate zone. The value will be a pair of comma separated integers representing the minimum 1374 * and maximum thresholds of the zone, respectively, in lux. 1375 * 1376 * Note that the name and value don't match because they were added before we had a high 1377 * zone to consider. 1378 * 1379 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1380 * @see android.R.array#config_ambientThresholdsOfPeakRefreshRate 1381 * @hide 1382 */ 1383 String KEY_FIXED_REFRESH_RATE_LOW_AMBIENT_BRIGHTNESS_THRESHOLDS = 1384 "peak_refresh_rate_ambient_thresholds"; 1385 /** 1386 * Key for refresh rate in the high zone defined by thresholds. 1387 * 1388 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1389 * @see android.R.integer#config_fixedRefreshRateInHighZone 1390 */ 1391 String KEY_REFRESH_RATE_IN_HIGH_ZONE = "refresh_rate_in_high_zone"; 1392 1393 /** 1394 * Key for accessing the display brightness thresholds for the configured refresh rate zone. 1395 * The value will be a pair of comma separated integers representing the minimum and maximum 1396 * thresholds of the zone, respectively, in display backlight units (i.e. [0, 255]). 1397 * 1398 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1399 * @see android.R.array#config_brightnessHighThresholdsOfFixedRefreshRate 1400 * @hide 1401 */ 1402 String KEY_FIXED_REFRESH_RATE_HIGH_DISPLAY_BRIGHTNESS_THRESHOLDS = 1403 "fixed_refresh_rate_high_display_brightness_thresholds"; 1404 1405 /** 1406 * Key for accessing the ambient brightness thresholds for the configured refresh rate zone. 1407 * The value will be a pair of comma separated integers representing the minimum and maximum 1408 * thresholds of the zone, respectively, in lux. 1409 * 1410 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1411 * @see android.R.array#config_ambientHighThresholdsOfFixedRefreshRate 1412 * @hide 1413 */ 1414 String KEY_FIXED_REFRESH_RATE_HIGH_AMBIENT_BRIGHTNESS_THRESHOLDS = 1415 "fixed_refresh_rate_high_ambient_brightness_thresholds"; 1416 1417 /** 1418 * Key for refresh rate when the device is in high brightness mode for sunlight visility. 1419 * 1420 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1421 * @see android.R.integer#config_defaultRefreshRateInHbmSunlight 1422 */ 1423 String KEY_REFRESH_RATE_IN_HBM_SUNLIGHT = "refresh_rate_in_hbm_sunlight"; 1424 1425 /** 1426 * Key for refresh rate when the device is in high brightness mode for HDR. 1427 * 1428 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1429 * @see android.R.integer#config_defaultRefreshRateInHbmHdr 1430 */ 1431 String KEY_REFRESH_RATE_IN_HBM_HDR = "refresh_rate_in_hbm_hdr"; 1432 1433 /** 1434 * Key for default peak refresh rate 1435 * 1436 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1437 * @see android.R.integer#config_defaultPeakRefreshRate 1438 * @hide 1439 */ 1440 String KEY_PEAK_REFRESH_RATE_DEFAULT = "peak_refresh_rate_default"; 1441 1442 // TODO(b/162536543): rename it once it is proved not harmful for users. 1443 /** 1444 * Key for controlling which packages are explicitly blocked from running at refresh rates 1445 * higher than 60hz. An app may be added to this list if they exhibit performance issues at 1446 * higher refresh rates. 1447 * 1448 * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER 1449 * @see android.R.array#config_highRefreshRateBlacklist 1450 * @hide 1451 */ 1452 String KEY_HIGH_REFRESH_RATE_BLACKLIST = "high_refresh_rate_blacklist"; 1453 1454 /** 1455 * Key for the brightness throttling data as a String formatted: 1456 * <displayId>,<no of throttling levels>,[<severity as string>,<brightness cap>] 1457 * Where the latter part is repeated for each throttling level, and the entirety is repeated 1458 * for each display, separated by a semicolon. 1459 * For example: 1460 * 123,1,critical,0.8;456,2,moderate,0.9,critical,0.7 1461 */ 1462 String KEY_BRIGHTNESS_THROTTLING_DATA = "brightness_throttling_data"; 1463 } 1464 } 1465