Developers
Most visited
Recently visited
Display
public
final
class
Display
extends Object
| java.lang.Object | |
| ↳ | android.view.Display |
Provides information about the size and density of a logical display.
The display area is described in two different ways.
- The application display area specifies the part of the display that may contain
an application window, excluding the system decorations. The application display area may
be smaller than the real display area because the system subtracts the space needed
for decor elements such as the status bar. Use
WindowMetrics#getBounds()to query the application window bounds. - The real display area specifies the part of the display that is accessible to an application
in the current system state. The real display area may be smaller than the physical size of the
display in a few scenarios. Use
WindowManager#getCurrentWindowMetrics()to identify the current size of the activity window. UI-related work, such as choosing UI layouts, should rely uponWindowMetrics#getBounds(). SeegetRealSize(Point)/getRealMetrics(DisplayMetrics)for details.
A logical display does not necessarily represent a particular physical display device such as the internal display or an external display. The contents of a logical display may be presented on one or more physical displays according to the devices that are currently attached and whether mirroring has been enabled.
Summary
Nested classes | |
|---|---|
class |
Display.HdrCapabilities
Encapsulates the HDR capabilities of a given display. |
class |
Display.Mode
A mode supported by a given display. |
Constants | |
|---|---|
int |
DEFAULT_DISPLAY
The default Display id, which is the id of the primary display assuming there is one. |
int |
FLAG_PRESENTATION
Display flag: Indicates that the display is a presentation display. |
int |
FLAG_PRIVATE
Display flag: Indicates that the display is private. |
int |
FLAG_ROUND
Display flag: Indicates that the display has a round shape. |
int |
FLAG_SECURE
Display flag: Indicates that the display has a secure video output and supports compositing secure surfaces. |
int |
FLAG_SUPPORTS_PROTECTED_BUFFERS
Display flag: Indicates that the display supports compositing content that is stored in protected graphics buffers. |
int |
INVALID_DISPLAY
Invalid display id. |
int |
STATE_DOZE
Display state: The display is dozing in a low power state; it is still on but is optimized for showing system-provided content while the device is non-interactive. |
int |
STATE_DOZE_SUSPEND
Display state: The display is dozing in a suspended low power state; it is still on but the CPU is not updating it. |
int |
STATE_OFF
Display state: The display is off. |
int |
STATE_ON
Display state: The display is on. |
int |
STATE_ON_SUSPEND
Display state: The display is in a suspended full power state; it is still on but the CPU is not updating it. |
int |
STATE_UNKNOWN
Display state: The display state is unknown. |
int |
STATE_VR
Display state: The display is on and optimized for VR mode. |
Public methods | |
|---|---|
long
|
getAppVsyncOffsetNanos()
Gets the app VSYNC offset, in nanoseconds. |
void
|
getCurrentSizeRange(Point outSmallestSize, Point outLargestSize)
Return the range of display sizes an application can expect to encounter under normal operation, as long as there is no physical change in screen size. |
DisplayCutout
|
getCutout()
Returns the |
DeviceProductInfo
|
getDeviceProductInfo()
Returns the product-specific information about the display or the directly connected device on the display chain. |
int
|
getDisplayId()
Gets the display id. |
int
|
getFlags()
Returns a combination of flags that describe the capabilities of the display. |
Display.HdrCapabilities
|
getHdrCapabilities()
Returns the display's HDR capabilities. |
int
|
getHeight()
This method is deprecated.
Use |
void
|
getMetrics(DisplayMetrics outMetrics)
This method is deprecated.
Use |
Display.Mode
|
getMode()
Returns the active mode of the display. |
String
|
getName()
Gets the name of the display. |
int
|
getOrientation()
This method is deprecated.
use |
int
|
getPixelFormat()
This method is deprecated.
This method is no longer supported.
The result is always |
ColorSpace
|
getPreferredWideGamutColorSpace()
Returns the preferred wide color space of the Display. |
long
|
getPresentationDeadlineNanos()
This is how far in advance a buffer must be queued for presentation at a given time. |
void
|
getRealMetrics(DisplayMetrics outMetrics)
This method is deprecated.
Use |
void
|
getRealSize(Point outSize)
This method is deprecated.
Use |
void
|
getRectSize(Rect outSize)
This method is deprecated.
Use |
float
|
getRefreshRate()
Gets the refresh rate of this display in frames per second. |
int
|
getRotation()
Returns the rotation of the screen from its "natural" orientation. |
RoundedCorner
|
getRoundedCorner(int position)
Returns the |
void
|
getSize(Point outSize)
This method is deprecated.
Use |
int
|
getState()
Gets the state of the display, such as whether it is on or off. |
Mode[]
|
getSupportedModes()
Gets the supported modes of this display. |
float[]
|
getSupportedRefreshRates()
This method is deprecated.
use |
int
|
getWidth()
This method is deprecated.
Use |
boolean
|
isHdr()
Returns whether this display supports any HDR type. |
boolean
|
isMinimalPostProcessingSupported()
Returns true if the connected display can be switched into a mode with minimal post processing. |
boolean
|
isValid()
Returns true if this display is still valid, false if the display has been removed. |
boolean
|
isWideColorGamut()
Returns whether this display can be used to display wide color gamut content. |
String
|
toString()
Returns a string representation of the object. |
Inherited methods | |
|---|---|
Constants
DEFAULT_DISPLAY
public static final int DEFAULT_DISPLAY
The default Display id, which is the id of the primary display assuming there is one.
Constant Value: 0 (0x00000000)
FLAG_PRESENTATION
public static final int FLAG_PRESENTATION
Display flag: Indicates that the display is a presentation display.
This flag identifies secondary displays that are suitable for use as presentation displays such as external or wireless displays. Applications may automatically project their content to presentation displays to provide richer second screen experiences.
See also:
Constant Value: 8 (0x00000008)
FLAG_PRIVATE
public static final int FLAG_PRIVATE
Display flag: Indicates that the display is private. Only the application that owns the display and apps that are already on the display can create windows on it.
See also:
Constant Value: 4 (0x00000004)
FLAG_ROUND
public static final int FLAG_ROUND
Display flag: Indicates that the display has a round shape.
This flag identifies displays that are circular, elliptical or otherwise do not permit the user to see all the way to the logical corners of the display.
See also:
Constant Value: 16 (0x00000010)
FLAG_SECURE
public static final int FLAG_SECURE
Display flag: Indicates that the display has a secure video output and supports compositing secure surfaces.
If this flag is set then the display device has a secure video output
and is capable of showing secure surfaces. It may also be capable of
showing protected buffers.
If this flag is not set then the display device may not have a secure video output; the user may see a blank region on the screen instead of the contents of secure surfaces or protected buffers.
Secure surfaces are used to prevent content rendered into those surfaces by applications from appearing in screenshots or from being viewed on non-secure displays. Protected buffers are used by secure video decoders for a similar purpose.
An application creates a window with a secure surface by specifying the
WindowManager.LayoutParams#FLAG_SECURE window flag.
Likewise, an application creates a SurfaceView with a secure surface
by calling SurfaceView#setSecure before attaching the secure view to
its containing window.
An application can use the absence of this flag as a hint that it should not create secure surfaces or protected buffers on this display because the content may not be visible. For example, if the flag is not set then the application may choose not to show content on this display, show an informative error message, select an alternate content stream or adopt a different strategy for decoding content that does not rely on secure surfaces or protected buffers.
See also:
Constant Value: 2 (0x00000002)
FLAG_SUPPORTS_PROTECTED_BUFFERS
public static final int FLAG_SUPPORTS_PROTECTED_BUFFERS
Display flag: Indicates that the display supports compositing content that is stored in protected graphics buffers.
If this flag is set then the display device supports compositing protected buffers.
If this flag is not set then the display device may not support compositing protected buffers; the user may see a blank region on the screen instead of the protected content.
Secure (DRM) video decoders may allocate protected graphics buffers to request that a hardware-protected path be provided between the video decoder and the external display sink. If a hardware-protected path is not available, then content stored in protected graphics buffers may not be composited.
An application can use the absence of this flag as a hint that it should not use protected buffers for this display because the content may not be visible. For example, if the flag is not set then the application may choose not to show content on this display, show an informative error message, select an alternate content stream or adopt a different strategy for decoding content that does not rely on protected buffers.
See also:
Constant Value: 1 (0x00000001)
INVALID_DISPLAY
public static final int INVALID_DISPLAY
Invalid display id.
Constant Value: -1 (0xffffffff)
STATE_DOZE
public static final int STATE_DOZE
Display state: The display is dozing in a low power state; it is still on but is optimized for showing system-provided content while the device is non-interactive.
See also:
Constant Value: 3 (0x00000003)
STATE_DOZE_SUSPEND
public static final int STATE_DOZE_SUSPEND
Display state: The display is dozing in a suspended low power state; it is still on but the CPU is not updating it. This may be used in one of two ways: to show static system-provided content while the device is non-interactive, or to allow a "Sidekick" compute resource to update the display. For this reason, the CPU must not control the display in this mode.
See also:
Constant Value: 4 (0x00000004)
STATE_OFF
public static final int STATE_OFF
Display state: The display is off.
See also:
Constant Value: 1 (0x00000001)
STATE_ON
public static final int STATE_ON
Display state: The display is on.
See also:
Constant Value: 2 (0x00000002)
STATE_ON_SUSPEND
public static final int STATE_ON_SUSPEND
Display state: The display is in a suspended full power state; it is still on but the CPU is not updating it. This may be used in one of two ways: to show static system-provided content while the device is non-interactive, or to allow a "Sidekick" compute resource to update the display. For this reason, the CPU must not control the display in this mode.
See also:
Constant Value: 6 (0x00000006)
STATE_UNKNOWN
public static final int STATE_UNKNOWN
Display state: The display state is unknown.
See also:
Constant Value: 0 (0x00000000)
STATE_VR
public static final int STATE_VR
Display state: The display is on and optimized for VR mode.
See also:
Constant Value: 5 (0x00000005)
Public methods
getAppVsyncOffsetNanos
public long getAppVsyncOffsetNanos ()
Gets the app VSYNC offset, in nanoseconds. This is a positive value indicating the phase offset of the VSYNC events provided by Choreographer relative to the display refresh. For example, if Choreographer reports that the refresh occurred at time N, it actually occurred at (N - appVsyncOffset).
Apps generally do not need to be aware of this. It's only useful for fine-grained A/V synchronization.
| Returns | |
|---|---|
long |
|
getCurrentSizeRange
public void getCurrentSizeRange (Point outSmallestSize, Point outLargestSize)
Return the range of display sizes an application can expect to encounter under normal operation, as long as there is no physical change in screen size. This is basically the sizes you will see as the orientation changes, taking into account whatever screen decoration there is in each rotation. For example, the status bar is always at the top of the screen, so it will reduce the height both in landscape and portrait, and the smallest height returned here will be the smaller of the two. This is intended for applications to get an idea of the range of sizes they will encounter while going through device rotations, to provide a stable UI through rotation. The sizes here take into account all standard system decorations that reduce the size actually available to the application: the status bar, navigation bar, system bar, etc. It does not take into account more transient elements like an IME soft keyboard.
| Parameters | |
|---|---|
outSmallestSize |
Point: Filled in with the smallest width and height
that the application will encounter, in pixels (not dp units). The x
(width) dimension here directly corresponds to
Configuration.smallestScreenWidthDp, except the value here is in raw
screen pixels rather than dp units. Your application may of course
still get smaller space yet if, for example, a soft keyboard is
being displayed. |
outLargestSize |
Point: Filled in with the largest width and height
that the application will encounter, in pixels (not dp units). Your
application may of course still get larger space than this if,
for example, screen decorations like the status bar are being hidden. |
getCutout
public DisplayCutout getCutout ()
Returns the DisplayCutout, or null if there is none.
| Returns | |
|---|---|
DisplayCutout |
|
See also:
getDeviceProductInfo
public DeviceProductInfo getDeviceProductInfo ()
Returns the product-specific information about the display or the directly connected
device on the display chain.
For example, if the display is transitively connected, this field may contain product
information about the intermediate device.
Returns null if product information is not available.
| Returns | |
|---|---|
DeviceProductInfo |
|
getDisplayId
public int getDisplayId ()
Gets the display id.
Each logical display has a unique id.
The default display has id DEFAULT_DISPLAY.
| Returns | |
|---|---|
int |
|
getFlags
public int getFlags ()
Returns a combination of flags that describe the capabilities of the display.
| Returns | |
|---|---|
int |
The display flags. |
getHdrCapabilities
public Display.HdrCapabilities getHdrCapabilities ()
Returns the display's HDR capabilities.
| Returns | |
|---|---|
Display.HdrCapabilities |
|
See also:
getHeight
public int getHeight ()
This method is deprecated.
Use WindowMetrics#getBounds() instead.
| Returns | |
|---|---|
int |
|
getMetrics
public void getMetrics (DisplayMetrics outMetrics)
This method is deprecated.
Use WindowMetrics#getBounds() to get the dimensions of the application
window area, and Configuration#densityDpi to get the current density.
Gets display metrics that describe the size and density of this display. The size returned by this method does not necessarily represent the actual raw size (native resolution) of the display.
1. The returned size may be adjusted to exclude certain system decor elements that are always visible.
2. It may be scaled to provide compatibility with older applications that were originally designed for smaller displays.
3. It can be different depending on the WindowManager to which the display belongs.
- If requested from non-Activity context (e.g. Application context via
(WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE))
metrics will report the size of the entire display based on current rotation and with
subtracted system decoration areas.
- If requested from activity (either using getWindowManager() or
(WindowManager) getSystemService(Context.WINDOW_SERVICE)) resulting metrics will
correspond to current app window metrics. In this case the size can be smaller than physical
size in multi-window mode.
| Parameters | |
|---|---|
outMetrics |
DisplayMetrics: A DisplayMetrics object to receive the metrics. |
getName
public String getName ()
Gets the name of the display.
Note that some displays may be renamed by the user.
| Returns | |
|---|---|
String |
The display's name. |
getOrientation
public int getOrientation ()
This method is deprecated.
use getRotation()
| Returns | |
|---|---|
int |
orientation of this display.
Value is Surface.ROTATION_0, Surface.ROTATION_90, Surface.ROTATION_180, or Surface.ROTATION_270 |
getPixelFormat
public int getPixelFormat ()
This method is deprecated.
This method is no longer supported.
The result is always PixelFormat#RGBA_8888.
Gets the pixel format of the display.
| Returns | |
|---|---|
int |
One of the constants defined in PixelFormat. |
getPreferredWideGamutColorSpace
public ColorSpace getPreferredWideGamutColorSpace ()
Returns the preferred wide color space of the Display.
The returned wide gamut color space is based on hardware capability and
is preferred by the composition pipeline.
Returns null if the display doesn't support wide color gamut.
Display#isWideColorGamut().
| Returns | |
|---|---|
ColorSpace |
|
getPresentationDeadlineNanos
public long getPresentationDeadlineNanos ()
This is how far in advance a buffer must be queued for presentation at a given time. If you want a buffer to appear on the screen at time N, you must submit the buffer before (N - presentationDeadline).
The desired presentation time for GLES rendering may be set with
EGLExt.eglPresentationTimeANDROID(EGLDisplay, EGLSurface, long). For video decoding, use
MediaCodec.releaseOutputBuffer(int, long). Times are
expressed in nanoseconds, using the system monotonic clock
(System#nanoTime).
| Returns | |
|---|---|
long |
|
getRealMetrics
public void getRealMetrics (DisplayMetrics outMetrics)
This method is deprecated.
Use WindowManager#getCurrentWindowMetrics() to identify the current size
of the activity window. UI-related work, such as choosing UI layouts, should rely
upon WindowMetrics#getBounds(). Use Configuration#densityDpi to
get the current density.
Gets the size of the largest region of the display accessible to an app in the current system state, without subtracting any window decor or applying scaling factors.
The size is adjusted based on the current rotation of the display.
The returned size will fall into one of these scenarios:- The device has no partitions on the display. The returned value is the largest region of the display accessible to an app in the current system state, regardless of windowing mode.
- The device divides a single display into multiple partitions. An application is restricted to a portion of the display. This is common in devices where the display changes size, such as foldables or large screens. The returned size will match the portion of the display the application is restricted to.
- The window manager is emulating a different display size, using
adb shell wm size. The returned size will match the emulated display size.
The returned value is unsuitable to use when sizing and placing UI elements, since it
does not reflect the application window size in any of these scenarios.
WindowManager#getCurrentWindowMetrics() is an alternative that returns the size
of the current application window, even if the window is on a device with a partitioned
display. This helps prevent UI bugs where UI elements are misaligned or placed beyond the
bounds of the window.
WindowManager#getCurrentWindowMetrics() reports the fullscreen window is half of the
screen in size, and each split screen window is a quarter of the screen in size. On the other
hand, getRealMetrics(DisplayMetrics) reports half of the screen size for all windows, since the
application windows are all restricted to their respective partitions.
| Parameters | |
|---|---|
outMetrics |
DisplayMetrics: A DisplayMetrics object to receive the metrics. |
getRealSize
public void getRealSize (Point outSize)
This method is deprecated.
Use WindowManager#getCurrentWindowMetrics() to identify the current size
of the activity window. UI-related work, such as choosing UI layouts, should rely
upon WindowMetrics#getBounds().
Gets the size of the largest region of the display accessible to an app in the current system state, without subtracting any window decor or applying scaling factors.
The size is adjusted based on the current rotation of the display.
The returned size will fall into one of these scenarios:- The device has no partitions on the display. The returned value is the largest region of the display accessible to an app in the current system state, regardless of windowing mode.
- The device divides a single display into multiple partitions. An application is restricted to a portion of the display. This is common in devices where the display changes size, such as foldables or large screens. The returned size will match the portion of the display the application is restricted to.
- The window manager is emulating a different display size, using
adb shell wm size. The returned size will match the emulated display size.
The returned value is unsuitable to use when sizing and placing UI elements, since it
does not reflect the application window size in any of these scenarios.
WindowManager#getCurrentWindowMetrics() is an alternative that returns the size
of the current application window, even if the window is on a device with a partitioned
display. This helps prevent UI bugs where UI elements are misaligned or placed beyond the
bounds of the window.
WindowManager#getCurrentWindowMetrics() reports the fullscreen window is half of the
screen in size, and each split screen window is a quarter of the screen in size. On the other
hand, getRealSize(Point) reports half of the screen size for all windows, since the
application windows are all restricted to their respective partitions.
| Parameters | |
|---|---|
outSize |
Point: Set to the real size of the display. |
getRectSize
public void getRectSize (Rect outSize)
This method is deprecated.
Use WindowMetrics#getBounds() to get the dimensions of the application
window area.
Gets the size of the display as a rectangle, in pixels.
| Parameters | |
|---|---|
outSize |
Rect: A Rect object to receive the size information. |
getRefreshRate
public float getRefreshRate ()
Gets the refresh rate of this display in frames per second.
| Returns | |
|---|---|
float |
|
getRotation
public int getRotation ()
Returns the rotation of the screen from its "natural" orientation.
The returned value may be Surface.ROTATION_0
(no rotation), Surface.ROTATION_90,
Surface.ROTATION_180, or
Surface.ROTATION_270. For
example, if a device has a naturally tall screen, and the user has
turned it on its side to go into a landscape orientation, the value
returned here may be either Surface.ROTATION_90
or Surface.ROTATION_270 depending on
the direction it was turned. The angle is the rotation of the drawn
graphics on the screen, which is the opposite direction of the physical
rotation of the device. For example, if the device is rotated 90
degrees counter-clockwise, to compensate rendering will be rotated by
90 degrees clockwise and thus the returned value here will be
Surface.ROTATION_90.
| Returns | |
|---|---|
int |
Value is Surface.ROTATION_0, Surface.ROTATION_90, Surface.ROTATION_180, or Surface.ROTATION_270 |
getRoundedCorner
public RoundedCorner getRoundedCorner (int position)
Returns the RoundedCorner of the given position if there is one.
| Parameters | |
|---|---|
position |
int: the position of the rounded corner on the display.
Value is RoundedCorner.POSITION_TOP_LEFT, RoundedCorner.POSITION_TOP_RIGHT, RoundedCorner.POSITION_BOTTOM_RIGHT, or RoundedCorner.POSITION_BOTTOM_LEFT |
| Returns | |
|---|---|
RoundedCorner |
the rounded corner of the given position. Returns null if there is none. |
getSize
public void getSize (Point outSize)
This method is deprecated.
Use WindowManager#getCurrentWindowMetrics() to obtain an instance of
WindowMetrics and use WindowMetrics#getBounds() instead.
Gets the size of the display, in pixels. Value returned by this method does not necessarily represent the actual raw size (native resolution) of the display.
1. The returned size may be adjusted to exclude certain system decor elements that are always visible.
2. It may be scaled to provide compatibility with older applications that were originally designed for smaller displays.
3. It can be different depending on the WindowManager to which the display belongs.
- If requested from non-Activity context (e.g. Application context via
(WindowManager) getApplicationContext().getSystemService(Context.WINDOW_SERVICE))
it will report the size of the entire display based on current rotation and with subtracted
system decoration areas.
- If requested from activity (either using getWindowManager() or
(WindowManager) getSystemService(Context.WINDOW_SERVICE)) resulting size will
correspond to current app window size. In this case it can be smaller than physical size in
multi-window mode.
Typically for the purposes of layout apps should make a request from activity context to obtain size available for the app content.
| Parameters | |
|---|---|
outSize |
Point: A Point object to receive the size information. |
getState
public int getState ()
Gets the state of the display, such as whether it is on or off.
| Returns | |
|---|---|
int |
The state of the display: one of STATE_OFF, STATE_ON,
STATE_DOZE, STATE_DOZE_SUSPEND, STATE_ON_SUSPEND, or
STATE_UNKNOWN. |
getSupportedModes
public Mode[] getSupportedModes ()
Gets the supported modes of this display.
| Returns | |
|---|---|
Mode[] |
|
getSupportedRefreshRates
public float[] getSupportedRefreshRates ()
This method is deprecated.
use getSupportedModes() instead
Get the supported refresh rates of this display in frames per second.
This method only returns refresh rates for the display's default modes. For more options, use
getSupportedModes().
| Returns | |
|---|---|
float[] |
|
getWidth
public int getWidth ()
This method is deprecated.
Use WindowMetrics#getBounds instead.
| Returns | |
|---|---|
int |
|
isHdr
public boolean isHdr ()
Returns whether this display supports any HDR type.
| Returns | |
|---|---|
boolean |
|
isMinimalPostProcessingSupported
public boolean isMinimalPostProcessingSupported ()
Returns true if the connected display can be switched into a mode with minimal post processing.
If the Display sink is connected via HDMI, this method will return true if the display supports either Auto Low Latency Mode or Game Content Type.
If the Display sink has an internal connection or uses some other protocol than HDMI, this method will return true if the sink can be switched into an implementation-defined low latency image processing mode.
The ability to switch to a mode with minimal post processing may be disabled by a user setting in the system settings menu. In that case, this method returns false.
| Returns | |
|---|---|
boolean |
|
isValid
public boolean isValid ()
Returns true if this display is still valid, false if the display has been removed.
If the display is invalid, then the methods of this class will
continue to report the most recently observed display information.
However, it is unwise (and rather fruitless) to continue using a
Display object after the display's demise.
It's possible for a display that was previously invalid to become
valid again if a display with the same id is reconnected.
| Returns | |
|---|---|
boolean |
True if the display is still valid. |
isWideColorGamut
public boolean isWideColorGamut ()
Returns whether this display can be used to display wide color gamut content.
This does not necessarily mean the device itself can render wide color gamut
content. To ensure wide color gamut content can be produced, refer to
Configuration#isScreenWideColorGamut().
| Returns | |
|---|---|
boolean |
|
toString
public String toString ()
Returns a string representation of the object. In general, the
toString method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
| Returns | |
|---|---|
String |
a string representation of the object. |