/* * Copyright (C) 2012 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.content.Context; import android.os.Handler; import android.util.SparseArray; import android.view.Display; import android.view.Surface; import java.util.ArrayList; /** * Manages the properties of attached displays. *
* Get an instance of this class by calling * {@link android.content.Context#getSystemService(java.lang.String) * Context.getSystemService()} with the argument * {@link android.content.Context#DISPLAY_SERVICE}. *
*/ public final class DisplayManager { private static final String TAG = "DisplayManager"; private static final boolean DEBUG = false; private final Context mContext; private final DisplayManagerGlobal mGlobal; private final Object mLock = new Object(); private final SparseArray* The status is provided as a {@link WifiDisplayStatus} object in the * {@link #EXTRA_WIFI_DISPLAY_STATUS} extra. *
* This broadcast is only sent to registered receivers and can only be sent by the system. *
* @hide */ public static final String ACTION_WIFI_DISPLAY_STATUS_CHANGED = "android.hardware.display.action.WIFI_DISPLAY_STATUS_CHANGED"; /** * Contains a {@link WifiDisplayStatus} object. * @hide */ public static final String EXTRA_WIFI_DISPLAY_STATUS = "android.hardware.display.extra.WIFI_DISPLAY_STATUS"; /** * Display category: Presentation displays. ** This category can be used to identify 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 android.app.Presentation * @see Display#FLAG_PRESENTATION * @see #getDisplays(String) */ public static final String DISPLAY_CATEGORY_PRESENTATION = "android.hardware.display.category.PRESENTATION"; /** * Virtual display flag: Create a public display. * ** When this flag is set, the virtual display is public. *
* A public virtual display behaves just like most any other display that is connected * to the system such as an HDMI or Wireless display. Applications can open * windows on the display and the system may mirror the contents of other displays * onto it. *
* Creating a public virtual display requires the * {@link android.Manifest.permission#CAPTURE_VIDEO_OUTPUT} * or {@link android.Manifest.permission#CAPTURE_SECURE_VIDEO_OUTPUT} permission. * These permissions are reserved for use by system components and are not available to * third-party applications. *
* ** When this flag is not set, the virtual display is private as defined by the * {@link Display#FLAG_PRIVATE} display flag. *
* A private virtual display belongs to the application that created it. * Only the a owner of a private virtual display is allowed to place windows upon it. * The private virtual display also does not participate in display mirroring: it will * neither receive mirrored content from another display nor allow its own content to * be mirrored elsewhere. More precisely, the only processes that are allowed to * enumerate or interact with the private display are those that have the same UID as the * application that originally created the private virtual display. * * * @see #createVirtualDisplay * @see #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY */ public static final int VIRTUAL_DISPLAY_FLAG_PUBLIC = 1 << 0; /** * Virtual display flag: Create a presentation display. * ** When this flag is set, the virtual display is registered as a presentation * display in the {@link #DISPLAY_CATEGORY_PRESENTATION presentation display category}. * Applications may automatically project their content to presentation displays * to provide richer second screen experiences. *
* ** When this flag is not set, the virtual display is not registered as a presentation * display. Applications can still project their content on the display but they * will typically not do so automatically. This option is appropriate for * more special-purpose displays. *
* * @see android.app.Presentation * @see #createVirtualDisplay * @see #DISPLAY_CATEGORY_PRESENTATION * @see Display#FLAG_PRESENTATION */ public static final int VIRTUAL_DISPLAY_FLAG_PRESENTATION = 1 << 1; /** * Virtual display flag: Create a secure display. * ** When this flag is set, the virtual display is considered secure as defined * by the {@link Display#FLAG_SECURE} display flag. The caller promises to take * reasonable measures, such as over-the-air encryption, to prevent the contents * of the display from being intercepted or recorded on a persistent medium. *
* Creating a secure virtual display requires the * {@link android.Manifest.permission#CAPTURE_SECURE_VIDEO_OUTPUT} permission. * This permission is reserved for use by system components and is not available to * third-party applications. *
* ** When this flag is not set, the virtual display is considered unsecure. * The content of secure windows will be blanked if shown on this display. *
* * @see Display#FLAG_SECURE * @see #createVirtualDisplay */ public static final int VIRTUAL_DISPLAY_FLAG_SECURE = 1 << 2; /** * Virtual display flag: Only show this display's own content; do not mirror * the content of another display. * ** This flag is used in conjunction with {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}. * Ordinarily public virtual displays will automatically mirror the content of the * default display if they have no windows of their own. When this flag is * specified, the virtual display will only ever show its own content and * will be blanked instead if it has no windows. *
* * @see #createVirtualDisplay */ public static final int VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY = 1 << 3; /** @hide */ public DisplayManager(Context context) { mContext = context; mGlobal = DisplayManagerGlobal.getInstance(); } /** * Gets information about a logical display. * * The display metrics may be adjusted to provide compatibility * for legacy applications. * * @param displayId The logical display id. * @return The display object, or null if there is no valid display with the given id. */ public Display getDisplay(int displayId) { synchronized (mLock) { return getOrCreateDisplayLocked(displayId, false /*assumeValid*/); } } /** * Gets all currently valid logical displays. * * @return An array containing all displays. */ public Display[] getDisplays() { return getDisplays(null); } /** * Gets all currently valid logical displays of the specified category. ** When there are multiple displays in a category the returned displays are sorted * of preference. For example, if the requested category is * {@link #DISPLAY_CATEGORY_PRESENTATION} and there are multiple presentation displays * then the displays are sorted so that the first display in the returned array * is the most preferred presentation display. The application may simply * use the first display or allow the user to choose. *
* * @param category The requested display category or null to return all displays. * @return An array containing all displays sorted by order of preference. * * @see #DISPLAY_CATEGORY_PRESENTATION */ public Display[] getDisplays(String category) { final int[] displayIds = mGlobal.getDisplayIds(); synchronized (mLock) { try { if (category == null) { addAllDisplaysLocked(mTempDisplays, displayIds); } else if (category.equals(DISPLAY_CATEGORY_PRESENTATION)) { addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_WIFI); addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_HDMI); addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_OVERLAY); addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_VIRTUAL); } return mTempDisplays.toArray(new Display[mTempDisplays.size()]); } finally { mTempDisplays.clear(); } } } private void addAllDisplaysLocked(ArrayList* Calls to this method nest and must be matched by an equal number of calls to * {@link #stopWifiDisplayScan()}. *
* Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. *
* * @hide */ public void startWifiDisplayScan() { mGlobal.startWifiDisplayScan(); } /** * Stops scanning for available Wifi displays. ** Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. *
* * @hide */ public void stopWifiDisplayScan() { mGlobal.stopWifiDisplayScan(); } /** * Connects to a Wifi display. * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast. ** Automatically remembers the display after a successful connection, if not * already remembered. *
* Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. *
* * @param deviceAddress The MAC address of the device to which we should connect. * @hide */ public void connectWifiDisplay(String deviceAddress) { mGlobal.connectWifiDisplay(deviceAddress); } /** @hide */ public void pauseWifiDisplay() { mGlobal.pauseWifiDisplay(); } /** @hide */ public void resumeWifiDisplay() { mGlobal.resumeWifiDisplay(); } /** * Disconnects from the current Wifi display. * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast. * @hide */ public void disconnectWifiDisplay() { mGlobal.disconnectWifiDisplay(); } /** * Renames a Wifi display. ** The display must already be remembered for this call to succeed. In other words, * we must already have successfully connected to the display at least once and then * not forgotten it. *
* Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. *
* * @param deviceAddress The MAC address of the device to rename. * @param alias The alias name by which to remember the device, or null * or empty if no alias should be used. * @hide */ public void renameWifiDisplay(String deviceAddress, String alias) { mGlobal.renameWifiDisplay(deviceAddress, alias); } /** * Forgets a previously remembered Wifi display. ** Automatically disconnects from the display if currently connected to it. *
* Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}. *
* * @param deviceAddress The MAC address of the device to forget. * @hide */ public void forgetWifiDisplay(String deviceAddress) { mGlobal.forgetWifiDisplay(deviceAddress); } /** * Gets the current Wifi display status. * Watch for changes in the status by registering a broadcast receiver for * {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED}. * * @return The current Wifi display status. * @hide */ public WifiDisplayStatus getWifiDisplayStatus() { return mGlobal.getWifiDisplayStatus(); } /** * Creates a virtual display. ** The content of a virtual display is rendered to a {@link Surface} provided * by the application. *
* The virtual display should be {@link VirtualDisplay#release released} * when no longer needed. Because a virtual display renders to a surface * provided by the application, it will be released automatically when the * process terminates and all remaining windows on it will be forcibly removed. *
* The behavior of the virtual display depends on the flags that are provided * to this method. By default, virtual displays are created to be private, * non-presentation and unsecure. Permissions may be required to use certain flags. *
* As of {@link android.os.Build.VERSION_CODES#KITKAT_WATCH}, the surface may * be attached or detached dynamically using {@link VirtualDisplay#setSurface}. * Previously, the surface had to be non-null when {@link #createVirtualDisplay} * was called and could not be changed for the lifetime of the display. *
* Detaching the surface that backs a virtual display has a similar effect to * turning off the screen. *
* * @param name The name of the virtual display, must be non-empty. * @param width The width of the virtual display in pixels, must be greater than 0. * @param height The height of the virtual display in pixels, must be greater than 0. * @param densityDpi The density of the virtual display in dpi, must be greater than 0. * @param surface The surface to which the content of the virtual display should * be rendered, or null if there is none initially. * @param flags A combination of virtual display flags: * {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}, {@link #VIRTUAL_DISPLAY_FLAG_PRESENTATION}, * {@link #VIRTUAL_DISPLAY_FLAG_SECURE}, or {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}. * @return The newly created virtual display, or null if the application could * not create the virtual display. * * @throws SecurityException if the caller does not have permission to create * a virtual display with the specified flags. */ public VirtualDisplay createVirtualDisplay(String name, int width, int height, int densityDpi, Surface surface, int flags) { return mGlobal.createVirtualDisplay(mContext, name, width, height, densityDpi, surface, flags); } /** * Listens for changes in available display devices. */ public interface DisplayListener { /** * Called whenever a logical display has been added to the system. * Use {@link DisplayManager#getDisplay} to get more information about * the display. * * @param displayId The id of the logical display that was added. */ void onDisplayAdded(int displayId); /** * Called whenever a logical display has been removed from the system. * * @param displayId The id of the logical display that was removed. */ void onDisplayRemoved(int displayId); /** * Called whenever the properties of a logical display have changed. * * @param displayId The id of the logical display that changed. */ void onDisplayChanged(int displayId); } }