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.hardware.SensorManager; 20 import android.os.Handler; 21 import android.os.PowerManager; 22 import android.util.IntArray; 23 import android.util.SparseArray; 24 import android.view.Display; 25 import android.view.DisplayInfo; 26 27 /** 28 * Display manager local system service interface. 29 * 30 * @hide Only for use within the system server. 31 */ 32 public abstract class DisplayManagerInternal { 33 /** 34 * Called by the power manager to initialize power management facilities. 35 */ 36 public abstract void initPowerManagement(DisplayPowerCallbacks callbacks, 37 Handler handler, SensorManager sensorManager); 38 39 /** 40 * Called by the power manager to request a new power state. 41 * <p> 42 * The display power controller makes a copy of the provided object and then 43 * begins adjusting the power state to match what was requested. 44 * </p> 45 * 46 * @param request The requested power state. 47 * @param waitForNegativeProximity If true, issues a request to wait for 48 * negative proximity before turning the screen back on, assuming the screen 49 * was turned off by the proximity sensor. 50 * @return True if display is ready, false if there are important changes that must 51 * be made asynchronously (such as turning the screen on), in which case the caller 52 * should grab a wake lock, watch for {@link DisplayPowerCallbacks#onStateChanged()} 53 * then try the request again later until the state converges. 54 */ 55 public abstract boolean requestPowerState(DisplayPowerRequest request, 56 boolean waitForNegativeProximity); 57 58 /** 59 * Returns true if the proximity sensor screen-off function is available. 60 */ 61 public abstract boolean isProximitySensorAvailable(); 62 63 /** 64 * Returns information about the specified logical display. 65 * 66 * @param displayId The logical display id. 67 * @return The logical display info, or null if the display does not exist. The 68 * returned object must be treated as immutable. 69 */ 70 public abstract DisplayInfo getDisplayInfo(int displayId); 71 72 /** 73 * Registers a display transaction listener to provide the client a chance to 74 * update its surfaces within the same transaction as any display layout updates. 75 * 76 * @param listener The listener to register. 77 */ 78 public abstract void registerDisplayTransactionListener(DisplayTransactionListener listener); 79 80 /** 81 * Unregisters a display transaction listener to provide the client a chance to 82 * update its surfaces within the same transaction as any display layout updates. 83 * 84 * @param listener The listener to unregister. 85 */ 86 public abstract void unregisterDisplayTransactionListener(DisplayTransactionListener listener); 87 88 /** 89 * Overrides the display information of a particular logical display. 90 * This is used by the window manager to control the size and characteristics 91 * of the default display. It is expected to apply the requested change 92 * to the display information synchronously so that applications will immediately 93 * observe the new state. 94 * 95 * NOTE: This method must be the only entry point by which the window manager 96 * influences the logical configuration of displays. 97 * 98 * @param displayId The logical display id. 99 * @param info The new data to be stored. 100 */ 101 public abstract void setDisplayInfoOverrideFromWindowManager( 102 int displayId, DisplayInfo info); 103 104 /** 105 * Get current display info without override from WindowManager. 106 * Current implementation of LogicalDisplay#getDisplayInfoLocked() always returns display info 107 * with overrides from WM if set. This method can be used for getting real display size without 108 * overrides to determine if real changes to display metrics happened. 109 * @param displayId Id of the target display. 110 * @param outInfo {@link DisplayInfo} to fill. 111 */ 112 public abstract void getNonOverrideDisplayInfo(int displayId, DisplayInfo outInfo); 113 114 /** 115 * Called by the window manager to perform traversals while holding a 116 * surface flinger transaction. 117 */ 118 public abstract void performTraversalInTransactionFromWindowManager(); 119 120 /** 121 * Tells the display manager about properties of the display that depend on the windows on it. 122 * This includes whether there is interesting unique content on the specified logical display, 123 * and whether the one of the windows has a preferred refresh rate. 124 * <p> 125 * If the display has unique content, then the display manager arranges for it 126 * to be presented on a physical display if appropriate. Otherwise, the display manager 127 * may choose to make the physical display mirror some other logical display. 128 * </p> 129 * 130 * <p> 131 * If one of the windows on the display has a preferred refresh rate that's supported by the 132 * display, then the display manager will request its use. 133 * </p> 134 * 135 * @param displayId The logical display id to update. 136 * @param hasContent True if the logical display has content. This is used to control automatic 137 * mirroring. 138 * @param requestedRefreshRate The preferred refresh rate for the top-most visible window that 139 * has a preference. 140 * @param requestedModeId The preferred mode id for the top-most visible window that has a 141 * preference. 142 * @param inTraversal True if called from WindowManagerService during a window traversal 143 * prior to call to performTraversalInTransactionFromWindowManager. 144 */ 145 public abstract void setDisplayProperties(int displayId, boolean hasContent, 146 float requestedRefreshRate, int requestedModeId, boolean inTraversal); 147 148 /** 149 * Applies an offset to the contents of a display, for example to avoid burn-in. 150 * <p> 151 * TODO: Technically this should be associated with a physical rather than logical 152 * display but this is good enough for now. 153 * </p> 154 * 155 * @param displayId The logical display id to update. 156 * @param x The X offset by which to shift the contents of the display. 157 * @param y The Y offset by which to shift the contents of the display. 158 */ 159 public abstract void setDisplayOffsets(int displayId, int x, int y); 160 161 /** 162 * Provide a list of UIDs that are present on the display and are allowed to access it. 163 * 164 * @param displayAccessUIDs Mapping displayId -> int array of UIDs. 165 */ 166 public abstract void setDisplayAccessUIDs(SparseArray<IntArray> displayAccessUIDs); 167 168 /** 169 * Check if specified UID's content is present on display and should be granted access to it. 170 * 171 * @param uid UID to be checked. 172 * @param displayId id of the display where presence of the content is checked. 173 * */ 174 public abstract boolean isUidPresentOnDisplay(int uid, int displayId); 175 176 /** 177 * Describes the requested power state of the display. 178 * 179 * This object is intended to describe the general characteristics of the 180 * power state, such as whether the screen should be on or off and the current 181 * brightness controls leaving the DisplayPowerController to manage the 182 * details of how the transitions between states should occur. The goal is for 183 * the PowerManagerService to focus on the global power state and not 184 * have to micro-manage screen off animations, auto-brightness and other effects. 185 */ 186 public static final class DisplayPowerRequest { 187 // Policy: Turn screen off as if the user pressed the power button 188 // including playing a screen off animation if applicable. 189 public static final int POLICY_OFF = 0; 190 // Policy: Enable dozing and always-on display functionality. 191 public static final int POLICY_DOZE = 1; 192 // Policy: Make the screen dim when the user activity timeout is 193 // about to expire. 194 public static final int POLICY_DIM = 2; 195 // Policy: Make the screen bright as usual. 196 public static final int POLICY_BRIGHT = 3; 197 // Policy: Keep the screen and display optimized for VR mode. 198 public static final int POLICY_VR = 4; 199 200 // The basic overall policy to apply: off, doze, dim or bright. 201 public int policy; 202 203 // If true, the proximity sensor overrides the screen state when an object is 204 // nearby, turning it off temporarily until the object is moved away. 205 public boolean useProximitySensor; 206 207 // The desired screen brightness in the range 0 (minimum / off) to 255 (brightest). 208 // The display power controller may choose to clamp the brightness. 209 // When auto-brightness is enabled, this field should specify a nominal default 210 // value to use while waiting for the light sensor to report enough data. 211 public int screenBrightness; 212 213 // The screen auto-brightness adjustment factor in the range -1 (dimmer) to 1 (brighter). 214 public float screenAutoBrightnessAdjustment; 215 216 // Set to true if screenBrightness and screenAutoBrightnessAdjustment were both 217 // set by the user as opposed to being programmatically controlled by apps. 218 public boolean brightnessSetByUser; 219 220 // If true, enables automatic brightness control. 221 public boolean useAutoBrightness; 222 223 // If true, scales the brightness to half of desired. 224 public boolean lowPowerMode; 225 226 // The factor to adjust the screen brightness in low power mode in the range 227 // 0 (screen off) to 1 (no change) 228 public float screenLowPowerBrightnessFactor; 229 230 // If true, applies a brightness boost. 231 public boolean boostScreenBrightness; 232 233 // If true, prevents the screen from completely turning on if it is currently off. 234 // The display does not enter a "ready" state if this flag is true and screen on is 235 // blocked. The window manager policy blocks screen on while it prepares the keyguard to 236 // prevent the user from seeing intermediate updates. 237 // 238 // Technically, we may not block the screen itself from turning on (because that introduces 239 // extra unnecessary latency) but we do prevent content on screen from becoming 240 // visible to the user. 241 public boolean blockScreenOn; 242 243 // Overrides the policy for adjusting screen brightness and state while dozing. 244 public int dozeScreenBrightness; 245 public int dozeScreenState; 246 247 public DisplayPowerRequest() { 248 policy = POLICY_BRIGHT; 249 useProximitySensor = false; 250 screenBrightness = PowerManager.BRIGHTNESS_ON; 251 screenAutoBrightnessAdjustment = 0.0f; 252 screenLowPowerBrightnessFactor = 0.5f; 253 useAutoBrightness = false; 254 blockScreenOn = false; 255 dozeScreenBrightness = PowerManager.BRIGHTNESS_DEFAULT; 256 dozeScreenState = Display.STATE_UNKNOWN; 257 } 258 259 public DisplayPowerRequest(DisplayPowerRequest other) { 260 copyFrom(other); 261 } 262 263 public boolean isBrightOrDim() { 264 return policy == POLICY_BRIGHT || policy == POLICY_DIM; 265 } 266 267 public boolean isVr() { 268 return policy == POLICY_VR; 269 } 270 271 public void copyFrom(DisplayPowerRequest other) { 272 policy = other.policy; 273 useProximitySensor = other.useProximitySensor; 274 screenBrightness = other.screenBrightness; 275 screenAutoBrightnessAdjustment = other.screenAutoBrightnessAdjustment; 276 screenLowPowerBrightnessFactor = other.screenLowPowerBrightnessFactor; 277 brightnessSetByUser = other.brightnessSetByUser; 278 useAutoBrightness = other.useAutoBrightness; 279 blockScreenOn = other.blockScreenOn; 280 lowPowerMode = other.lowPowerMode; 281 boostScreenBrightness = other.boostScreenBrightness; 282 dozeScreenBrightness = other.dozeScreenBrightness; 283 dozeScreenState = other.dozeScreenState; 284 } 285 286 @Override 287 public boolean equals(Object o) { 288 return o instanceof DisplayPowerRequest 289 && equals((DisplayPowerRequest)o); 290 } 291 292 public boolean equals(DisplayPowerRequest other) { 293 return other != null 294 && policy == other.policy 295 && useProximitySensor == other.useProximitySensor 296 && screenBrightness == other.screenBrightness 297 && screenAutoBrightnessAdjustment == other.screenAutoBrightnessAdjustment 298 && screenLowPowerBrightnessFactor 299 == other.screenLowPowerBrightnessFactor 300 && brightnessSetByUser == other.brightnessSetByUser 301 && useAutoBrightness == other.useAutoBrightness 302 && blockScreenOn == other.blockScreenOn 303 && lowPowerMode == other.lowPowerMode 304 && boostScreenBrightness == other.boostScreenBrightness 305 && dozeScreenBrightness == other.dozeScreenBrightness 306 && dozeScreenState == other.dozeScreenState; 307 } 308 309 @Override 310 public int hashCode() { 311 return 0; // don't care 312 } 313 314 @Override 315 public String toString() { 316 return "policy=" + policyToString(policy) 317 + ", useProximitySensor=" + useProximitySensor 318 + ", screenBrightness=" + screenBrightness 319 + ", screenAutoBrightnessAdjustment=" + screenAutoBrightnessAdjustment 320 + ", screenLowPowerBrightnessFactor=" + screenLowPowerBrightnessFactor 321 + ", brightnessSetByUser=" + brightnessSetByUser 322 + ", useAutoBrightness=" + useAutoBrightness 323 + ", blockScreenOn=" + blockScreenOn 324 + ", lowPowerMode=" + lowPowerMode 325 + ", boostScreenBrightness=" + boostScreenBrightness 326 + ", dozeScreenBrightness=" + dozeScreenBrightness 327 + ", dozeScreenState=" + Display.stateToString(dozeScreenState); 328 } 329 330 public static String policyToString(int policy) { 331 switch (policy) { 332 case POLICY_OFF: 333 return "OFF"; 334 case POLICY_DOZE: 335 return "DOZE"; 336 case POLICY_DIM: 337 return "DIM"; 338 case POLICY_BRIGHT: 339 return "BRIGHT"; 340 case POLICY_VR: 341 return "VR"; 342 default: 343 return Integer.toString(policy); 344 } 345 } 346 } 347 348 /** 349 * Asynchronous callbacks from the power controller to the power manager service. 350 */ 351 public interface DisplayPowerCallbacks { 352 void onStateChanged(); 353 void onProximityPositive(); 354 void onProximityNegative(); 355 void onDisplayStateChange(int state); // one of the Display state constants 356 357 void acquireSuspendBlocker(); 358 void releaseSuspendBlocker(); 359 } 360 361 /** 362 * Called within a Surface transaction whenever the size or orientation of a 363 * display may have changed. Provides an opportunity for the client to 364 * update the position of its surfaces as part of the same transaction. 365 */ 366 public interface DisplayTransactionListener { 367 void onDisplayTransaction(); 368 } 369 } 370
