Skip to content

Most visited

Recently visited

navigation
Added in API level 1

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.

A logical display does not necessarily represent a particular physical display device such as the built-in screen or an external monitor. 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 built-in 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 is optimized for showing static system-provided content while the device is non-interactive.

int STATE_OFF

Display state: The display is off.

int STATE_ON

Display state: The display is on.

int STATE_UNKNOWN

Display state: The display state is unknown.

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.

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 was deprecated in API level 13. Use getSize(Point) instead.

void getMetrics(DisplayMetrics outMetrics)

Gets display metrics that describe the size and density of this display.

Display.Mode getMode()

Returns the active mode of the display.

String getName()

Gets the name of the display.

int getOrientation()

This method was deprecated in API level 8. use getRotation()

int getPixelFormat()

This method was deprecated in API level 17. This method is no longer supported. The result is always RGBA_8888.

long getPresentationDeadlineNanos()

This is how far in advance a buffer must be queued for presentation at a given time.

void getRealMetrics(DisplayMetrics outMetrics)

Gets display metrics based on the real size of this display.

void getRealSize(Point outSize)

Gets the real size of the display without subtracting any window decor or applying any compatibility scale factors.

void getRectSize(Rect outSize)

Gets the size of the display as a rectangle, in pixels.

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.

void getSize(Point outSize)

Gets the size of the display, in pixels.

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 was deprecated in API level 23. use getSupportedModes() instead

int getWidth()

This method was deprecated in API level 13. Use getSize(Point) instead.

boolean isValid()

Returns true if this display is still valid, false if the display has been removed.

String toString()

Returns a string representation of the object.

Inherited methods

From class java.lang.Object

Constants

DEFAULT_DISPLAY

Added in API level 1
int DEFAULT_DISPLAY

The default Display id, which is the id of the built-in primary display assuming there is one.

Constant Value: 0 (0x00000000)

FLAG_PRESENTATION

Added in API level 19
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 HDMI 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

Added in API level 19
int FLAG_PRIVATE

Display flag: Indicates that the display is private. Only the application that owns the display can create windows on it.

See also:

Constant Value: 4 (0x00000004)

FLAG_ROUND

Added in API level 23
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

Added in API level 17
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 FLAG_SECURE window flag. Likewise, an application creates a SurfaceView with a secure surface by calling setSecure(boolean) 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

Added in API level 17
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

Added in API level 23
int INVALID_DISPLAY

Invalid display id.

Constant Value: -1 (0xffffffff)

STATE_DOZE

Added in API level 21
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

Added in API level 21
int STATE_DOZE_SUSPEND

Display state: The display is dozing in a suspended low power state; it is still on but is optimized for showing static system-provided content while the device is non-interactive. This mode may be used to conserve even more power by allowing the hardware to stop applying frame buffer updates from the graphics subsystem or to take over the display and manage it autonomously to implement low power always-on display functionality.

See also:

Constant Value: 4 (0x00000004)

STATE_OFF

Added in API level 20
int STATE_OFF

Display state: The display is off.

See also:

Constant Value: 1 (0x00000001)

STATE_ON

Added in API level 20
int STATE_ON

Display state: The display is on.

See also:

Constant Value: 2 (0x00000002)

STATE_UNKNOWN

Added in API level 20
int STATE_UNKNOWN

Display state: The display state is unknown.

See also:

Constant Value: 0 (0x00000000)

Public methods

getAppVsyncOffsetNanos

Added in API level 21
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

Added in API level 16
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.

getDisplayId

Added in API level 1
int getDisplayId ()

Gets the display id.

Each logical display has a unique id. The default display has id DEFAULT_DISPLAY.

Returns
int

getFlags

Added in API level 17
int getFlags ()

Returns a combination of flags that describe the capabilities of the display.

Returns
int The display flags.

See also:

getHdrCapabilities

Added in API level 24
Display.HdrCapabilities getHdrCapabilities ()

Returns the display's HDR capabilities.

Returns
Display.HdrCapabilities

getHeight

Added in API level 1
int getHeight ()

This method was deprecated in API level 13.
Use getSize(Point) instead.

Returns
int

getMetrics

Added in API level 1
void getMetrics (DisplayMetrics outMetrics)

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 real size of the display based on current rotation.
 - If requested from activity resulting metrics will correspond to current 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.

getMode

Added in API level 23
Display.Mode getMode ()

Returns the active mode of the display.

Returns
Display.Mode

getName

Added in API level 17
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

Added in API level 1
int getOrientation ()

This method was deprecated in API level 8.
use getRotation()

Returns
int orientation of this display.

getPixelFormat

Added in API level 1
int getPixelFormat ()

This method was deprecated in API level 17.
This method is no longer supported. The result is always RGBA_8888.

Gets the pixel format of the display.

Returns
int One of the constants defined in PixelFormat.

getPresentationDeadlineNanos

Added in API level 21
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 eglPresentationTimeANDROID(EGLDisplay, EGLSurface, long). For video decoding, use releaseOutputBuffer(int, long). Times are expressed in nanoseconds, using the system monotonic clock (nanoTime()).

Returns
long

getRealMetrics

Added in API level 17
void getRealMetrics (DisplayMetrics outMetrics)

Gets display metrics based on the real size of this display.

The size is adjusted based on the current rotation of the display.

The real size may be smaller than the physical size of the screen when the window manager is emulating a smaller display (using adb shell wm size).

Parameters
outMetrics DisplayMetrics: A DisplayMetrics object to receive the metrics.

getRealSize

Added in API level 17
void getRealSize (Point outSize)

Gets the real size of the display without subtracting any window decor or applying any compatibility scale factors.

The size is adjusted based on the current rotation of the display.

The real size may be smaller than the physical size of the screen when the window manager is emulating a smaller display (using adb shell am display-size).

Parameters
outSize Point: Set to the real size of the display.

getRectSize

Added in API level 13
void getRectSize (Rect outSize)

Gets the size of the display as a rectangle, in pixels.

Parameters
outSize Rect: A Rect object to receive the size information.

See also:

getRefreshRate

Added in API level 1
float getRefreshRate ()

Gets the refresh rate of this display in frames per second.

Returns
float

getRotation

Added in API level 8
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

getSize

Added in API level 13
void getSize (Point outSize)

Gets the size of the display, in pixels.

Note that this value should not be used for computing layouts, since a device will typically have screen decoration (such as a status bar) along the edges of the display that reduce the amount of application space available from the size returned here. Layouts should instead use the window size.

The size is adjusted based on the current rotation of the display.

The size returned by this method does not necessarily represent the actual raw size (native resolution) of the display. The returned size may be adjusted to exclude certain system decoration elements that are always visible. It may also be scaled to provide compatibility with older applications that were originally designed for smaller displays.

Parameters
outSize Point: A Point object to receive the size information.

getState

Added in API level 20
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, or STATE_UNKNOWN.

getSupportedModes

Added in API level 23
Mode[] getSupportedModes ()

Gets the supported modes of this display.

Returns
Mode[]

getSupportedRefreshRates

Added in API level 21
float[] getSupportedRefreshRates ()

This method was deprecated in API level 23.
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

Added in API level 1
int getWidth ()

This method was deprecated in API level 13.
Use getSize(Point) instead.

Returns
int

isValid

Added in API level 17
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.

toString

Added in API level 1
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.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.