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