* The display power controller makes a copy of the provided object and then * begins adjusting the power state to match what was requested. *
* * @param groupId The identifier for the display group being requested to change power state * @param request The requested power state. * @param waitForNegativeProximity If {@code true}, issues a request to wait for * negative proximity before turning the screen back on, assuming the screen * was turned off by the proximity sensor. * @return {@code true} if display group is ready, {@code false} if there are important * changes that must be made asynchronously (such as turning the screen on), in which case * the caller should grab a wake lock, watch for {@link DisplayPowerCallbacks#onStateChanged} * then try the request again later until the state converges. If the provided {@code groupId} * cannot be found then {@code true} will be returned. */ public abstract boolean requestPowerState(int groupId, DisplayPowerRequest request, boolean waitForNegativeProximity); /** * Returns {@code true} if the proximity sensor screen-off function is available for the given * display. */ public abstract boolean isProximitySensorAvailable(int displayId); /** * Registers a display group listener which will be informed of the addition, removal, or change * of display groups. * * @param listener The listener to register. */ public abstract void registerDisplayGroupListener(DisplayGroupListener listener); /** * Unregisters a display group listener which will be informed of the addition, removal, or * change of display groups. * * @param listener The listener to unregister. */ public abstract void unregisterDisplayGroupListener(DisplayGroupListener listener); /** * Screenshot for internal system-only use such as rotation, etc. This method includes secure * layers and the result should never be exposed to non-system applications. This method does * not apply any rotation and provides the output in natural orientation. * * @param displayId The display id to take the screenshot of. * @return The buffer or null if we have failed. */ public abstract ScreenCaptureInternal.ScreenshotHardwareBuffer systemScreenshot(int displayId); /** * Captures a screenshot of the specified display for internal system use. * *This method allows for more granular control over the screenshot process
* compared to {@link #systemScreenshot(int)}.
*
* @param displayId The display id to take the screenshot of.
* @param argsBuilder A {@link ScreenCaptureInternal.DisplayCaptureArgs.Builder}
* to specify screenshot parameters.
* @param callback A {@link ScreenCaptureInternal.ScreenCaptureListener} to receive
* the screenshot result or an error.
*/
public abstract void systemScreenshot(
int displayId,
ScreenCaptureInternal.DisplayCaptureArgs.Builder argsBuilder,
ScreenCaptureInternal.ScreenCaptureListener callback);
/**
* General screenshot functionality that excludes secure layers and applies appropriate rotation
* that the device is currently in.
*
* @param displayId The display id to take the screenshot of.
* @return The buffer or null if we have failed.
*/
public abstract ScreenCaptureInternal.ScreenshotHardwareBuffer userScreenshot(int displayId);
/**
* Returns information about the specified logical display.
*
* @param displayId The logical display id.
* @return The logical display info, or null if the display does not exist. The
* returned object must be treated as immutable.
*/
public abstract DisplayInfo getDisplayInfo(int displayId);
/**
* Returns a set of DisplayInfo, for the states that may be assumed by either the given display,
* or any other display within that display's group.
*
* @param displayId The logical display id to fetch DisplayInfo for.
*/
public abstract Set NOTE: This method must be the only entry point by which the window manager
* influences the logical configuration of displays.
*
* @param displayId The logical display id.
* @param info The new data to be stored.
*/
public abstract void setDisplayInfoOverrideFromWindowManager(
int displayId, DisplayInfo info);
/**
* Get current display info without override from WindowManager.
* Current implementation of LogicalDisplay#getDisplayInfoLocked() always returns display info
* with overrides from WM if set. This method can be used for getting real display size without
* overrides to determine if real changes to display metrics happened.
* @param displayId Id of the target display.
* @param outInfo {@link DisplayInfo} to fill.
*/
public abstract void getNonOverrideDisplayInfo(int displayId, DisplayInfo outInfo);
/**
* Called by the window manager to perform traversals while holding a
* surface flinger transaction.
* @param t The default transaction.
* @param displayTransactions The transactions mapped by display id.
*/
public abstract void performTraversal(Transaction t,
SparseArray
* If the display has unique content, then the display manager arranges for it
* to be presented on a physical display if appropriate. Otherwise, the display manager
* may choose to make the physical display mirror some other logical display.
*
* If one of the windows on the display has a preferred refresh rate that's supported by the
* display, then the display manager will request its use.
*
* TODO: Technically this should be associated with a physical rather than logical
* display but this is good enough for now.
* A cap of {@code 1f} will remove the cap.
*
* @param displayId id of the display to cap the maximum brightness for
* @param cap the brightness cap between {@code 0f} and {@code 1f}
* @param reason reason for capping brightness. Using the same reason again for a display
* replaces the previous cap
*/
public abstract void setBrightnessCap(
int displayId,
@FloatRange(from = 0f, to = 1f) float cap,
@BrightnessInfo.BrightnessMaxReason int reason);
/**
* Notifies the display manager that resource overlays have changed.
*/
public abstract void onOverlayChanged();
/**
* Get the attributes available for display color sampling.
* @param displayId id of the display to collect the sample from.
*
* @return The attributes the display supports, or null if sampling is not supported.
*/
@Nullable
public abstract DisplayedContentSamplingAttributes getDisplayedContentSamplingAttributes(
int displayId);
/**
* Enable or disable the collection of color samples.
*
* @param displayId id of the display to collect the sample from.
* @param componentMask a bitmask of the color channels to collect samples for, or zero for all
* available.
* @param maxFrames maintain a ringbuffer of the last maxFrames.
* @param enable True to enable, False to disable.
*
* @return True if sampling was enabled, false if failure.
*/
public abstract boolean setDisplayedContentSamplingEnabled(
int displayId, boolean enable, int componentMask, int maxFrames);
/**
* Accesses the color histogram statistics of displayed frames on devices that support sampling.
*
* @param displayId id of the display to collect the sample from
* @param maxFrames limit the statistics to the last maxFrames number of frames.
* @param timestamp discard statistics that were collected prior to timestamp, where timestamp
* is given as CLOCK_MONOTONIC.
* @return The statistics representing a histogram of the color distribution of the frames
* displayed on-screen, or null if sampling is not supported.
*/
@Nullable
public abstract DisplayedContentSample getDisplayedContentSample(
int displayId, long maxFrames, long timestamp);
/**
* Temporarily ignore proximity-sensor-based display behavior until there is a change
* to the proximity sensor state. This allows the display to turn back on even if something
* is obstructing the proximity sensor.
*/
public abstract void ignoreProximitySensorUntilChanged();
/**
* Sets the persistent connection preference for a given display. This preference
* determines whether to show a dialog, mirror, or use desktop mode automatically.
*
* @param uniqueId The unique ID of the display.
* @param preference The integer constant for the new preference to save.
* @hide
*/
public abstract void setConnectionPreference(String uniqueId, int preference);
/**
* Retrieves the saved connection preference for a given display.
*
* @param uniqueId The unique ID of the display.
* @return The integer constant for the saved preference.
* @hide
*/
public abstract int getConnectionPreference(String uniqueId);
/**
* Returns the refresh rate switching type.
*/
@DisplayManager.SwitchingType
public abstract int getRefreshRateSwitchingType();
/**
* TODO: b/191384041 - Replace this with getRefreshRateLimitations()
* Return the refresh rate restriction for the specified display and sensor pairing. If the
* specified sensor is identified as an associated sensor in the specified display's
* display-device-config file, then return any refresh rate restrictions that it might define.
* If no restriction is specified, or the sensor is not associated with the display, then null
* will be returned.
*
* @param displayId The display to check against.
* @param name The name of the sensor.
* @param type The type of sensor.
*
* @return The min/max refresh-rate restriction as a pair of floats, or {@code null} if not
* restricted.
*/
public abstract RefreshRateRange getRefreshRateForDisplayAndSensor(
int displayId, String name, String type);
/**
* Returns a list of various refresh rate limitations for the specified display.
*
* @param displayId The display to get limitations for.
*
* @return a list of {@link RefreshRateLimitation}s describing the various limits.
*/
public abstract List The key of the array is the displayId. If a displayId is missing from the array, this is
* equivalent to clearing any existing brightness overrides for that display.
*
* This method must only be called by the window manager.
*/
public abstract void setScreenBrightnessOverrideFromWindowManager(
SparseArray This object is intended to describe the general characteristics of the
* power state, such as whether the screen should be on or off and the current
* brightness controls leaving the DisplayPowerController to manage the
* details of how the transitions between states should occur. The goal is for
* the PowerManagerService to focus on the global power state and not
* have to micro-manage screen off animations, auto-brightness and other effects.
*/
public static class DisplayPowerRequest {
// Policy: Turn screen off as if the user pressed the power button
// including playing a screen off animation if applicable.
public static final int POLICY_OFF = 0;
// Policy: Enable dozing and always-on display functionality.
public static final int POLICY_DOZE = 1;
// Policy: Make the screen dim when the user activity timeout is
// about to expire.
public static final int POLICY_DIM = 2;
// Policy: Make the screen bright as usual.
public static final int POLICY_BRIGHT = 3;
// The maximum policy constant. Useful for iterating through all constants in tests.
public static final int POLICY_MAX = POLICY_BRIGHT;
// The basic overall policy to apply: off, doze, dim or bright.
public int policy;
// The reason behind the current policy.
@Display.StateReason
public int policyReason;
// If true, the proximity sensor overrides the screen state when an object is
// nearby, turning it off temporarily until the object is moved away.
public boolean useProximitySensor;
// A global override of the screen brightness, applied to all displays.
// Set to PowerManager.BRIGHTNESS_INVALID if there's no override.
public float screenBrightnessOverride;
// Tag used to identify the reason for the global brightness override.
public CharSequence screenBrightnessOverrideTag;
// An override of the screen auto-brightness adjustment factor in the range -1 (dimmer) to
// 1 (brighter). Set to Float.NaN if there's no override.
public float screenAutoBrightnessAdjustmentOverride;
// If true, scales the brightness to a fraction of desired (as defined by
// screenLowPowerBrightnessFactor).
public boolean lowPowerMode;
// The factor to adjust the screen brightness in low power mode in the range
// 0 (screen off) to 1 (no change)
public float screenLowPowerBrightnessFactor;
// If true, applies a brightness boost.
public boolean boostScreenBrightness;
// If true, prevents the screen from completely turning on if it is currently off.
// The display does not enter a "ready" state if this flag is true and screen on is
// blocked. The window manager policy blocks screen on while it prepares the keyguard to
// prevent the user from seeing intermediate updates.
//
// Technically, we may not block the screen itself from turning on (because that introduces
// extra unnecessary latency) but we do prevent content on screen from becoming
// visible to the user.
public boolean blockScreenOn;
// Overrides the policy for adjusting screen brightness and state while dozing.
public int dozeScreenState;
public float dozeScreenBrightness;
public int dozeScreenStateReason;
// Override that makes display use normal brightness while dozing.
public boolean useNormalBrightnessForDoze;
public DisplayPowerRequest() {
policy = POLICY_BRIGHT;
policyReason = Display.STATE_REASON_DEFAULT_POLICY;
useProximitySensor = false;
screenBrightnessOverride = PowerManager.BRIGHTNESS_INVALID_FLOAT;
screenAutoBrightnessAdjustmentOverride = Float.NaN;
screenLowPowerBrightnessFactor = 0.5f;
blockScreenOn = false;
dozeScreenBrightness = PowerManager.BRIGHTNESS_INVALID_FLOAT;
dozeScreenState = Display.STATE_UNKNOWN;
dozeScreenStateReason = Display.STATE_REASON_UNKNOWN;
}
public DisplayPowerRequest(DisplayPowerRequest other) {
copyFrom(other);
}
public boolean isBrightOrDim() {
return policy == POLICY_BRIGHT || policy == POLICY_DIM;
}
public void copyFrom(DisplayPowerRequest other) {
policy = other.policy;
policyReason = other.policyReason;
useProximitySensor = other.useProximitySensor;
screenBrightnessOverride = other.screenBrightnessOverride;
screenBrightnessOverrideTag = other.screenBrightnessOverrideTag;
screenAutoBrightnessAdjustmentOverride = other.screenAutoBrightnessAdjustmentOverride;
screenLowPowerBrightnessFactor = other.screenLowPowerBrightnessFactor;
blockScreenOn = other.blockScreenOn;
lowPowerMode = other.lowPowerMode;
boostScreenBrightness = other.boostScreenBrightness;
dozeScreenBrightness = other.dozeScreenBrightness;
dozeScreenState = other.dozeScreenState;
dozeScreenStateReason = other.dozeScreenStateReason;
useNormalBrightnessForDoze = other.useNormalBrightnessForDoze;
}
@Override
public boolean equals(@Nullable Object o) {
return o instanceof DisplayPowerRequest
&& equals((DisplayPowerRequest)o);
}
public boolean equals(DisplayPowerRequest other) {
return other != null
&& policy == other.policy
&& useProximitySensor == other.useProximitySensor
&& floatEquals(screenBrightnessOverride, other.screenBrightnessOverride)
&& Objects.equals(screenBrightnessOverrideTag,
other.screenBrightnessOverrideTag)
&& floatEquals(screenAutoBrightnessAdjustmentOverride,
other.screenAutoBrightnessAdjustmentOverride)
&& screenLowPowerBrightnessFactor
== other.screenLowPowerBrightnessFactor
&& blockScreenOn == other.blockScreenOn
&& lowPowerMode == other.lowPowerMode
&& boostScreenBrightness == other.boostScreenBrightness
&& floatEquals(dozeScreenBrightness, other.dozeScreenBrightness)
&& dozeScreenState == other.dozeScreenState
&& dozeScreenStateReason == other.dozeScreenStateReason
&& useNormalBrightnessForDoze == other.useNormalBrightnessForDoze;
}
private boolean floatEquals(float f1, float f2) {
return f1 == f2 || Float.isNaN(f1) && Float.isNaN(f2);
}
@Override
public int hashCode() {
return 0; // don't care
}
@Override
public String toString() {
return "policy=" + policyToString(policy)
+ ", useProximitySensor=" + useProximitySensor
+ ", screenBrightnessOverride=" + screenBrightnessOverride
+ ", screenAutoBrightnessAdjustmentOverride="
+ screenAutoBrightnessAdjustmentOverride
+ ", screenLowPowerBrightnessFactor=" + screenLowPowerBrightnessFactor
+ ", blockScreenOn=" + blockScreenOn
+ ", lowPowerMode=" + lowPowerMode
+ ", boostScreenBrightness=" + boostScreenBrightness
+ ", dozeScreenBrightness=" + dozeScreenBrightness
+ ", dozeScreenState=" + Display.stateToString(dozeScreenState)
+ ", dozeScreenStateReason="
+ Display.stateReasonToString(dozeScreenStateReason)
+ ", useNormalBrightnessForDoze=" + useNormalBrightnessForDoze;
}
public static String policyToString(int policy) {
switch (policy) {
case POLICY_OFF:
return "OFF";
case POLICY_DOZE:
return "DOZE";
case POLICY_DIM:
return "DIM";
case POLICY_BRIGHT:
return "BRIGHT";
default:
return Integer.toString(policy);
}
}
}
/**
* Asynchronous callbacks from the power controller to the power manager service.
*/
public interface DisplayPowerCallbacks {
void onStateChanged();
void onProximityPositive();
void onProximityNegative();
void onDisplayStateChange(boolean allInactive, boolean allOff);
/**
* Acquires a suspend blocker with a specified label.
*
* @param id A logging label for the acquisition.
*/
void acquireSuspendBlocker(String id);
/**
* Releases a suspend blocker with a specified label.
*
* @param id A logging label for the release.
*/
void releaseSuspendBlocker(String id);
}
/**
* Called within a Surface transaction whenever the size or orientation of a
* display may have changed. Provides an opportunity for the client to
* update the position of its surfaces as part of the same transaction.
*/
public interface DisplayTransactionListener {
void onDisplayTransaction(Transaction t);
}
/**
* Called when there are changes to {@link com.android.server.display.DisplayGroup
* DisplayGroups}.
*/
public interface DisplayGroupListener {
/**
* A new display group with the provided {@code groupId} was added.
*
*
*
*/
void onDisplayGroupAdded(int groupId);
/**
* The display group with the provided {@code groupId} was removed.
*
*
*
*/
void onDisplayGroupRemoved(int groupId);
/**
* The display group with the provided {@code groupId} has changed.
*
*
*
*/
void onDisplayGroupChanged(int groupId);
}
/**
* Describes a limitation on a display's refresh rate. Includes the allowed refresh rate
* range as well as information about when it applies, such as high-brightness-mode.
*/
public static final class RefreshRateLimitation {
@RefreshRateLimitType
public int type;
/** The range the that refresh rate should be limited to. */
public RefreshRateRange range;
public RefreshRateLimitation(@RefreshRateLimitType int type, float min, float max) {
this(type, new RefreshRateRange(min, max));
}
public RefreshRateLimitation(@RefreshRateLimitType int type, RefreshRateRange range) {
this.type = type;
this.range = range;
}
@Override
public String toString() {
return "RefreshRateLimitation(" + type + ": " + range + ")";
}
}
/**
* Class to provide Ambient sensor data using the API
* {@link DisplayManagerInternal#getAmbientLightSensorData(int)}
*/
public static final class AmbientLightSensorData {
public String sensorName;
public String sensorType;
public AmbientLightSensorData(String name, String type) {
sensorName = name;
sensorType = type;
}
@Override
public String toString() {
return "AmbientLightSensorData(" + sensorName + ", " + sensorType + ")";
}
}
/**
* Associate a internal display to a {@link DisplayOffloader}.
*
* @param displayId the id of the internal display.
* @param displayOffloader the {@link DisplayOffloader} that controls offloading ops of internal
* display whose id is displayId.
* @return a {@link DisplayOffloadSession} associated with given displayId and displayOffloader.
*/
public abstract DisplayOffloadSession registerDisplayOffloader(
int displayId, DisplayOffloader displayOffloader);
/** The callbacks that controls the entry & exit of display offloading. */
public interface DisplayOffloader {
boolean startOffload();
void stopOffload();
/**
* Called when {@link DisplayOffloadSession} tries to block screen turning on.
*
* @param unblocker a {@link Runnable} executed upon all work required before screen turning
* on is done.
*/
void onBlockingScreenOn(Runnable unblocker);
/**
* Called while display is turning to screen state other than state ON to notify that any
* pending work from the previous blockScreenOn call should have been cancelled.
*/
void cancelBlockScreenOn();
/** Whether auto brightness update in doze is allowed */
boolean allowAutoBrightnessInDoze();
}
/** A session token that associates a internal display with a {@link DisplayOffloader}. */
public interface DisplayOffloadSession {
/** Provide the display state to use in place of state DOZE. */
void setDozeStateOverride(int displayState);
/** Whether the session is active. */
boolean isActive();
/** Whether auto brightness update in doze is allowed */
boolean allowAutoBrightnessInDoze();
/**
* Update the brightness from the offload chip.
* @param brightness The brightness value between {@link PowerManager#BRIGHTNESS_MIN} and
* {@link PowerManager#BRIGHTNESS_MAX}, or
* {@link PowerManager#BRIGHTNESS_INVALID_FLOAT} which removes
* the brightness from offload. Other values will be ignored.
*/
void updateBrightness(float brightness);
/**
* Called while display is turning to state ON to leave a small period for displayoffload
* session to finish some work.
*
* @param unblocker a {@link Runnable} used by displayoffload session to notify
* {@link DisplayManager} that it can continue turning screen on.
*/
boolean blockScreenOn(Runnable unblocker);
/**
* Called while display is turning to screen state other than state ON to notify that any
* pending work from the previous blockScreenOn call should have been cancelled.
*/
void cancelBlockScreenOn();
/**
* Get the brightness levels used to determine automatic brightness based on lux levels.
* @param mode The auto-brightness mode
* (AutomaticBrightnessController.AutomaticBrightnessMode)
* @return The brightness levels for the specified mode. The values are between
* {@link PowerManager#BRIGHTNESS_MIN} and {@link PowerManager#BRIGHTNESS_MAX}.
*/
float[] getAutoBrightnessLevels(int mode);
/**
* Get the lux levels used to determine automatic brightness.
* @param mode The auto-brightness mode
* (AutomaticBrightnessController.AutomaticBrightnessMode)
* @return The lux levels for the specified mode
*/
float[] getAutoBrightnessLuxLevels(int mode);
/**
* @return The current brightness setting
*/
float getBrightness();
/**
* @return The brightness value that is used when the device is in doze
*/
float getDozeBrightness();
/** Returns whether displayoffload supports the given display state. */
static boolean isSupportedOffloadState(int displayState) {
return Display.isSuspendedState(displayState);
}
}
}