Home | History | Annotate | Download | only in display
      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.view.Display;
     23 import android.view.DisplayInfo;
     24 
     25 /**
     26  * Display manager local system service interface.
     27  *
     28  * @hide Only for use within the system server.
     29  */
     30 public 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 inTraversal True if called from WindowManagerService during a window traversal
    129      * prior to call to performTraversalInTransactionFromWindowManager.
    130      */
    131     public abstract void setDisplayProperties(int displayId, boolean hasContent,
    132             float requestedRefreshRate, boolean inTraversal);
    133 
    134     /**
    135      * Describes the requested power state of the display.
    136      *
    137      * This object is intended to describe the general characteristics of the
    138      * power state, such as whether the screen should be on or off and the current
    139      * brightness controls leaving the DisplayPowerController to manage the
    140      * details of how the transitions between states should occur.  The goal is for
    141      * the PowerManagerService to focus on the global power state and not
    142      * have to micro-manage screen off animations, auto-brightness and other effects.
    143      */
    144     public static final class DisplayPowerRequest {
    145         // Policy: Turn screen off as if the user pressed the power button
    146         // including playing a screen off animation if applicable.
    147         public static final int POLICY_OFF = 0;
    148         // Policy: Enable dozing and always-on display functionality.
    149         public static final int POLICY_DOZE = 1;
    150         // Policy: Make the screen dim when the user activity timeout is
    151         // about to expire.
    152         public static final int POLICY_DIM = 2;
    153         // Policy: Make the screen bright as usual.
    154         public static final int POLICY_BRIGHT = 3;
    155 
    156         // The basic overall policy to apply: off, doze, dim or bright.
    157         public int policy;
    158 
    159         // If true, the proximity sensor overrides the screen state when an object is
    160         // nearby, turning it off temporarily until the object is moved away.
    161         public boolean useProximitySensor;
    162 
    163         // The desired screen brightness in the range 0 (minimum / off) to 255 (brightest).
    164         // The display power controller may choose to clamp the brightness.
    165         // When auto-brightness is enabled, this field should specify a nominal default
    166         // value to use while waiting for the light sensor to report enough data.
    167         public int screenBrightness;
    168 
    169         // The screen auto-brightness adjustment factor in the range -1 (dimmer) to 1 (brighter).
    170         public float screenAutoBrightnessAdjustment;
    171 
    172         // If true, enables automatic brightness control.
    173         public boolean useAutoBrightness;
    174 
    175         // If true, scales the brightness to half of desired.
    176         public boolean lowPowerMode;
    177 
    178         // If true, applies a brightness boost.
    179         public boolean boostScreenBrightness;
    180 
    181         // If true, prevents the screen from completely turning on if it is currently off.
    182         // The display does not enter a "ready" state if this flag is true and screen on is
    183         // blocked.  The window manager policy blocks screen on while it prepares the keyguard to
    184         // prevent the user from seeing intermediate updates.
    185         //
    186         // Technically, we may not block the screen itself from turning on (because that introduces
    187         // extra unnecessary latency) but we do prevent content on screen from becoming
    188         // visible to the user.
    189         public boolean blockScreenOn;
    190 
    191         // Overrides the policy for adjusting screen brightness and state while dozing.
    192         public int dozeScreenBrightness;
    193         public int dozeScreenState;
    194 
    195         public DisplayPowerRequest() {
    196             policy = POLICY_BRIGHT;
    197             useProximitySensor = false;
    198             screenBrightness = PowerManager.BRIGHTNESS_ON;
    199             screenAutoBrightnessAdjustment = 0.0f;
    200             useAutoBrightness = false;
    201             blockScreenOn = false;
    202             dozeScreenBrightness = PowerManager.BRIGHTNESS_DEFAULT;
    203             dozeScreenState = Display.STATE_UNKNOWN;
    204         }
    205 
    206         public DisplayPowerRequest(DisplayPowerRequest other) {
    207             copyFrom(other);
    208         }
    209 
    210         public boolean isBrightOrDim() {
    211             return policy == POLICY_BRIGHT || policy == POLICY_DIM;
    212         }
    213 
    214         public void copyFrom(DisplayPowerRequest other) {
    215             policy = other.policy;
    216             useProximitySensor = other.useProximitySensor;
    217             screenBrightness = other.screenBrightness;
    218             screenAutoBrightnessAdjustment = other.screenAutoBrightnessAdjustment;
    219             useAutoBrightness = other.useAutoBrightness;
    220             blockScreenOn = other.blockScreenOn;
    221             lowPowerMode = other.lowPowerMode;
    222             boostScreenBrightness = other.boostScreenBrightness;
    223             dozeScreenBrightness = other.dozeScreenBrightness;
    224             dozeScreenState = other.dozeScreenState;
    225         }
    226 
    227         @Override
    228         public boolean equals(Object o) {
    229             return o instanceof DisplayPowerRequest
    230                     && equals((DisplayPowerRequest)o);
    231         }
    232 
    233         public boolean equals(DisplayPowerRequest other) {
    234             return other != null
    235                     && policy == other.policy
    236                     && useProximitySensor == other.useProximitySensor
    237                     && screenBrightness == other.screenBrightness
    238                     && screenAutoBrightnessAdjustment == other.screenAutoBrightnessAdjustment
    239                     && useAutoBrightness == other.useAutoBrightness
    240                     && blockScreenOn == other.blockScreenOn
    241                     && lowPowerMode == other.lowPowerMode
    242                     && boostScreenBrightness == other.boostScreenBrightness
    243                     && dozeScreenBrightness == other.dozeScreenBrightness
    244                     && dozeScreenState == other.dozeScreenState;
    245         }
    246 
    247         @Override
    248         public int hashCode() {
    249             return 0; // don't care
    250         }
    251 
    252         @Override
    253         public String toString() {
    254             return "policy=" + policyToString(policy)
    255                     + ", useProximitySensor=" + useProximitySensor
    256                     + ", screenBrightness=" + screenBrightness
    257                     + ", screenAutoBrightnessAdjustment=" + screenAutoBrightnessAdjustment
    258                     + ", useAutoBrightness=" + useAutoBrightness
    259                     + ", blockScreenOn=" + blockScreenOn
    260                     + ", lowPowerMode=" + lowPowerMode
    261                     + ", boostScreenBrightness=" + boostScreenBrightness
    262                     + ", dozeScreenBrightness=" + dozeScreenBrightness
    263                     + ", dozeScreenState=" + Display.stateToString(dozeScreenState);
    264         }
    265 
    266         public static String policyToString(int policy) {
    267             switch (policy) {
    268                 case POLICY_OFF:
    269                     return "OFF";
    270                 case POLICY_DOZE:
    271                     return "DOZE";
    272                 case POLICY_DIM:
    273                     return "DIM";
    274                 case POLICY_BRIGHT:
    275                     return "BRIGHT";
    276                 default:
    277                     return Integer.toString(policy);
    278             }
    279         }
    280     }
    281 
    282     /**
    283      * Asynchronous callbacks from the power controller to the power manager service.
    284      */
    285     public interface DisplayPowerCallbacks {
    286         void onStateChanged();
    287         void onProximityPositive();
    288         void onProximityNegative();
    289         void onDisplayStateChange(int state); // one of the Display state constants
    290 
    291         void acquireSuspendBlocker();
    292         void releaseSuspendBlocker();
    293     }
    294 
    295     /**
    296      * Called within a Surface transaction whenever the size or orientation of a
    297      * display may have changed.  Provides an opportunity for the client to
    298      * update the position of its surfaces as part of the same transaction.
    299      */
    300     public interface DisplayTransactionListener {
    301         void onDisplayTransaction();
    302     }
    303 }
    304