1 /* 2 * Copyright (C) 2022 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 com.android.server.display; 18 19 import android.content.pm.ParceledListSlice; 20 import android.hardware.display.AmbientBrightnessDayStats; 21 import android.hardware.display.BrightnessChangeEvent; 22 import android.hardware.display.BrightnessConfiguration; 23 import android.hardware.display.BrightnessInfo; 24 import android.hardware.display.DisplayManagerInternal; 25 import android.os.PowerManager; 26 import android.view.Display; 27 28 import java.io.PrintWriter; 29 30 /** 31 * An interface to manage the display's power state and brightness 32 */ 33 public interface DisplayPowerControllerInterface { 34 /** 35 * Notified when the display is changed. 36 * 37 * We use this to apply any changes that might be needed when displays get swapped on foldable 38 * devices, when layouts change, etc. 39 * 40 * Must be called while holding the SyncRoot lock. 41 * 42 * @param hbmInfo The high brightness mode metadata, like 43 * remaining time and hbm events, for the corresponding 44 * physical display, to make sure we stay within the safety margins. 45 * @param leadDisplayId The display who is considered our "leader" for things like brightness. 46 */ onDisplayChanged(HighBrightnessModeMetadata hbmInfo, int leadDisplayId)47 void onDisplayChanged(HighBrightnessModeMetadata hbmInfo, int leadDisplayId); 48 49 /** 50 * Unregisters all listeners and interrupts all running threads; halting future work. 51 * 52 * This method should be called when the DisplayPowerController is no longer in use; i.e. when 53 * the display has been removed. 54 */ stop()55 void stop(); 56 57 /** 58 * Used to update the display's BrightnessConfiguration 59 * @param config The new BrightnessConfiguration 60 */ setBrightnessConfiguration(BrightnessConfiguration config, boolean shouldResetShortTermModel)61 void setBrightnessConfiguration(BrightnessConfiguration config, 62 boolean shouldResetShortTermModel); 63 64 /** 65 * Used to set the ambient color temperature of the Display 66 * @param ambientColorTemperature The target ambientColorTemperature 67 */ setAmbientColorTemperatureOverride(float ambientColorTemperature)68 void setAmbientColorTemperatureOverride(float ambientColorTemperature); 69 70 /** 71 * Used to decide the associated AutomaticBrightnessController's BrightnessMode 72 * @param mode The auto-brightness mode 73 */ setAutomaticScreenBrightnessMode( @utomaticBrightnessController.AutomaticBrightnessMode int mode)74 void setAutomaticScreenBrightnessMode( 75 @AutomaticBrightnessController.AutomaticBrightnessMode int mode); 76 77 /** 78 * Used to enable/disable the logging of the WhileBalance associated entities 79 * @param enabled Flag which represents if the logging is the be enabled 80 */ setDisplayWhiteBalanceLoggingEnabled(boolean enabled)81 void setDisplayWhiteBalanceLoggingEnabled(boolean enabled); 82 83 /** 84 * Used to dump the state. 85 * @param writer The PrintWriter used to dump the state. 86 */ dump(PrintWriter writer)87 void dump(PrintWriter writer); 88 89 /** 90 * Used to get the ambient brightness stats 91 */ getAmbientBrightnessStats(int userId)92 ParceledListSlice<AmbientBrightnessDayStats> getAmbientBrightnessStats(int userId); 93 94 /** 95 * Get the default brightness configuration 96 */ getDefaultBrightnessConfiguration()97 BrightnessConfiguration getDefaultBrightnessConfiguration(); 98 99 /** 100 * Set the screen brightness of the associated display 101 * @param brightness The value to which the brightness is to be set 102 */ setBrightness(float brightness)103 void setBrightness(float brightness); 104 105 /** 106 * Set the screen brightness of the associated display 107 * @param brightness The value to which the brightness is to be set 108 * @param userSerial The user for which the brightness value is to be set. 109 */ setBrightness(float brightness, int userSerial)110 void setBrightness(float brightness, int userSerial); 111 112 /** 113 * Checks if the proximity sensor is available 114 */ isProximitySensorAvailable()115 boolean isProximitySensorAvailable(); 116 117 /** 118 * Persist the brightness slider events and ambient brightness stats to disk. 119 */ persistBrightnessTrackerState()120 void persistBrightnessTrackerState(); 121 122 /** 123 * Ignores the proximity sensor until the sensor state changes, but only if the sensor is 124 * currently enabled and forcing the screen to be dark. 125 */ ignoreProximitySensorUntilChanged()126 void ignoreProximitySensorUntilChanged(); 127 128 /** 129 * Requests a new power state. 130 * 131 * @param request The requested power state. 132 * @param waitForNegativeProximity If true, issues a request to wait for 133 * negative proximity before turning the screen back on, 134 * assuming the screen was turned off by the proximity sensor. 135 * @return True if display is ready, false if there are important changes that must 136 * be made asynchronously. 137 */ requestPowerState(DisplayManagerInternal.DisplayPowerRequest request, boolean waitForNegativeProximity)138 boolean requestPowerState(DisplayManagerInternal.DisplayPowerRequest request, 139 boolean waitForNegativeProximity); 140 141 /** 142 * Overrides the current doze screen state. 143 * 144 * @param displayState the new doze display state. 145 * @param reason the reason behind the new doze display state. 146 */ overrideDozeScreenState(int displayState, @Display.StateReason int reason)147 void overrideDozeScreenState(int displayState, @Display.StateReason int reason); 148 setDisplayOffloadSession(DisplayManagerInternal.DisplayOffloadSession session)149 void setDisplayOffloadSession(DisplayManagerInternal.DisplayOffloadSession session); 150 151 /** 152 * Sets up the temporary autobrightness adjustment when the user is yet to settle down to a 153 * value. 154 */ setTemporaryAutoBrightnessAdjustment(float adjustment)155 void setTemporaryAutoBrightnessAdjustment(float adjustment); 156 157 /** 158 * Sets temporary brightness from the offload chip until we get a brightness value from 159 * the light sensor. 160 * @param brightness The brightness value between {@link PowerManager.BRIGHTNESS_MIN} and 161 * {@link PowerManager.BRIGHTNESS_MAX}. Values outside of that range will be ignored. 162 */ setBrightnessFromOffload(float brightness)163 void setBrightnessFromOffload(float brightness); 164 165 /** 166 * Gets the screen brightness setting 167 */ getScreenBrightnessSetting()168 float getScreenBrightnessSetting(); 169 170 /** 171 * Gets the brightness value used when the device is in doze 172 */ getDozeBrightnessForOffload()173 float getDozeBrightnessForOffload(); 174 175 /** 176 * Sets up the temporary brightness for the associated display 177 */ setTemporaryBrightness(float brightness)178 void setTemporaryBrightness(float brightness); 179 180 /** 181 * Gets the associated {@link BrightnessInfo} 182 */ getBrightnessInfo()183 BrightnessInfo getBrightnessInfo(); 184 185 /** 186 * Get the {@link BrightnessChangeEvent}s for the specified user. 187 */ getBrightnessEvents(int userId, boolean hasUsageStats)188 ParceledListSlice<BrightnessChangeEvent> getBrightnessEvents(int userId, boolean hasUsageStats); 189 190 /** 191 * Sets up the logging for the associated {@link AutomaticBrightnessController} 192 * @param enabled Flag to represent if the logging is to be enabled 193 */ setAutoBrightnessLoggingEnabled(boolean enabled)194 void setAutoBrightnessLoggingEnabled(boolean enabled); 195 196 /** 197 * Handles the changes to be done to update the brightness when the user is changed 198 * @param newUserId The new userId 199 * @param userSerial The serial number of the new user 200 * @param newBrightness The brightness for the new user 201 */ onSwitchUser(int newUserId, int userSerial, float newBrightness)202 void onSwitchUser(int newUserId, int userSerial, float newBrightness); 203 204 /** 205 * Get the ID of the display associated with this DPC. 206 * @return The display ID 207 */ getDisplayId()208 int getDisplayId(); 209 210 /** 211 * Get the ID of the display that is the leader of this DPC. 212 * 213 * Note that this is different than the display associated with the DPC. The leader is another 214 * display which we follow for things like brightness. 215 * 216 * Must be called while holding the SyncRoot lock. 217 */ getLeadDisplayId()218 int getLeadDisplayId(); 219 220 /** 221 * Set the brightness to follow if this is an additional display in a set of concurrent 222 * displays. 223 * @param leadDisplayBrightness The brightness of the lead display in the set of concurrent 224 * displays 225 * @param nits The brightness value in nits if the device supports nits. Set to a negative 226 * number otherwise. 227 * @param ambientLux The lux value that will be passed to {@link HighBrightnessModeController} 228 * @param slowChange Indicates whether we should slowly animate to the given brightness value. 229 */ setBrightnessToFollow(float leadDisplayBrightness, float nits, float ambientLux, boolean slowChange)230 void setBrightnessToFollow(float leadDisplayBrightness, float nits, float ambientLux, 231 boolean slowChange); 232 233 /** 234 * Add an additional display that will copy the brightness value from this display. This is used 235 * when the device is in concurrent displays mode. 236 * @param follower The DPC that should copy the brightness value from this DPC 237 */ addDisplayBrightnessFollower(DisplayPowerControllerInterface follower)238 void addDisplayBrightnessFollower(DisplayPowerControllerInterface follower); 239 240 /** 241 * Removes the given display from the list of brightness followers. 242 * @param follower The DPC to remove from the followers list 243 */ removeDisplayBrightnessFollower(DisplayPowerControllerInterface follower)244 void removeDisplayBrightnessFollower(DisplayPowerControllerInterface follower); 245 246 /** 247 * Indicate that boot has been completed and the screen is ready to update. 248 */ onBootCompleted()249 void onBootCompleted(); 250 251 /** 252 * Get the brightness levels used to determine automatic brightness based on lux levels. 253 * @param mode The auto-brightness mode 254 * @return The brightness levels for the specified mode. The values are between 255 * {@link PowerManager.BRIGHTNESS_MIN} and {@link PowerManager.BRIGHTNESS_MAX}. 256 */ getAutoBrightnessLevels( @utomaticBrightnessController.AutomaticBrightnessMode int mode)257 float[] getAutoBrightnessLevels( 258 @AutomaticBrightnessController.AutomaticBrightnessMode int mode); 259 260 /** 261 * Get the lux levels used to determine automatic brightness. 262 * @param mode The auto-brightness mode 263 * @return The lux levels for the specified mode 264 */ getAutoBrightnessLuxLevels( @utomaticBrightnessController.AutomaticBrightnessMode int mode)265 float[] getAutoBrightnessLuxLevels( 266 @AutomaticBrightnessController.AutomaticBrightnessMode int mode); 267 } 268