1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.display; 18 19 import android.annotation.IntDef; 20 import android.annotation.Nullable; 21 import android.companion.virtual.IVirtualDevice; 22 import android.graphics.Point; 23 import android.hardware.SensorManager; 24 import android.hardware.input.HostUsiVersion; 25 import android.os.Handler; 26 import android.os.PowerManager; 27 import android.util.IntArray; 28 import android.util.SparseArray; 29 import android.view.Display; 30 import android.view.DisplayInfo; 31 import android.view.SurfaceControl; 32 import android.view.SurfaceControl.RefreshRateRange; 33 import android.view.SurfaceControl.Transaction; 34 import android.window.DisplayWindowPolicyController; 35 import android.window.ScreenCapture; 36 37 import java.lang.annotation.Retention; 38 import java.lang.annotation.RetentionPolicy; 39 import java.util.List; 40 import java.util.Set; 41 42 /** 43 * Display manager local system service interface. 44 * 45 * @hide Only for use within the system server. 46 */ 47 public abstract class DisplayManagerInternal { 48 49 @IntDef(prefix = {"REFRESH_RATE_LIMIT_"}, value = { 50 REFRESH_RATE_LIMIT_HIGH_BRIGHTNESS_MODE 51 }) 52 @Retention(RetentionPolicy.SOURCE) 53 public @interface RefreshRateLimitType {} 54 55 /** Refresh rate should be limited when High Brightness Mode is active. */ 56 public static final int REFRESH_RATE_LIMIT_HIGH_BRIGHTNESS_MODE = 1; 57 58 /** 59 * Called by the power manager to initialize power management facilities. 60 */ initPowerManagement(DisplayPowerCallbacks callbacks, Handler handler, SensorManager sensorManager)61 public abstract void initPowerManagement(DisplayPowerCallbacks callbacks, 62 Handler handler, SensorManager sensorManager); 63 64 /** 65 * Called by the VirtualDeviceManagerService to create a VirtualDisplay owned by a 66 * VirtualDevice. 67 */ createVirtualDisplay(VirtualDisplayConfig config, IVirtualDisplayCallback callback, IVirtualDevice virtualDevice, DisplayWindowPolicyController dwpc, String packageName)68 public abstract int createVirtualDisplay(VirtualDisplayConfig config, 69 IVirtualDisplayCallback callback, IVirtualDevice virtualDevice, 70 DisplayWindowPolicyController dwpc, String packageName); 71 72 /** 73 * Called by the power manager to request a new power state. 74 * <p> 75 * The display power controller makes a copy of the provided object and then 76 * begins adjusting the power state to match what was requested. 77 * </p> 78 * 79 * @param groupId The identifier for the display group being requested to change power state 80 * @param request The requested power state. 81 * @param waitForNegativeProximity If {@code true}, issues a request to wait for 82 * negative proximity before turning the screen back on, assuming the screen 83 * was turned off by the proximity sensor. 84 * @return {@code true} if display group is ready, {@code false} if there are important 85 * changes that must be made asynchronously (such as turning the screen on), in which case 86 * the caller should grab a wake lock, watch for {@link DisplayPowerCallbacks#onStateChanged} 87 * then try the request again later until the state converges. If the provided {@code groupId} 88 * cannot be found then {@code true} will be returned. 89 */ requestPowerState(int groupId, DisplayPowerRequest request, boolean waitForNegativeProximity)90 public abstract boolean requestPowerState(int groupId, DisplayPowerRequest request, 91 boolean waitForNegativeProximity); 92 93 /** 94 * Returns {@code true} if the proximity sensor screen-off function is available. 95 */ isProximitySensorAvailable()96 public abstract boolean isProximitySensorAvailable(); 97 98 /** 99 * Registers a display group listener which will be informed of the addition, removal, or change 100 * of display groups. 101 * 102 * @param listener The listener to register. 103 */ registerDisplayGroupListener(DisplayGroupListener listener)104 public abstract void registerDisplayGroupListener(DisplayGroupListener listener); 105 106 /** 107 * Unregisters a display group listener which will be informed of the addition, removal, or 108 * change of display groups. 109 * 110 * @param listener The listener to unregister. 111 */ unregisterDisplayGroupListener(DisplayGroupListener listener)112 public abstract void unregisterDisplayGroupListener(DisplayGroupListener listener); 113 114 /** 115 * Screenshot for internal system-only use such as rotation, etc. This method includes 116 * secure layers and the result should never be exposed to non-system applications. 117 * This method does not apply any rotation and provides the output in natural orientation. 118 * 119 * @param displayId The display id to take the screenshot of. 120 * @return The buffer or null if we have failed. 121 */ systemScreenshot(int displayId)122 public abstract ScreenCapture.ScreenshotHardwareBuffer systemScreenshot(int displayId); 123 124 /** 125 * General screenshot functionality that excludes secure layers and applies appropriate 126 * rotation that the device is currently in. 127 * 128 * @param displayId The display id to take the screenshot of. 129 * @return The buffer or null if we have failed. 130 */ userScreenshot(int displayId)131 public abstract ScreenCapture.ScreenshotHardwareBuffer userScreenshot(int displayId); 132 133 /** 134 * Returns information about the specified logical display. 135 * 136 * @param displayId The logical display id. 137 * @return The logical display info, or null if the display does not exist. The 138 * returned object must be treated as immutable. 139 */ getDisplayInfo(int displayId)140 public abstract DisplayInfo getDisplayInfo(int displayId); 141 142 /** 143 * Returns a set of DisplayInfo, for the states that may be assumed by either the given display, 144 * or any other display within that display's group. 145 * 146 * @param displayId The logical display id to fetch DisplayInfo for. 147 */ getPossibleDisplayInfo(int displayId)148 public abstract Set<DisplayInfo> getPossibleDisplayInfo(int displayId); 149 150 /** 151 * Returns the position of the display's projection. 152 * 153 * @param displayId The logical display id. 154 * @return The x, y coordinates of the display, or null if the display does not exist. The 155 * return object must be treated as immutable. 156 */ 157 @Nullable getDisplayPosition(int displayId)158 public abstract Point getDisplayPosition(int displayId); 159 160 /** 161 * Registers a display transaction listener to provide the client a chance to 162 * update its surfaces within the same transaction as any display layout updates. 163 * 164 * @param listener The listener to register. 165 */ registerDisplayTransactionListener(DisplayTransactionListener listener)166 public abstract void registerDisplayTransactionListener(DisplayTransactionListener listener); 167 168 /** 169 * Unregisters a display transaction listener to provide the client a chance to 170 * update its surfaces within the same transaction as any display layout updates. 171 * 172 * @param listener The listener to unregister. 173 */ unregisterDisplayTransactionListener(DisplayTransactionListener listener)174 public abstract void unregisterDisplayTransactionListener(DisplayTransactionListener listener); 175 176 /** 177 * Overrides the display information of a particular logical display. 178 * This is used by the window manager to control the size and characteristics 179 * of the default display. It is expected to apply the requested change 180 * to the display information synchronously so that applications will immediately 181 * observe the new state. 182 * 183 * NOTE: This method must be the only entry point by which the window manager 184 * influences the logical configuration of displays. 185 * 186 * @param displayId The logical display id. 187 * @param info The new data to be stored. 188 */ setDisplayInfoOverrideFromWindowManager( int displayId, DisplayInfo info)189 public abstract void setDisplayInfoOverrideFromWindowManager( 190 int displayId, DisplayInfo info); 191 192 /** 193 * Get current display info without override from WindowManager. 194 * Current implementation of LogicalDisplay#getDisplayInfoLocked() always returns display info 195 * with overrides from WM if set. This method can be used for getting real display size without 196 * overrides to determine if real changes to display metrics happened. 197 * @param displayId Id of the target display. 198 * @param outInfo {@link DisplayInfo} to fill. 199 */ getNonOverrideDisplayInfo(int displayId, DisplayInfo outInfo)200 public abstract void getNonOverrideDisplayInfo(int displayId, DisplayInfo outInfo); 201 202 /** 203 * Called by the window manager to perform traversals while holding a 204 * surface flinger transaction. 205 * @param t The default transaction. 206 * @param displayTransactions The transactions mapped by display id. 207 */ performTraversal(Transaction t, SparseArray<SurfaceControl.Transaction> displayTransactions)208 public abstract void performTraversal(Transaction t, 209 SparseArray<SurfaceControl.Transaction> displayTransactions); 210 211 /** 212 * Tells the display manager about properties of the display that depend on the windows on it. 213 * This includes whether there is interesting unique content on the specified logical display, 214 * and whether the one of the windows has a preferred refresh rate. 215 * <p> 216 * If the display has unique content, then the display manager arranges for it 217 * to be presented on a physical display if appropriate. Otherwise, the display manager 218 * may choose to make the physical display mirror some other logical display. 219 * </p> 220 * 221 * <p> 222 * If one of the windows on the display has a preferred refresh rate that's supported by the 223 * display, then the display manager will request its use. 224 * </p> 225 * 226 * @param displayId The logical display id to update. 227 * @param hasContent True if the logical display has content. This is used to control automatic 228 * mirroring. 229 * @param requestedRefreshRate The preferred refresh rate for the top-most visible window that 230 * has a preference. 231 * @param requestedModeId The preferred mode id for the top-most visible window that has a 232 * preference. 233 * @param requestedMinRefreshRate The preferred lowest refresh rate for the top-most visible 234 * window that has a preference. 235 * @param requestedMaxRefreshRate The preferred highest refresh rate for the top-most visible 236 * window that has a preference. 237 * @param requestedMinimalPostProcessing The preferred minimal post processing setting for the 238 * display. This is true when there is at least one visible window that wants minimal post 239 * processng on. 240 * @param disableHdrConversion The preferred HDR conversion setting for the window. 241 * @param inTraversal True if called from WindowManagerService during a window traversal 242 * prior to call to performTraversalInTransactionFromWindowManager. 243 */ setDisplayProperties(int displayId, boolean hasContent, float requestedRefreshRate, int requestedModeId, float requestedMinRefreshRate, float requestedMaxRefreshRate, boolean requestedMinimalPostProcessing, boolean disableHdrConversion, boolean inTraversal)244 public abstract void setDisplayProperties(int displayId, boolean hasContent, 245 float requestedRefreshRate, int requestedModeId, float requestedMinRefreshRate, 246 float requestedMaxRefreshRate, boolean requestedMinimalPostProcessing, 247 boolean disableHdrConversion, boolean inTraversal); 248 249 /** 250 * Applies an offset to the contents of a display, for example to avoid burn-in. 251 * <p> 252 * TODO: Technically this should be associated with a physical rather than logical 253 * display but this is good enough for now. 254 * </p> 255 * 256 * @param displayId The logical display id to update. 257 * @param x The X offset by which to shift the contents of the display. 258 * @param y The Y offset by which to shift the contents of the display. 259 */ setDisplayOffsets(int displayId, int x, int y)260 public abstract void setDisplayOffsets(int displayId, int x, int y); 261 262 /** 263 * Disables scaling for a display. 264 * 265 * @param displayId The logical display id to disable scaling for. 266 * @param disableScaling {@code true} to disable scaling, 267 * {@code false} to use the default scaling behavior of the logical display. 268 */ setDisplayScalingDisabled(int displayId, boolean disableScaling)269 public abstract void setDisplayScalingDisabled(int displayId, boolean disableScaling); 270 271 /** 272 * Provide a list of UIDs that are present on the display and are allowed to access it. 273 * 274 * @param displayAccessUIDs Mapping displayId -> int array of UIDs. 275 */ setDisplayAccessUIDs(SparseArray<IntArray> displayAccessUIDs)276 public abstract void setDisplayAccessUIDs(SparseArray<IntArray> displayAccessUIDs); 277 278 /** 279 * Persist brightness slider events and ambient brightness stats. 280 */ persistBrightnessTrackerState()281 public abstract void persistBrightnessTrackerState(); 282 283 /** 284 * Notifies the display manager that resource overlays have changed. 285 */ onOverlayChanged()286 public abstract void onOverlayChanged(); 287 288 /** 289 * Get the attributes available for display color sampling. 290 * @param displayId id of the display to collect the sample from. 291 * 292 * @return The attributes the display supports, or null if sampling is not supported. 293 */ 294 @Nullable getDisplayedContentSamplingAttributes( int displayId)295 public abstract DisplayedContentSamplingAttributes getDisplayedContentSamplingAttributes( 296 int displayId); 297 298 /** 299 * Enable or disable the collection of color samples. 300 * 301 * @param displayId id of the display to collect the sample from. 302 * @param componentMask a bitmask of the color channels to collect samples for, or zero for all 303 * available. 304 * @param maxFrames maintain a ringbuffer of the last maxFrames. 305 * @param enable True to enable, False to disable. 306 * 307 * @return True if sampling was enabled, false if failure. 308 */ setDisplayedContentSamplingEnabled( int displayId, boolean enable, int componentMask, int maxFrames)309 public abstract boolean setDisplayedContentSamplingEnabled( 310 int displayId, boolean enable, int componentMask, int maxFrames); 311 312 /** 313 * Accesses the color histogram statistics of displayed frames on devices that support sampling. 314 * 315 * @param displayId id of the display to collect the sample from 316 * @param maxFrames limit the statistics to the last maxFrames number of frames. 317 * @param timestamp discard statistics that were collected prior to timestamp, where timestamp 318 * is given as CLOCK_MONOTONIC. 319 * @return The statistics representing a histogram of the color distribution of the frames 320 * displayed on-screen, or null if sampling is not supported. 321 */ 322 @Nullable getDisplayedContentSample( int displayId, long maxFrames, long timestamp)323 public abstract DisplayedContentSample getDisplayedContentSample( 324 int displayId, long maxFrames, long timestamp); 325 326 /** 327 * Temporarily ignore proximity-sensor-based display behavior until there is a change 328 * to the proximity sensor state. This allows the display to turn back on even if something 329 * is obstructing the proximity sensor. 330 */ ignoreProximitySensorUntilChanged()331 public abstract void ignoreProximitySensorUntilChanged(); 332 333 /** 334 * Returns the refresh rate switching type. 335 */ 336 @DisplayManager.SwitchingType getRefreshRateSwitchingType()337 public abstract int getRefreshRateSwitchingType(); 338 339 /** 340 * TODO: b/191384041 - Replace this with getRefreshRateLimitations() 341 * Return the refresh rate restriction for the specified display and sensor pairing. If the 342 * specified sensor is identified as an associated sensor in the specified display's 343 * display-device-config file, then return any refresh rate restrictions that it might define. 344 * If no restriction is specified, or the sensor is not associated with the display, then null 345 * will be returned. 346 * 347 * @param displayId The display to check against. 348 * @param name The name of the sensor. 349 * @param type The type of sensor. 350 * 351 * @return The min/max refresh-rate restriction as a {@link Pair} of floats, or null if not 352 * restricted. 353 */ getRefreshRateForDisplayAndSensor( int displayId, String name, String type)354 public abstract RefreshRateRange getRefreshRateForDisplayAndSensor( 355 int displayId, String name, String type); 356 357 /** 358 * Returns a list of various refresh rate limitations for the specified display. 359 * 360 * @param displayId The display to get limitations for. 361 * 362 * @return a list of {@link RefreshRateLimitation}s describing the various limits. 363 */ getRefreshRateLimitations(int displayId)364 public abstract List<RefreshRateLimitation> getRefreshRateLimitations(int displayId); 365 366 /** 367 * For the given displayId, updates if WindowManager is responsible for mirroring on that 368 * display. If {@code false}, then SurfaceFlinger performs no layer mirroring to the 369 * given display. 370 * Only used for mirroring started from MediaProjection. 371 */ setWindowManagerMirroring(int displayId, boolean isMirroring)372 public abstract void setWindowManagerMirroring(int displayId, boolean isMirroring); 373 374 /** 375 * Returns the default size of the surface associated with the display, or null if the surface 376 * is not provided for layer mirroring by SurfaceFlinger. Size is rotated to reflect the current 377 * display device orientation. 378 * Used for mirroring from MediaProjection, or a physical display based on display flags. 379 */ getDisplaySurfaceDefaultSize(int displayId)380 public abstract Point getDisplaySurfaceDefaultSize(int displayId); 381 382 /** 383 * Get a new displayId which represents the display you want to mirror. If mirroring is not 384 * enabled on the display, {@link Display#INVALID_DISPLAY} will be returned. 385 * 386 * @param displayId The id of the display. 387 * @return The displayId that should be mirrored or INVALID_DISPLAY if mirroring is not enabled. 388 */ getDisplayIdToMirror(int displayId)389 public abstract int getDisplayIdToMirror(int displayId); 390 391 /** 392 * Receives early interactivity changes from power manager. 393 * 394 * @param interactive The interactive state that the device is moving into. 395 */ onEarlyInteractivityChange(boolean interactive)396 public abstract void onEarlyInteractivityChange(boolean interactive); 397 398 /** 399 * Get {@link DisplayWindowPolicyController} associated to the {@link DisplayInfo#displayId} 400 * 401 * @param displayId The id of the display. 402 * @return The associated {@link DisplayWindowPolicyController}. 403 */ getDisplayWindowPolicyController(int displayId)404 public abstract DisplayWindowPolicyController getDisplayWindowPolicyController(int displayId); 405 406 /** 407 * Get DisplayPrimaries from SF for a particular display. 408 */ getDisplayNativePrimaries(int displayId)409 public abstract SurfaceControl.DisplayPrimaries getDisplayNativePrimaries(int displayId); 410 411 /** 412 * Get the version of the Universal Stylus Initiative (USI) Protocol supported by the display. 413 * @param displayId The id of the display. 414 * @return The USI version, or null if not supported 415 */ 416 @Nullable getHostUsiVersion(int displayId)417 public abstract HostUsiVersion getHostUsiVersion(int displayId); 418 419 /** 420 * Get the ALS data for a particular display. 421 * 422 * @param displayId The id of the display. 423 * @return {@link AmbientLightSensorData} 424 */ 425 @Nullable getAmbientLightSensorData(int displayId)426 public abstract AmbientLightSensorData getAmbientLightSensorData(int displayId); 427 428 /** 429 * Get all available DisplayGroupIds. 430 */ getDisplayGroupIds()431 public abstract IntArray getDisplayGroupIds(); 432 433 /** 434 * Called upon presentation started/ended on the display. 435 * @param displayId the id of the display where presentation started. 436 * @param isShown whether presentation is shown. 437 */ onPresentation(int displayId, boolean isShown)438 public abstract void onPresentation(int displayId, boolean isShown); 439 440 /** 441 * Describes the requested power state of the display. 442 * 443 * This object is intended to describe the general characteristics of the 444 * power state, such as whether the screen should be on or off and the current 445 * brightness controls leaving the DisplayPowerController to manage the 446 * details of how the transitions between states should occur. The goal is for 447 * the PowerManagerService to focus on the global power state and not 448 * have to micro-manage screen off animations, auto-brightness and other effects. 449 */ 450 public static class DisplayPowerRequest { 451 // Policy: Turn screen off as if the user pressed the power button 452 // including playing a screen off animation if applicable. 453 public static final int POLICY_OFF = 0; 454 // Policy: Enable dozing and always-on display functionality. 455 public static final int POLICY_DOZE = 1; 456 // Policy: Make the screen dim when the user activity timeout is 457 // about to expire. 458 public static final int POLICY_DIM = 2; 459 // Policy: Make the screen bright as usual. 460 public static final int POLICY_BRIGHT = 3; 461 462 // The basic overall policy to apply: off, doze, dim or bright. 463 public int policy; 464 465 // If true, the proximity sensor overrides the screen state when an object is 466 // nearby, turning it off temporarily until the object is moved away. 467 public boolean useProximitySensor; 468 469 // An override of the screen brightness. 470 // Set to PowerManager.BRIGHTNESS_INVALID if there's no override. 471 public float screenBrightnessOverride; 472 473 // An override of the screen auto-brightness adjustment factor in the range -1 (dimmer) to 474 // 1 (brighter). Set to Float.NaN if there's no override. 475 public float screenAutoBrightnessAdjustmentOverride; 476 477 // If true, scales the brightness to a fraction of desired (as defined by 478 // screenLowPowerBrightnessFactor). 479 public boolean lowPowerMode; 480 481 // The factor to adjust the screen brightness in low power mode in the range 482 // 0 (screen off) to 1 (no change) 483 public float screenLowPowerBrightnessFactor; 484 485 // If true, applies a brightness boost. 486 public boolean boostScreenBrightness; 487 488 // If true, prevents the screen from completely turning on if it is currently off. 489 // The display does not enter a "ready" state if this flag is true and screen on is 490 // blocked. The window manager policy blocks screen on while it prepares the keyguard to 491 // prevent the user from seeing intermediate updates. 492 // 493 // Technically, we may not block the screen itself from turning on (because that introduces 494 // extra unnecessary latency) but we do prevent content on screen from becoming 495 // visible to the user. 496 public boolean blockScreenOn; 497 498 // Overrides the policy for adjusting screen brightness and state while dozing. 499 public int dozeScreenState; 500 public float dozeScreenBrightness; 501 public int dozeScreenStateReason; 502 DisplayPowerRequest()503 public DisplayPowerRequest() { 504 policy = POLICY_BRIGHT; 505 useProximitySensor = false; 506 screenBrightnessOverride = PowerManager.BRIGHTNESS_INVALID_FLOAT; 507 screenAutoBrightnessAdjustmentOverride = Float.NaN; 508 screenLowPowerBrightnessFactor = 0.5f; 509 blockScreenOn = false; 510 dozeScreenBrightness = PowerManager.BRIGHTNESS_INVALID_FLOAT; 511 dozeScreenState = Display.STATE_UNKNOWN; 512 dozeScreenStateReason = Display.STATE_REASON_UNKNOWN; 513 } 514 DisplayPowerRequest(DisplayPowerRequest other)515 public DisplayPowerRequest(DisplayPowerRequest other) { 516 copyFrom(other); 517 } 518 isBrightOrDim()519 public boolean isBrightOrDim() { 520 return policy == POLICY_BRIGHT || policy == POLICY_DIM; 521 } 522 copyFrom(DisplayPowerRequest other)523 public void copyFrom(DisplayPowerRequest other) { 524 policy = other.policy; 525 useProximitySensor = other.useProximitySensor; 526 screenBrightnessOverride = other.screenBrightnessOverride; 527 screenAutoBrightnessAdjustmentOverride = other.screenAutoBrightnessAdjustmentOverride; 528 screenLowPowerBrightnessFactor = other.screenLowPowerBrightnessFactor; 529 blockScreenOn = other.blockScreenOn; 530 lowPowerMode = other.lowPowerMode; 531 boostScreenBrightness = other.boostScreenBrightness; 532 dozeScreenBrightness = other.dozeScreenBrightness; 533 dozeScreenState = other.dozeScreenState; 534 dozeScreenStateReason = other.dozeScreenStateReason; 535 } 536 537 @Override equals(@ullable Object o)538 public boolean equals(@Nullable Object o) { 539 return o instanceof DisplayPowerRequest 540 && equals((DisplayPowerRequest)o); 541 } 542 equals(DisplayPowerRequest other)543 public boolean equals(DisplayPowerRequest other) { 544 return other != null 545 && policy == other.policy 546 && useProximitySensor == other.useProximitySensor 547 && floatEquals(screenBrightnessOverride, 548 other.screenBrightnessOverride) 549 && floatEquals(screenAutoBrightnessAdjustmentOverride, 550 other.screenAutoBrightnessAdjustmentOverride) 551 && screenLowPowerBrightnessFactor 552 == other.screenLowPowerBrightnessFactor 553 && blockScreenOn == other.blockScreenOn 554 && lowPowerMode == other.lowPowerMode 555 && boostScreenBrightness == other.boostScreenBrightness 556 && floatEquals(dozeScreenBrightness, other.dozeScreenBrightness) 557 && dozeScreenState == other.dozeScreenState 558 && dozeScreenStateReason == other.dozeScreenStateReason; 559 } 560 floatEquals(float f1, float f2)561 private boolean floatEquals(float f1, float f2) { 562 return f1 == f2 || Float.isNaN(f1) && Float.isNaN(f2); 563 } 564 565 @Override hashCode()566 public int hashCode() { 567 return 0; // don't care 568 } 569 570 @Override toString()571 public String toString() { 572 return "policy=" + policyToString(policy) 573 + ", useProximitySensor=" + useProximitySensor 574 + ", screenBrightnessOverride=" + screenBrightnessOverride 575 + ", screenAutoBrightnessAdjustmentOverride=" 576 + screenAutoBrightnessAdjustmentOverride 577 + ", screenLowPowerBrightnessFactor=" + screenLowPowerBrightnessFactor 578 + ", blockScreenOn=" + blockScreenOn 579 + ", lowPowerMode=" + lowPowerMode 580 + ", boostScreenBrightness=" + boostScreenBrightness 581 + ", dozeScreenBrightness=" + dozeScreenBrightness 582 + ", dozeScreenState=" + Display.stateToString(dozeScreenState) 583 + ", dozeScreenStateReason=" 584 + Display.stateReasonToString(dozeScreenStateReason); 585 } 586 policyToString(int policy)587 public static String policyToString(int policy) { 588 switch (policy) { 589 case POLICY_OFF: 590 return "OFF"; 591 case POLICY_DOZE: 592 return "DOZE"; 593 case POLICY_DIM: 594 return "DIM"; 595 case POLICY_BRIGHT: 596 return "BRIGHT"; 597 default: 598 return Integer.toString(policy); 599 } 600 } 601 } 602 603 /** 604 * Asynchronous callbacks from the power controller to the power manager service. 605 */ 606 public interface DisplayPowerCallbacks { onStateChanged()607 void onStateChanged(); onProximityPositive()608 void onProximityPositive(); onProximityNegative()609 void onProximityNegative(); onDisplayStateChange(boolean allInactive, boolean allOff)610 void onDisplayStateChange(boolean allInactive, boolean allOff); 611 612 /** 613 * Acquires a suspend blocker with a specified label. 614 * 615 * @param id A logging label for the acquisition. 616 */ acquireSuspendBlocker(String id)617 void acquireSuspendBlocker(String id); 618 619 /** 620 * Releases a suspend blocker with a specified label. 621 * 622 * @param id A logging label for the release. 623 */ releaseSuspendBlocker(String id)624 void releaseSuspendBlocker(String id); 625 } 626 627 /** 628 * Called within a Surface transaction whenever the size or orientation of a 629 * display may have changed. Provides an opportunity for the client to 630 * update the position of its surfaces as part of the same transaction. 631 */ 632 public interface DisplayTransactionListener { onDisplayTransaction(Transaction t)633 void onDisplayTransaction(Transaction t); 634 } 635 636 /** 637 * Called when there are changes to {@link com.android.server.display.DisplayGroup 638 * DisplayGroups}. 639 */ 640 public interface DisplayGroupListener { 641 /** 642 * A new display group with the provided {@code groupId} was added. 643 * 644 * <ol> 645 * <li>The {@code groupId} is applied to all appropriate {@link Display displays}. 646 * <li>This method is called. 647 * <li>{@link android.hardware.display.DisplayManager.DisplayListener DisplayListeners} 648 * are informed of any corresponding changes. 649 * </ol> 650 */ onDisplayGroupAdded(int groupId)651 void onDisplayGroupAdded(int groupId); 652 653 /** 654 * The display group with the provided {@code groupId} was removed. 655 * 656 * <ol> 657 * <li>All affected {@link Display displays} have their group IDs updated appropriately. 658 * <li>{@link android.hardware.display.DisplayManager.DisplayListener DisplayListeners} 659 * are informed of any corresponding changes. 660 * <li>This method is called. 661 * </ol> 662 */ onDisplayGroupRemoved(int groupId)663 void onDisplayGroupRemoved(int groupId); 664 665 /** 666 * The display group with the provided {@code groupId} has changed. 667 * 668 * <ol> 669 * <li>All affected {@link Display displays} have their group IDs updated appropriately. 670 * <li>{@link android.hardware.display.DisplayManager.DisplayListener DisplayListeners} 671 * are informed of any corresponding changes. 672 * <li>This method is called. 673 * </ol> 674 */ onDisplayGroupChanged(int groupId)675 void onDisplayGroupChanged(int groupId); 676 } 677 678 /** 679 * Describes a limitation on a display's refresh rate. Includes the allowed refresh rate 680 * range as well as information about when it applies, such as high-brightness-mode. 681 */ 682 public static final class RefreshRateLimitation { 683 @RefreshRateLimitType public int type; 684 685 /** The range the that refresh rate should be limited to. */ 686 public RefreshRateRange range; 687 RefreshRateLimitation(@efreshRateLimitType int type, float min, float max)688 public RefreshRateLimitation(@RefreshRateLimitType int type, float min, float max) { 689 this.type = type; 690 range = new RefreshRateRange(min, max); 691 } 692 693 @Override toString()694 public String toString() { 695 return "RefreshRateLimitation(" + type + ": " + range + ")"; 696 } 697 } 698 699 /** 700 * Class to provide Ambient sensor data using the API 701 * {@link DisplayManagerInternal#getAmbientLightSensorData(int)} 702 */ 703 public static final class AmbientLightSensorData { 704 public String sensorName; 705 public String sensorType; 706 AmbientLightSensorData(String name, String type)707 public AmbientLightSensorData(String name, String type) { 708 sensorName = name; 709 sensorType = type; 710 } 711 712 @Override toString()713 public String toString() { 714 return "AmbientLightSensorData(" + sensorName + ", " + sensorType + ")"; 715 } 716 } 717 718 /** 719 * Associate a internal display to a {@link DisplayOffloader}. 720 * 721 * @param displayId the id of the internal display. 722 * @param displayOffloader the {@link DisplayOffloader} that controls offloading ops of internal 723 * display whose id is displayId. 724 * @return a {@link DisplayOffloadSession} associated with given displayId and displayOffloader. 725 */ registerDisplayOffloader( int displayId, DisplayOffloader displayOffloader)726 public abstract DisplayOffloadSession registerDisplayOffloader( 727 int displayId, DisplayOffloader displayOffloader); 728 729 /** The callbacks that controls the entry & exit of display offloading. */ 730 public interface DisplayOffloader { startOffload()731 boolean startOffload(); 732 stopOffload()733 void stopOffload(); 734 735 /** 736 * Called when {@link DisplayOffloadSession} tries to block screen turning on. 737 * 738 * @param unblocker a {@link Runnable} executed upon all work required before screen turning 739 * on is done. 740 */ onBlockingScreenOn(Runnable unblocker)741 void onBlockingScreenOn(Runnable unblocker); 742 743 /** Whether auto brightness update in doze is allowed */ allowAutoBrightnessInDoze()744 boolean allowAutoBrightnessInDoze(); 745 } 746 747 /** A session token that associates a internal display with a {@link DisplayOffloader}. */ 748 public interface DisplayOffloadSession { 749 /** Provide the display state to use in place of state DOZE. */ setDozeStateOverride(int displayState)750 void setDozeStateOverride(int displayState); 751 752 /** Whether the session is active. */ isActive()753 boolean isActive(); 754 755 /** Whether auto brightness update in doze is allowed */ allowAutoBrightnessInDoze()756 boolean allowAutoBrightnessInDoze(); 757 758 /** 759 * Update the brightness from the offload chip. 760 * @param brightness The brightness value between {@link PowerManager.BRIGHTNESS_MIN} and 761 * {@link PowerManager.BRIGHTNESS_MAX}, or 762 * {@link PowerManager.BRIGHTNESS_INVALID_FLOAT} which removes 763 * the brightness from offload. Other values will be ignored. 764 */ updateBrightness(float brightness)765 void updateBrightness(float brightness); 766 767 /** 768 * Called while display is turning to state ON to leave a small period for displayoffload 769 * session to finish some work. 770 * 771 * @param unblocker a {@link Runnable} used by displayoffload session to notify 772 * {@link DisplayManager} that it can continue turning screen on. 773 */ blockScreenOn(Runnable unblocker)774 boolean blockScreenOn(Runnable unblocker); 775 776 /** 777 * Get the brightness levels used to determine automatic brightness based on lux levels. 778 * @param mode The auto-brightness mode 779 * (AutomaticBrightnessController.AutomaticBrightnessMode) 780 * @return The brightness levels for the specified mode. The values are between 781 * {@link PowerManager.BRIGHTNESS_MIN} and {@link PowerManager.BRIGHTNESS_MAX}. 782 */ getAutoBrightnessLevels(int mode)783 float[] getAutoBrightnessLevels(int mode); 784 785 /** 786 * Get the lux levels used to determine automatic brightness. 787 * @param mode The auto-brightness mode 788 * (AutomaticBrightnessController.AutomaticBrightnessMode) 789 * @return The lux levels for the specified mode 790 */ getAutoBrightnessLuxLevels(int mode)791 float[] getAutoBrightnessLuxLevels(int mode); 792 793 /** 794 * @return The current brightness setting 795 */ getBrightness()796 float getBrightness(); 797 798 /** 799 * @return The brightness value that is used when the device is in doze 800 */ getDozeBrightness()801 float getDozeBrightness(); 802 803 /** Returns whether displayoffload supports the given display state. */ isSupportedOffloadState(int displayState)804 static boolean isSupportedOffloadState(int displayState) { 805 return Display.isSuspendedState(displayState); 806 } 807 } 808 } 809