DisplayManagerInternal.java revision f974cc870635227ae13201480fb2f019d153af22
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 17package android.hardware.display; 18 19import android.hardware.SensorManager; 20import android.os.Handler; 21import android.os.PowerManager; 22import android.view.DisplayInfo; 23 24/** 25 * Display manager local system service interface. 26 * 27 * @hide Only for use within the system server. 28 */ 29public abstract class DisplayManagerInternal { 30 /** 31 * Called by the power manager to initialize power management facilities. 32 */ 33 public abstract void initPowerManagement(DisplayPowerCallbacks callbacks, 34 Handler handler, SensorManager sensorManager); 35 36 /** 37 * Called by the power manager to request a new power state. 38 * <p> 39 * The display power controller makes a copy of the provided object and then 40 * begins adjusting the power state to match what was requested. 41 * </p> 42 * 43 * @param request The requested power state. 44 * @param waitForNegativeProximity If true, issues a request to wait for 45 * negative proximity before turning the screen back on, assuming the screen 46 * was turned off by the proximity sensor. 47 * @return True if display is ready, false if there are important changes that must 48 * be made asynchronously (such as turning the screen on), in which case the caller 49 * should grab a wake lock, watch for {@link DisplayPowerCallbacks#onStateChanged()} 50 * then try the request again later until the state converges. 51 */ 52 public abstract boolean requestPowerState(DisplayPowerRequest request, 53 boolean waitForNegativeProximity); 54 55 /** 56 * Returns true if the proximity sensor screen-off function is available. 57 */ 58 public abstract boolean isProximitySensorAvailable(); 59 60 /** 61 * Returns information about the specified logical display. 62 * 63 * @param displayId The logical display id. 64 * @return The logical display info, or null if the display does not exist. The 65 * returned object must be treated as immutable. 66 */ 67 public abstract DisplayInfo getDisplayInfo(int displayId); 68 69 /** 70 * Registers a display transaction listener to provide the client a chance to 71 * update its surfaces within the same transaction as any display layout updates. 72 * 73 * @param listener The listener to register. 74 */ 75 public abstract void registerDisplayTransactionListener(DisplayTransactionListener listener); 76 77 /** 78 * Unregisters a display transaction listener to provide the client a chance to 79 * update its surfaces within the same transaction as any display layout updates. 80 * 81 * @param listener The listener to unregister. 82 */ 83 public abstract void unregisterDisplayTransactionListener(DisplayTransactionListener listener); 84 85 /** 86 * Overrides the display information of a particular logical display. 87 * This is used by the window manager to control the size and characteristics 88 * of the default display. It is expected to apply the requested change 89 * to the display information synchronously so that applications will immediately 90 * observe the new state. 91 * 92 * NOTE: This method must be the only entry point by which the window manager 93 * influences the logical configuration of displays. 94 * 95 * @param displayId The logical display id. 96 * @param info The new data to be stored. 97 */ 98 public abstract void setDisplayInfoOverrideFromWindowManager( 99 int displayId, DisplayInfo info); 100 101 /** 102 * Called by the window manager to perform traversals while holding a 103 * surface flinger transaction. 104 */ 105 public abstract void performTraversalInTransactionFromWindowManager(); 106 107 /** 108 * Tells the display manager whether there is interesting unique content on the 109 * specified logical display. This is used to control automatic mirroring. 110 * <p> 111 * If the display has unique content, then the display manager arranges for it 112 * to be presented on a physical display if appropriate. Otherwise, the display manager 113 * may choose to make the physical display mirror some other logical display. 114 * </p> 115 * 116 * @param displayId The logical display id to update. 117 * @param hasContent True if the logical display has content. 118 * @param inTraversal True if called from WindowManagerService during a window traversal 119 * prior to call to performTraversalInTransactionFromWindowManager. 120 */ 121 public abstract void setDisplayHasContent(int displayId, boolean hasContent, 122 boolean inTraversal); 123 124 /** 125 * Describes the requested power state of the display. 126 * 127 * This object is intended to describe the general characteristics of the 128 * power state, such as whether the screen should be on or off and the current 129 * brightness controls leaving the DisplayPowerController to manage the 130 * details of how the transitions between states should occur. The goal is for 131 * the PowerManagerService to focus on the global power state and not 132 * have to micro-manage screen off animations, auto-brightness and other effects. 133 */ 134 public static final class DisplayPowerRequest { 135 public static final int SCREEN_STATE_OFF = 0; 136 public static final int SCREEN_STATE_DOZE = 1; 137 public static final int SCREEN_STATE_DIM = 2; 138 public static final int SCREEN_STATE_BRIGHT = 3; 139 140 // The requested minimum screen power state: off, doze, dim or bright. 141 public int screenState; 142 143 // If true, the proximity sensor overrides the screen state when an object is 144 // nearby, turning it off temporarily until the object is moved away. 145 public boolean useProximitySensor; 146 147 // The desired screen brightness in the range 0 (minimum / off) to 255 (brightest). 148 // The display power controller may choose to clamp the brightness. 149 // When auto-brightness is enabled, this field should specify a nominal default 150 // value to use while waiting for the light sensor to report enough data. 151 public int screenBrightness; 152 153 // The screen auto-brightness adjustment factor in the range -1 (dimmer) to 1 (brighter). 154 public float screenAutoBrightnessAdjustment; 155 156 // If true, enables automatic brightness control. 157 public boolean useAutoBrightness; 158 159 //If true, scales the brightness to half of desired. 160 public boolean lowPowerMode; 161 162 // If true, prevents the screen from completely turning on if it is currently off. 163 // The display does not enter a "ready" state if this flag is true and screen on is 164 // blocked. The window manager policy blocks screen on while it prepares the keyguard to 165 // prevent the user from seeing intermediate updates. 166 // 167 // Technically, we may not block the screen itself from turning on (because that introduces 168 // extra unnecessary latency) but we do prevent content on screen from becoming 169 // visible to the user. 170 public boolean blockScreenOn; 171 172 public DisplayPowerRequest() { 173 screenState = SCREEN_STATE_BRIGHT; 174 useProximitySensor = false; 175 screenBrightness = PowerManager.BRIGHTNESS_ON; 176 screenAutoBrightnessAdjustment = 0.0f; 177 useAutoBrightness = false; 178 blockScreenOn = false; 179 } 180 181 public DisplayPowerRequest(DisplayPowerRequest other) { 182 copyFrom(other); 183 } 184 185 // Returns true if we want the screen on in any mode, including doze. 186 public boolean wantScreenOnAny() { 187 return screenState != SCREEN_STATE_OFF; 188 } 189 190 // Returns true if we want the screen on in a normal mode, excluding doze. 191 // This is usually what we want to tell the rest of the system. For compatibility 192 // reasons, we pretend the screen is off when dozing. 193 public boolean wantScreenOnNormal() { 194 return screenState == SCREEN_STATE_DIM || screenState == SCREEN_STATE_BRIGHT; 195 } 196 197 public boolean wantLightSensorEnabled() { 198 // Specifically, we don't want the light sensor while dozing. 199 return useAutoBrightness && wantScreenOnNormal(); 200 } 201 202 public void copyFrom(DisplayPowerRequest other) { 203 screenState = other.screenState; 204 useProximitySensor = other.useProximitySensor; 205 screenBrightness = other.screenBrightness; 206 screenAutoBrightnessAdjustment = other.screenAutoBrightnessAdjustment; 207 useAutoBrightness = other.useAutoBrightness; 208 blockScreenOn = other.blockScreenOn; 209 lowPowerMode = other.lowPowerMode; 210 } 211 212 @Override 213 public boolean equals(Object o) { 214 return o instanceof DisplayPowerRequest 215 && equals((DisplayPowerRequest)o); 216 } 217 218 public boolean equals(DisplayPowerRequest other) { 219 return other != null 220 && screenState == other.screenState 221 && useProximitySensor == other.useProximitySensor 222 && screenBrightness == other.screenBrightness 223 && screenAutoBrightnessAdjustment == other.screenAutoBrightnessAdjustment 224 && useAutoBrightness == other.useAutoBrightness 225 && blockScreenOn == other.blockScreenOn 226 && lowPowerMode == other.lowPowerMode; 227 } 228 229 @Override 230 public int hashCode() { 231 return 0; // don't care 232 } 233 234 @Override 235 public String toString() { 236 return "screenState=" + screenState 237 + ", useProximitySensor=" + useProximitySensor 238 + ", screenBrightness=" + screenBrightness 239 + ", screenAutoBrightnessAdjustment=" + screenAutoBrightnessAdjustment 240 + ", useAutoBrightness=" + useAutoBrightness 241 + ", blockScreenOn=" + blockScreenOn 242 + ", lowPowerMode=" + lowPowerMode; 243 } 244 } 245 246 /** 247 * Asynchronous callbacks from the power controller to the power manager service. 248 */ 249 public interface DisplayPowerCallbacks { 250 void onStateChanged(); 251 void onProximityPositive(); 252 void onProximityNegative(); 253 void onDisplayStateChange(int state); // one of the Display state constants 254 255 void acquireSuspendBlocker(); 256 void releaseSuspendBlocker(); 257 } 258 259 /** 260 * Called within a Surface transaction whenever the size or orientation of a 261 * display may have changed. Provides an opportunity for the client to 262 * update the position of its surfaces as part of the same transaction. 263 */ 264 public interface DisplayTransactionListener { 265 void onDisplayTransaction(); 266 } 267} 268