android/hardware/display/DisplayManagerInternal.java - platform/prebuilts/fullsdk/sources/android-30 - Git at Google

 /*
  * Copyright (C) 2014 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.hardware.display;

 import android.annotation.Nullable;
 import android.graphics.Point;
 import android.hardware.SensorManager;
 import android.os.Handler;
 import android.os.PowerManager;
 import android.util.IntArray;
 import android.util.SparseArray;
 import android.view.Display;
 import android.view.DisplayInfo;
 import android.view.SurfaceControl;
 import android.view.SurfaceControl.Transaction;

 /**
  * Display manager local system service interface.
  *
  * @hide Only for use within the system server.
  */
 public abstract class DisplayManagerInternal {
     /**
      * Called by the power manager to initialize power management facilities.
      */
     public abstract void initPowerManagement(DisplayPowerCallbacks callbacks,
             Handler handler, SensorManager sensorManager);

     /**
      * Called by the power manager to request a new power state.
      * <p>
      * The display power controller makes a copy of the provided object and then
      * begins adjusting the power state to match what was requested.
      * </p>
      *
      * @param request The requested power state.
      * @param waitForNegativeProximity If 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 True if display is ready, 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.
      */
     public abstract boolean requestPowerState(DisplayPowerRequest request,
             boolean waitForNegativeProximity);

     /**
      * Returns true if the proximity sensor screen-off function is available.
      */
     public abstract boolean isProximitySensorAvailable();

     /**
      * 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 SurfaceControl.ScreenshotGraphicBuffer systemScreenshot(int displayId);

     /**
      * 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 SurfaceControl.ScreenshotGraphicBuffer 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 the position of the display's projection.
      *
      * @param displayId The logical display id.
      * @return The x, y coordinates of the display, or null if the display does not exist. The
      * return object must be treated as immutable.
      */
     @Nullable
     public abstract Point getDisplayPosition(int displayId);

     /**
      * Registers a display transaction listener to provide the client a chance to
      * update its surfaces within the same transaction as any display layout updates.
      *
      * @param listener The listener to register.
      */
     public abstract void registerDisplayTransactionListener(DisplayTransactionListener listener);

     /**
      * Unregisters a display transaction listener to provide the client a chance to
      * update its surfaces within the same transaction as any display layout updates.
      *
      * @param listener The listener to unregister.
      */
     public abstract void unregisterDisplayTransactionListener(DisplayTransactionListener listener);

     /**
      * Overrides the display information of a particular logical display.
      * This is used by the window manager to control the size and characteristics
      * of the default display.  It is expected to apply the requested change
      * to the display information synchronously so that applications will immediately
      * observe the new state.
      *
      * 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.
      */
     public abstract void performTraversal(Transaction t);

     /**
      * Tells the display manager about properties of the display that depend on the windows on it.
      * This includes whether there is interesting unique content on the specified logical display,
      * and whether the one of the windows has a preferred refresh rate.
      * <p>
      * 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.
      * </p>
      *
      * <p>
      * 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.
      * </p>
      *
      * @param displayId The logical display id to update.
      * @param hasContent True if the logical display has content. This is used to control automatic
      * mirroring.
      * @param requestedRefreshRate The preferred refresh rate for the top-most visible window that
      * has a preference.
      * @param requestedModeId The preferred mode id for the top-most visible window that has a
      * preference.
      * @param requestedMinimalPostProcessing The preferred minimal post processing setting for the
      * display. This is true when there is at least one visible window that wants minimal post
      * processng on.
      * @param inTraversal True if called from WindowManagerService during a window traversal
      * prior to call to performTraversalInTransactionFromWindowManager.
      */
     public abstract void setDisplayProperties(int displayId, boolean hasContent,
             float requestedRefreshRate, int requestedModeId, boolean requestedMinimalPostProcessing,
             boolean inTraversal);

     /**
      * Applies an offset to the contents of a display, for example to avoid burn-in.
      * <p>
      * TODO: Technically this should be associated with a physical rather than logical
      * display but this is good enough for now.
      * </p>
      *
      * @param displayId The logical display id to update.
      * @param x The X offset by which to shift the contents of the display.
      * @param y The Y offset by which to shift the contents of the display.
      */
     public abstract void setDisplayOffsets(int displayId, int x, int y);

     /**
      * Disables scaling for a display.
      *
      * @param displayId The logical display id to disable scaling for.
      * @param disableScaling {@code true} to disable scaling,
      * {@code false} to use the default scaling behavior of the logical display.
      */
     public abstract void setDisplayScalingDisabled(int displayId, boolean disableScaling);

     /**
      * Provide a list of UIDs that are present on the display and are allowed to access it.
      *
      * @param displayAccessUIDs Mapping displayId -> int array of UIDs.
      */
     public abstract void setDisplayAccessUIDs(SparseArray<IntArray> displayAccessUIDs);

     /**
      * Persist brightness slider events and ambient brightness stats.
      */
     public abstract void persistBrightnessTrackerState();

     /**
      * 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);

     /**
      * Describes the requested power state of the display.
      *
      * 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 final 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;
         // Policy: Keep the screen and display optimized for VR mode.
         public static final int POLICY_VR = 4;

         // The basic overall policy to apply: off, doze, dim or bright.
         public int policy;

         // 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;

         // An override of the screen brightness.
         // Set to PowerManager.BRIGHTNESS_INVALID if there's no override.
         public float screenBrightnessOverride;

         // 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, enables automatic brightness control.
         public boolean useAutoBrightness;

         // 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 DisplayPowerRequest() {
             policy = POLICY_BRIGHT;
             useProximitySensor = false;
             screenBrightnessOverride = PowerManager.BRIGHTNESS_INVALID_FLOAT;
             useAutoBrightness = false;
             screenAutoBrightnessAdjustmentOverride = Float.NaN;
             screenLowPowerBrightnessFactor = 0.5f;
             blockScreenOn = false;
             dozeScreenBrightness = PowerManager.BRIGHTNESS_INVALID_FLOAT;
             dozeScreenState = Display.STATE_UNKNOWN;
         }

         public DisplayPowerRequest(DisplayPowerRequest other) {
             copyFrom(other);
         }

         public boolean isBrightOrDim() {
             return policy == POLICY_BRIGHT || policy == POLICY_DIM;
         }

         public boolean isVr() {
             return policy == POLICY_VR;
         }

         public void copyFrom(DisplayPowerRequest other) {
             policy = other.policy;
             useProximitySensor = other.useProximitySensor;
             screenBrightnessOverride = other.screenBrightnessOverride;
             useAutoBrightness = other.useAutoBrightness;
             screenAutoBrightnessAdjustmentOverride = other.screenAutoBrightnessAdjustmentOverride;
             screenLowPowerBrightnessFactor = other.screenLowPowerBrightnessFactor;
             blockScreenOn = other.blockScreenOn;
             lowPowerMode = other.lowPowerMode;
             boostScreenBrightness = other.boostScreenBrightness;
             dozeScreenBrightness = other.dozeScreenBrightness;
             dozeScreenState = other.dozeScreenState;
         }

         @Override
         public boolean equals(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)
                     && useAutoBrightness == other.useAutoBrightness
                     && floatEquals(screenAutoBrightnessAdjustmentOverride,
                             other.screenAutoBrightnessAdjustmentOverride)
                     && screenLowPowerBrightnessFactor
                     == other.screenLowPowerBrightnessFactor
                     && blockScreenOn == other.blockScreenOn
                     && lowPowerMode == other.lowPowerMode
                     && boostScreenBrightness == other.boostScreenBrightness
                     && floatEquals(dozeScreenBrightness, other.dozeScreenBrightness)
                     && dozeScreenState == other.dozeScreenState;
         }

         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
                     + ", useAutoBrightness=" + useAutoBrightness
                     + ", screenAutoBrightnessAdjustmentOverride="
                     + screenAutoBrightnessAdjustmentOverride
                     + ", screenLowPowerBrightnessFactor=" + screenLowPowerBrightnessFactor
                     + ", blockScreenOn=" + blockScreenOn
                     + ", lowPowerMode=" + lowPowerMode
                     + ", boostScreenBrightness=" + boostScreenBrightness
                     + ", dozeScreenBrightness=" + dozeScreenBrightness
                     + ", dozeScreenState=" + Display.stateToString(dozeScreenState);
         }

         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";
                 case POLICY_VR:
                     return "VR";
                 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(int state); // one of the Display state constants

         void acquireSuspendBlocker();
         void releaseSuspendBlocker();
     }

     /**
      * 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);
     }
 }
	/*
	* Copyright (C) 2014 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.hardware.display;

	import android.annotation.Nullable;
	import android.graphics.Point;
	import android.hardware.SensorManager;
	import android.os.Handler;
	import android.os.PowerManager;
	import android.util.IntArray;
	import android.util.SparseArray;
	import android.view.Display;
	import android.view.DisplayInfo;
	import android.view.SurfaceControl;
	import android.view.SurfaceControl.Transaction;

	/**
	* Display manager local system service interface.
	*
	* @hide Only for use within the system server.
	*/
	public abstract class DisplayManagerInternal {
	/**
	* Called by the power manager to initialize power management facilities.
	*/
	public abstract void initPowerManagement(DisplayPowerCallbacks callbacks,
	Handler handler, SensorManager sensorManager);

	/**
	* Called by the power manager to request a new power state.
	* <p>
	* The display power controller makes a copy of the provided object and then
	* begins adjusting the power state to match what was requested.
	* </p>
	*
	* @param request The requested power state.
	* @param waitForNegativeProximity If 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 True if display is ready, 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.
	*/
	public abstract boolean requestPowerState(DisplayPowerRequest request,
	boolean waitForNegativeProximity);

	/**
	* Returns true if the proximity sensor screen-off function is available.
	*/
	public abstract boolean isProximitySensorAvailable();

	/**
	* 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 SurfaceControl.ScreenshotGraphicBuffer systemScreenshot(int displayId);

	/**
	* 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 SurfaceControl.ScreenshotGraphicBuffer 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 the position of the display's projection.
	*
	* @param displayId The logical display id.
	* @return The x, y coordinates of the display, or null if the display does not exist. The
	* return object must be treated as immutable.
	*/
	@Nullable
	public abstract Point getDisplayPosition(int displayId);

	/**
	* Registers a display transaction listener to provide the client a chance to
	* update its surfaces within the same transaction as any display layout updates.
	*
	* @param listener The listener to register.
	*/
	public abstract void registerDisplayTransactionListener(DisplayTransactionListener listener);

	/**
	* Unregisters a display transaction listener to provide the client a chance to
	* update its surfaces within the same transaction as any display layout updates.
	*
	* @param listener The listener to unregister.
	*/
	public abstract void unregisterDisplayTransactionListener(DisplayTransactionListener listener);

	/**
	* Overrides the display information of a particular logical display.
	* This is used by the window manager to control the size and characteristics
	* of the default display. It is expected to apply the requested change
	* to the display information synchronously so that applications will immediately
	* observe the new state.
	*
	* 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.
	*/
	public abstract void performTraversal(Transaction t);

	/**
	* Tells the display manager about properties of the display that depend on the windows on it.
	* This includes whether there is interesting unique content on the specified logical display,
	* and whether the one of the windows has a preferred refresh rate.
	* <p>
	* 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.
	* </p>
	*
	* <p>
	* 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.
	* </p>
	*
	* @param displayId The logical display id to update.
	* @param hasContent True if the logical display has content. This is used to control automatic
	* mirroring.
	* @param requestedRefreshRate The preferred refresh rate for the top-most visible window that
	* has a preference.
	* @param requestedModeId The preferred mode id for the top-most visible window that has a
	* preference.
	* @param requestedMinimalPostProcessing The preferred minimal post processing setting for the
	* display. This is true when there is at least one visible window that wants minimal post
	* processng on.
	* @param inTraversal True if called from WindowManagerService during a window traversal
	* prior to call to performTraversalInTransactionFromWindowManager.
	*/
	public abstract void setDisplayProperties(int displayId, boolean hasContent,
	float requestedRefreshRate, int requestedModeId, boolean requestedMinimalPostProcessing,
	boolean inTraversal);

	/**
	* Applies an offset to the contents of a display, for example to avoid burn-in.
	* <p>
	* TODO: Technically this should be associated with a physical rather than logical
	* display but this is good enough for now.
	* </p>
	*
	* @param displayId The logical display id to update.
	* @param x The X offset by which to shift the contents of the display.
	* @param y The Y offset by which to shift the contents of the display.
	*/
	public abstract void setDisplayOffsets(int displayId, int x, int y);

	/**
	* Disables scaling for a display.
	*
	* @param displayId The logical display id to disable scaling for.
	* @param disableScaling {@code true} to disable scaling,
	* {@code false} to use the default scaling behavior of the logical display.
	*/
	public abstract void setDisplayScalingDisabled(int displayId, boolean disableScaling);

	/**
	* Provide a list of UIDs that are present on the display and are allowed to access it.
	*
	* @param displayAccessUIDs Mapping displayId -> int array of UIDs.
	*/
	public abstract void setDisplayAccessUIDs(SparseArray<IntArray> displayAccessUIDs);

	/**
	* Persist brightness slider events and ambient brightness stats.
	*/
	public abstract void persistBrightnessTrackerState();

	/**
	* 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);

	/**
	* Describes the requested power state of the display.
	*
	* 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 final 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;
	// Policy: Keep the screen and display optimized for VR mode.
	public static final int POLICY_VR = 4;

	// The basic overall policy to apply: off, doze, dim or bright.
	public int policy;

	// 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;

	// An override of the screen brightness.
	// Set to PowerManager.BRIGHTNESS_INVALID if there's no override.
	public float screenBrightnessOverride;

	// 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, enables automatic brightness control.
	public boolean useAutoBrightness;

	// 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 DisplayPowerRequest() {
	policy = POLICY_BRIGHT;
	useProximitySensor = false;
	screenBrightnessOverride = PowerManager.BRIGHTNESS_INVALID_FLOAT;
	useAutoBrightness = false;
	screenAutoBrightnessAdjustmentOverride = Float.NaN;
	screenLowPowerBrightnessFactor = 0.5f;
	blockScreenOn = false;
	dozeScreenBrightness = PowerManager.BRIGHTNESS_INVALID_FLOAT;
	dozeScreenState = Display.STATE_UNKNOWN;
	}

	public DisplayPowerRequest(DisplayPowerRequest other) {
	copyFrom(other);
	}

	public boolean isBrightOrDim() {
	return policy == POLICY_BRIGHT \|\| policy == POLICY_DIM;
	}

	public boolean isVr() {
	return policy == POLICY_VR;
	}

	public void copyFrom(DisplayPowerRequest other) {
	policy = other.policy;
	useProximitySensor = other.useProximitySensor;
	screenBrightnessOverride = other.screenBrightnessOverride;
	useAutoBrightness = other.useAutoBrightness;
	screenAutoBrightnessAdjustmentOverride = other.screenAutoBrightnessAdjustmentOverride;
	screenLowPowerBrightnessFactor = other.screenLowPowerBrightnessFactor;
	blockScreenOn = other.blockScreenOn;
	lowPowerMode = other.lowPowerMode;
	boostScreenBrightness = other.boostScreenBrightness;
	dozeScreenBrightness = other.dozeScreenBrightness;
	dozeScreenState = other.dozeScreenState;
	}

	@Override
	public boolean equals(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)
	&& useAutoBrightness == other.useAutoBrightness
	&& floatEquals(screenAutoBrightnessAdjustmentOverride,
	other.screenAutoBrightnessAdjustmentOverride)
	&& screenLowPowerBrightnessFactor
	== other.screenLowPowerBrightnessFactor
	&& blockScreenOn == other.blockScreenOn
	&& lowPowerMode == other.lowPowerMode
	&& boostScreenBrightness == other.boostScreenBrightness
	&& floatEquals(dozeScreenBrightness, other.dozeScreenBrightness)
	&& dozeScreenState == other.dozeScreenState;
	}

	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
	+ ", useAutoBrightness=" + useAutoBrightness
	+ ", screenAutoBrightnessAdjustmentOverride="
	+ screenAutoBrightnessAdjustmentOverride
	+ ", screenLowPowerBrightnessFactor=" + screenLowPowerBrightnessFactor
	+ ", blockScreenOn=" + blockScreenOn
	+ ", lowPowerMode=" + lowPowerMode
	+ ", boostScreenBrightness=" + boostScreenBrightness
	+ ", dozeScreenBrightness=" + dozeScreenBrightness
	+ ", dozeScreenState=" + Display.stateToString(dozeScreenState);
	}

	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";
	case POLICY_VR:
	return "VR";
	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(int state); // one of the Display state constants

	void acquireSuspendBlocker();
	void releaseSuspendBlocker();
	}

	/**
	* 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);
	}
	}