1 /*
2  * Copyright (C) 2012 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.hardware.display;
18 
19 import android.Manifest;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 import android.annotation.RequiresPermission;
23 import android.annotation.SystemApi;
24 import android.annotation.SystemService;
25 import android.annotation.TestApi;
26 import android.app.KeyguardManager;
27 import android.compat.annotation.UnsupportedAppUsage;
28 import android.content.Context;
29 import android.graphics.Point;
30 import android.media.projection.MediaProjection;
31 import android.os.Handler;
32 import android.util.Pair;
33 import android.util.SparseArray;
34 import android.view.Display;
35 import android.view.Surface;
36 
37 import java.util.ArrayList;
38 import java.util.List;
39 
40 /**
41  * Manages the properties of attached displays.
42  */
43 @SystemService(Context.DISPLAY_SERVICE)
44 public final class DisplayManager {
45     private static final String TAG = "DisplayManager";
46     private static final boolean DEBUG = false;
47 
48     private final Context mContext;
49     private final DisplayManagerGlobal mGlobal;
50 
51     private final Object mLock = new Object();
52     private final SparseArray<Display> mDisplays = new SparseArray<Display>();
53 
54     private final ArrayList<Display> mTempDisplays = new ArrayList<Display>();
55 
56     /**
57      * Broadcast receiver that indicates when the Wifi display status changes.
58      * <p>
59      * The status is provided as a {@link WifiDisplayStatus} object in the
60      * {@link #EXTRA_WIFI_DISPLAY_STATUS} extra.
61      * </p><p>
62      * This broadcast is only sent to registered receivers and can only be sent by the system.
63      * </p>
64      * @hide
65      */
66     @UnsupportedAppUsage
67     public static final String ACTION_WIFI_DISPLAY_STATUS_CHANGED =
68             "android.hardware.display.action.WIFI_DISPLAY_STATUS_CHANGED";
69 
70     /**
71      * Contains a {@link WifiDisplayStatus} object.
72      * @hide
73      */
74     @UnsupportedAppUsage
75     public static final String EXTRA_WIFI_DISPLAY_STATUS =
76             "android.hardware.display.extra.WIFI_DISPLAY_STATUS";
77 
78     /**
79      * Display category: Presentation displays.
80      * <p>
81      * This category can be used to identify secondary displays that are suitable for
82      * use as presentation displays such as HDMI or Wireless displays.  Applications
83      * may automatically project their content to presentation displays to provide
84      * richer second screen experiences.
85      * </p>
86      *
87      * @see android.app.Presentation
88      * @see Display#FLAG_PRESENTATION
89      * @see #getDisplays(String)
90      */
91     public static final String DISPLAY_CATEGORY_PRESENTATION =
92             "android.hardware.display.category.PRESENTATION";
93 
94     /**
95      * Virtual display flag: Create a public display.
96      *
97      * <h3>Public virtual displays</h3>
98      * <p>
99      * When this flag is set, the virtual display is public.
100      * </p><p>
101      * A public virtual display behaves just like most any other display that is connected
102      * to the system such as an HDMI or Wireless display.  Applications can open
103      * windows on the display and the system may mirror the contents of other displays
104      * onto it.
105      * </p><p>
106      * Creating a public virtual display that isn't restricted to own-content only implicitly
107      * creates an auto-mirroring display. See {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR} for
108      * restrictions on who is allowed to create an auto-mirroring display.
109      * </p>
110      *
111      * <h3>Private virtual displays</h3>
112      * <p>
113      * When this flag is not set, the virtual display is private as defined by the
114      * {@link Display#FLAG_PRIVATE} display flag.
115      * </p>
116      *
117      * <p>
118      * A private virtual display belongs to the application that created it.  Only the a owner of a
119      * private virtual display and the apps that are already on that display are allowed to place
120      * windows upon it.  The private virtual display also does not participate in display mirroring:
121      * it will neither receive mirrored content from another display nor allow its own content to be
122      * mirrored elsewhere.  More precisely, the only processes that are allowed to enumerate or
123      * interact with the private display are those that have the same UID as the application that
124      * originally created the private virtual display or as the activities that are already on that
125      * display.
126      * </p>
127      *
128      * @see #createVirtualDisplay
129      * @see #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY
130      * @see #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR
131      */
132     public static final int VIRTUAL_DISPLAY_FLAG_PUBLIC = 1 << 0;
133 
134     /**
135      * Virtual display flag: Create a presentation display.
136      *
137      * <h3>Presentation virtual displays</h3>
138      * <p>
139      * When this flag is set, the virtual display is registered as a presentation
140      * display in the {@link #DISPLAY_CATEGORY_PRESENTATION presentation display category}.
141      * Applications may automatically project their content to presentation displays
142      * to provide richer second screen experiences.
143      * </p>
144      *
145      * <h3>Non-presentation virtual displays</h3>
146      * <p>
147      * When this flag is not set, the virtual display is not registered as a presentation
148      * display.  Applications can still project their content on the display but they
149      * will typically not do so automatically.  This option is appropriate for
150      * more special-purpose displays.
151      * </p>
152      *
153      * @see android.app.Presentation
154      * @see #createVirtualDisplay
155      * @see #DISPLAY_CATEGORY_PRESENTATION
156      * @see Display#FLAG_PRESENTATION
157      */
158     public static final int VIRTUAL_DISPLAY_FLAG_PRESENTATION = 1 << 1;
159 
160     /**
161      * Virtual display flag: Create a secure display.
162      *
163      * <h3>Secure virtual displays</h3>
164      * <p>
165      * When this flag is set, the virtual display is considered secure as defined
166      * by the {@link Display#FLAG_SECURE} display flag.  The caller promises to take
167      * reasonable measures, such as over-the-air encryption, to prevent the contents
168      * of the display from being intercepted or recorded on a persistent medium.
169      * </p><p>
170      * Creating a secure virtual display requires the CAPTURE_SECURE_VIDEO_OUTPUT permission.
171      * This permission is reserved for use by system components and is not available to
172      * third-party applications.
173      * </p>
174      *
175      * <h3>Non-secure virtual displays</h3>
176      * <p>
177      * When this flag is not set, the virtual display is considered unsecure.
178      * The content of secure windows will be blanked if shown on this display.
179      * </p>
180      *
181      * @see Display#FLAG_SECURE
182      * @see #createVirtualDisplay
183      */
184     public static final int VIRTUAL_DISPLAY_FLAG_SECURE = 1 << 2;
185 
186     /**
187      * Virtual display flag: Only show this display's own content; do not mirror
188      * the content of another display.
189      *
190      * <p>
191      * This flag is used in conjunction with {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}.
192      * Ordinarily public virtual displays will automatically mirror the content of the
193      * default display if they have no windows of their own.  When this flag is
194      * specified, the virtual display will only ever show its own content and
195      * will be blanked instead if it has no windows.
196      * </p>
197      *
198      * <p>
199      * This flag is mutually exclusive with {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR}.  If both
200      * flags are specified then the own-content only behavior will be applied.
201      * </p>
202      *
203      * <p>
204      * This behavior of this flag is implied whenever neither {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}
205      * nor {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR} have been set.  This flag is only required to
206      * override the default behavior when creating a public display.
207      * </p>
208      *
209      * @see #createVirtualDisplay
210      */
211     public static final int VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY = 1 << 3;
212 
213 
214     /**
215      * Virtual display flag: Allows content to be mirrored on private displays when no content is
216      * being shown.
217      *
218      * <p>
219      * This flag is mutually exclusive with {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY}.
220      * If both flags are specified then the own-content only behavior will be applied.
221      * </p>
222      *
223      * <p>
224      * The behavior of this flag is implied whenever {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC} is set
225      * and {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY} has not been set.   This flag is only
226      * required to override the default behavior when creating a private display.
227      * </p>
228      *
229      * <p>
230      * Creating an auto-mirroing virtual display requires the CAPTURE_VIDEO_OUTPUT
231      * or CAPTURE_SECURE_VIDEO_OUTPUT permission.
232      * These permissions are reserved for use by system components and are not available to
233      * third-party applications.
234      *
235      * Alternatively, an appropriate {@link MediaProjection} may be used to create an
236      * auto-mirroring virtual display.
237      * </p>
238      *
239      * @see #createVirtualDisplay
240      */
241     public static final int VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR = 1 << 4;
242 
243     /**
244      * Virtual display flag: Allows content to be displayed on private virtual displays when
245      * keyguard is shown but is insecure.
246      *
247      * <p>
248      * This might be used in a case when the content of a virtual display is captured and sent to an
249      * external hardware display that is not visible to the system directly. This flag will allow
250      * the continued display of content while other displays will be covered by a keyguard which
251      * doesn't require providing credentials to unlock. This means that there is either no password
252      * or other authentication method set, or the device is in a trusted state -
253      * {@link android.service.trust.TrustAgentService} has available and active trust agent.
254      * </p><p>
255      * This flag can only be applied to private displays as defined by the
256      * {@link Display#FLAG_PRIVATE} display flag. It is mutually exclusive with
257      * {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}. If both flags are specified then this flag's behavior
258      * will not be applied.
259      * </p>
260      *
261      * @see #createVirtualDisplay
262      * @see KeyguardManager#isDeviceSecure()
263      * @see KeyguardManager#isDeviceLocked()
264      * @hide
265      */
266     // TODO (b/114338689): Remove the flag and use IWindowManager#shouldShowWithInsecureKeyguard
267     // TODO: Update name and documentation and un-hide the flag. Don't change the value before that.
268     public static final int VIRTUAL_DISPLAY_FLAG_CAN_SHOW_WITH_INSECURE_KEYGUARD = 1 << 5;
269 
270     /**
271      * Virtual display flag: Specifies that the virtual display can be associated with a
272      * touchpad device that matches its uniqueId.
273      *
274      * @see #createVirtualDisplay
275      * @hide
276      */
277     public static final int VIRTUAL_DISPLAY_FLAG_SUPPORTS_TOUCH = 1 << 6;
278 
279     /**
280      * Virtual display flag: Indicates that the orientation of this display device is coupled to
281      * the rotation of its associated logical display.
282      *
283      * @see #createVirtualDisplay
284      * @hide
285      */
286     public static final int VIRTUAL_DISPLAY_FLAG_ROTATES_WITH_CONTENT = 1 << 7;
287 
288     /**
289      * Virtual display flag: Indicates that the contents will be destroyed once
290      * the display is removed.
291      *
292      * Public virtual displays without this flag will move their content to main display
293      * stack once they're removed. Private vistual displays will always destroy their
294      * content on removal even without this flag.
295      *
296      * @see #createVirtualDisplay
297      * @hide
298      */
299     // TODO (b/114338689): Remove the flag and use WindowManager#REMOVE_CONTENT_MODE_DESTROY
300     public static final int VIRTUAL_DISPLAY_FLAG_DESTROY_CONTENT_ON_REMOVAL = 1 << 8;
301 
302     /**
303      * Virtual display flag: Indicates that the display should support system decorations. Virtual
304      * displays without this flag shouldn't show home, IME or any other system decorations.
305      *
306      * @see #createVirtualDisplay
307      * @hide
308      */
309     // TODO (b/114338689): Remove the flag and use IWindowManager#setShouldShowSystemDecors
310     public static final int VIRTUAL_DISPLAY_FLAG_SHOULD_SHOW_SYSTEM_DECORATIONS = 1 << 9;
311 
312     /** @hide */
DisplayManager(Context context)313     public DisplayManager(Context context) {
314         mContext = context;
315         mGlobal = DisplayManagerGlobal.getInstance();
316     }
317 
318     /**
319      * Gets information about a logical display.
320      *
321      * The display metrics may be adjusted to provide compatibility
322      * for legacy applications.
323      *
324      * @param displayId The logical display id.
325      * @return The display object, or null if there is no valid display with the given id.
326      */
getDisplay(int displayId)327     public Display getDisplay(int displayId) {
328         synchronized (mLock) {
329             return getOrCreateDisplayLocked(displayId, false /*assumeValid*/);
330         }
331     }
332 
333     /**
334      * Gets all currently valid logical displays.
335      *
336      * @return An array containing all displays.
337      */
getDisplays()338     public Display[] getDisplays() {
339         return getDisplays(null);
340     }
341 
342     /**
343      * Gets all currently valid logical displays of the specified category.
344      * <p>
345      * When there are multiple displays in a category the returned displays are sorted
346      * of preference.  For example, if the requested category is
347      * {@link #DISPLAY_CATEGORY_PRESENTATION} and there are multiple presentation displays
348      * then the displays are sorted so that the first display in the returned array
349      * is the most preferred presentation display.  The application may simply
350      * use the first display or allow the user to choose.
351      * </p>
352      *
353      * @param category The requested display category or null to return all displays.
354      * @return An array containing all displays sorted by order of preference.
355      *
356      * @see #DISPLAY_CATEGORY_PRESENTATION
357      */
getDisplays(String category)358     public Display[] getDisplays(String category) {
359         final int[] displayIds = mGlobal.getDisplayIds();
360         synchronized (mLock) {
361             try {
362                 if (category == null) {
363                     addAllDisplaysLocked(mTempDisplays, displayIds);
364                 } else if (category.equals(DISPLAY_CATEGORY_PRESENTATION)) {
365                     addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_WIFI);
366                     addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_HDMI);
367                     addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_OVERLAY);
368                     addPresentationDisplaysLocked(mTempDisplays, displayIds, Display.TYPE_VIRTUAL);
369                 }
370                 return mTempDisplays.toArray(new Display[mTempDisplays.size()]);
371             } finally {
372                 mTempDisplays.clear();
373             }
374         }
375     }
376 
addAllDisplaysLocked(ArrayList<Display> displays, int[] displayIds)377     private void addAllDisplaysLocked(ArrayList<Display> displays, int[] displayIds) {
378         for (int i = 0; i < displayIds.length; i++) {
379             Display display = getOrCreateDisplayLocked(displayIds[i], true /*assumeValid*/);
380             if (display != null) {
381                 displays.add(display);
382             }
383         }
384     }
385 
addPresentationDisplaysLocked( ArrayList<Display> displays, int[] displayIds, int matchType)386     private void addPresentationDisplaysLocked(
387             ArrayList<Display> displays, int[] displayIds, int matchType) {
388         for (int i = 0; i < displayIds.length; i++) {
389             Display display = getOrCreateDisplayLocked(displayIds[i], true /*assumeValid*/);
390             if (display != null
391                     && (display.getFlags() & Display.FLAG_PRESENTATION) != 0
392                     && display.getType() == matchType) {
393                 displays.add(display);
394             }
395         }
396     }
397 
getOrCreateDisplayLocked(int displayId, boolean assumeValid)398     private Display getOrCreateDisplayLocked(int displayId, boolean assumeValid) {
399         Display display = mDisplays.get(displayId);
400         if (display == null) {
401             // TODO: We cannot currently provide any override configurations for metrics on displays
402             // other than the display the context is associated with.
403             final Context context = mContext.getDisplayId() == displayId
404                     ? mContext : mContext.getApplicationContext();
405 
406             display = mGlobal.getCompatibleDisplay(displayId, context.getResources());
407             if (display != null) {
408                 mDisplays.put(displayId, display);
409             }
410         } else if (!assumeValid && !display.isValid()) {
411             display = null;
412         }
413         return display;
414     }
415 
416     /**
417      * Registers an display listener to receive notifications about when
418      * displays are added, removed or changed.
419      *
420      * @param listener The listener to register.
421      * @param handler The handler on which the listener should be invoked, or null
422      * if the listener should be invoked on the calling thread's looper.
423      *
424      * @see #unregisterDisplayListener
425      */
registerDisplayListener(DisplayListener listener, Handler handler)426     public void registerDisplayListener(DisplayListener listener, Handler handler) {
427         mGlobal.registerDisplayListener(listener, handler);
428     }
429 
430     /**
431      * Unregisters a display listener.
432      *
433      * @param listener The listener to unregister.
434      *
435      * @see #registerDisplayListener
436      */
unregisterDisplayListener(DisplayListener listener)437     public void unregisterDisplayListener(DisplayListener listener) {
438         mGlobal.unregisterDisplayListener(listener);
439     }
440 
441     /**
442      * Starts scanning for available Wifi displays.
443      * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast.
444      * <p>
445      * Calls to this method nest and must be matched by an equal number of calls to
446      * {@link #stopWifiDisplayScan()}.
447      * </p><p>
448      * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.
449      * </p>
450      *
451      * @hide
452      */
453     @UnsupportedAppUsage
startWifiDisplayScan()454     public void startWifiDisplayScan() {
455         mGlobal.startWifiDisplayScan();
456     }
457 
458     /**
459      * Stops scanning for available Wifi displays.
460      * <p>
461      * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.
462      * </p>
463      *
464      * @hide
465      */
466     @UnsupportedAppUsage
stopWifiDisplayScan()467     public void stopWifiDisplayScan() {
468         mGlobal.stopWifiDisplayScan();
469     }
470 
471     /**
472      * Connects to a Wifi display.
473      * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast.
474      * <p>
475      * Automatically remembers the display after a successful connection, if not
476      * already remembered.
477      * </p><p>
478      * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.
479      * </p>
480      *
481      * @param deviceAddress The MAC address of the device to which we should connect.
482      * @hide
483      */
484     @UnsupportedAppUsage
connectWifiDisplay(String deviceAddress)485     public void connectWifiDisplay(String deviceAddress) {
486         mGlobal.connectWifiDisplay(deviceAddress);
487     }
488 
489     /** @hide */
490     @UnsupportedAppUsage
pauseWifiDisplay()491     public void pauseWifiDisplay() {
492         mGlobal.pauseWifiDisplay();
493     }
494 
495     /** @hide */
496     @UnsupportedAppUsage
resumeWifiDisplay()497     public void resumeWifiDisplay() {
498         mGlobal.resumeWifiDisplay();
499     }
500 
501     /**
502      * Disconnects from the current Wifi display.
503      * The results are sent as a {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED} broadcast.
504      * @hide
505      */
506     @UnsupportedAppUsage
disconnectWifiDisplay()507     public void disconnectWifiDisplay() {
508         mGlobal.disconnectWifiDisplay();
509     }
510 
511     /**
512      * Renames a Wifi display.
513      * <p>
514      * The display must already be remembered for this call to succeed.  In other words,
515      * we must already have successfully connected to the display at least once and then
516      * not forgotten it.
517      * </p><p>
518      * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.
519      * </p>
520      *
521      * @param deviceAddress The MAC address of the device to rename.
522      * @param alias The alias name by which to remember the device, or null
523      * or empty if no alias should be used.
524      * @hide
525      */
526     @UnsupportedAppUsage
renameWifiDisplay(String deviceAddress, String alias)527     public void renameWifiDisplay(String deviceAddress, String alias) {
528         mGlobal.renameWifiDisplay(deviceAddress, alias);
529     }
530 
531     /**
532      * Forgets a previously remembered Wifi display.
533      * <p>
534      * Automatically disconnects from the display if currently connected to it.
535      * </p><p>
536      * Requires {@link android.Manifest.permission#CONFIGURE_WIFI_DISPLAY}.
537      * </p>
538      *
539      * @param deviceAddress The MAC address of the device to forget.
540      * @hide
541      */
542     @UnsupportedAppUsage
forgetWifiDisplay(String deviceAddress)543     public void forgetWifiDisplay(String deviceAddress) {
544         mGlobal.forgetWifiDisplay(deviceAddress);
545     }
546 
547     /**
548      * Gets the current Wifi display status.
549      * Watch for changes in the status by registering a broadcast receiver for
550      * {@link #ACTION_WIFI_DISPLAY_STATUS_CHANGED}.
551      *
552      * @return The current Wifi display status.
553      * @hide
554      */
555     @UnsupportedAppUsage
getWifiDisplayStatus()556     public WifiDisplayStatus getWifiDisplayStatus() {
557         return mGlobal.getWifiDisplayStatus();
558     }
559 
560     /**
561      * Set the level of color saturation to apply to the display.
562      * @param level The amount of saturation to apply, between 0 and 1 inclusive.
563      * 0 produces a grayscale image, 1 is normal.
564      *
565      * @hide
566      * @deprecated use {@link ColorDisplayManager#setSaturationLevel(int)} instead. The level passed
567      * as a parameter here will be rounded to the nearest hundredth.
568      */
569     @SystemApi
570     @RequiresPermission(Manifest.permission.CONTROL_DISPLAY_SATURATION)
setSaturationLevel(float level)571     public void setSaturationLevel(float level) {
572         if (level < 0f || level > 1f) {
573             throw new IllegalArgumentException("Saturation level must be between 0 and 1");
574         }
575         final ColorDisplayManager cdm = mContext.getSystemService(ColorDisplayManager.class);
576         cdm.setSaturationLevel(Math.round(level * 100f));
577     }
578 
579     /**
580      * Creates a virtual display.
581      *
582      * @see #createVirtualDisplay(String, int, int, int, Surface, int,
583      * VirtualDisplay.Callback, Handler)
584      */
createVirtualDisplay(@onNull String name, int width, int height, int densityDpi, @Nullable Surface surface, int flags)585     public VirtualDisplay createVirtualDisplay(@NonNull String name,
586             int width, int height, int densityDpi, @Nullable Surface surface, int flags) {
587         return createVirtualDisplay(name, width, height, densityDpi, surface, flags, null, null);
588     }
589 
590     /**
591      * Creates a virtual display.
592      * <p>
593      * The content of a virtual display is rendered to a {@link Surface} provided
594      * by the application.
595      * </p><p>
596      * The virtual display should be {@link VirtualDisplay#release released}
597      * when no longer needed.  Because a virtual display renders to a surface
598      * provided by the application, it will be released automatically when the
599      * process terminates and all remaining windows on it will be forcibly removed.
600      * </p><p>
601      * The behavior of the virtual display depends on the flags that are provided
602      * to this method.  By default, virtual displays are created to be private,
603      * non-presentation and unsecure.  Permissions may be required to use certain flags.
604      * </p><p>
605      * As of {@link android.os.Build.VERSION_CODES#KITKAT_WATCH}, the surface may
606      * be attached or detached dynamically using {@link VirtualDisplay#setSurface}.
607      * Previously, the surface had to be non-null when {@link #createVirtualDisplay}
608      * was called and could not be changed for the lifetime of the display.
609      * </p><p>
610      * Detaching the surface that backs a virtual display has a similar effect to
611      * turning off the screen.
612      * </p>
613      *
614      * @param name The name of the virtual display, must be non-empty.
615      * @param width The width of the virtual display in pixels, must be greater than 0.
616      * @param height The height of the virtual display in pixels, must be greater than 0.
617      * @param densityDpi The density of the virtual display in dpi, must be greater than 0.
618      * @param surface The surface to which the content of the virtual display should
619      * be rendered, or null if there is none initially.
620      * @param flags A combination of virtual display flags:
621      * {@link #VIRTUAL_DISPLAY_FLAG_PUBLIC}, {@link #VIRTUAL_DISPLAY_FLAG_PRESENTATION},
622      * {@link #VIRTUAL_DISPLAY_FLAG_SECURE}, {@link #VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY},
623      * or {@link #VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR}.
624      * @param callback Callback to call when the state of the {@link VirtualDisplay} changes
625      * @param handler The handler on which the listener should be invoked, or null
626      * if the listener should be invoked on the calling thread's looper.
627      * @return The newly created virtual display, or null if the application could
628      * not create the virtual display.
629      *
630      * @throws SecurityException if the caller does not have permission to create
631      * a virtual display with the specified flags.
632      */
createVirtualDisplay(@onNull String name, int width, int height, int densityDpi, @Nullable Surface surface, int flags, @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler)633     public VirtualDisplay createVirtualDisplay(@NonNull String name,
634             int width, int height, int densityDpi, @Nullable Surface surface, int flags,
635             @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler) {
636         return createVirtualDisplay(null /* projection */, name, width, height, densityDpi, surface,
637                 flags, callback, handler, null /* uniqueId */);
638     }
639 
640     /** @hide */
createVirtualDisplay(@ullable MediaProjection projection, @NonNull String name, int width, int height, int densityDpi, @Nullable Surface surface, int flags, @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler, @Nullable String uniqueId)641     public VirtualDisplay createVirtualDisplay(@Nullable MediaProjection projection,
642             @NonNull String name, int width, int height, int densityDpi, @Nullable Surface surface,
643             int flags, @Nullable VirtualDisplay.Callback callback, @Nullable Handler handler,
644             @Nullable String uniqueId) {
645         return mGlobal.createVirtualDisplay(mContext, projection,
646                 name, width, height, densityDpi, surface, flags, callback, handler, uniqueId);
647     }
648 
649     /**
650      * Gets the stable device display size, in pixels.
651      *
652      * This should really only be used for things like server-side filtering of available
653      * applications. Most applications don't need the level of stability guaranteed by this and
654      * should instead query either the size of the display they're currently running on or the
655      * size of the default display.
656      * @hide
657      */
658     @SystemApi
659     @TestApi
getStableDisplaySize()660     public Point getStableDisplaySize() {
661         return mGlobal.getStableDisplaySize();
662     }
663 
664     /**
665      * Fetch {@link BrightnessChangeEvent}s.
666      * @hide until we make it a system api.
667      */
668     @SystemApi
669     @TestApi
670     @RequiresPermission(Manifest.permission.BRIGHTNESS_SLIDER_USAGE)
getBrightnessEvents()671     public List<BrightnessChangeEvent> getBrightnessEvents() {
672         return mGlobal.getBrightnessEvents(mContext.getOpPackageName());
673     }
674 
675     /**
676      * Fetch {@link AmbientBrightnessDayStats}s.
677      *
678      * @hide until we make it a system api
679      */
680     @SystemApi
681     @TestApi
682     @RequiresPermission(Manifest.permission.ACCESS_AMBIENT_LIGHT_STATS)
getAmbientBrightnessStats()683     public List<AmbientBrightnessDayStats> getAmbientBrightnessStats() {
684         return mGlobal.getAmbientBrightnessStats();
685     }
686 
687     /**
688      * Sets the global display brightness configuration.
689      *
690      * @hide
691      */
692     @SystemApi
693     @TestApi
694     @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS)
setBrightnessConfiguration(BrightnessConfiguration c)695     public void setBrightnessConfiguration(BrightnessConfiguration c) {
696         setBrightnessConfigurationForUser(c, mContext.getUserId(), mContext.getPackageName());
697     }
698 
699     /**
700      * Sets the global display brightness configuration for a specific user.
701      *
702      * Note this requires the INTERACT_ACROSS_USERS permission if setting the configuration for a
703      * user other than the one you're currently running as.
704      *
705      * @hide
706      */
setBrightnessConfigurationForUser(BrightnessConfiguration c, int userId, String packageName)707     public void setBrightnessConfigurationForUser(BrightnessConfiguration c, int userId,
708             String packageName) {
709         mGlobal.setBrightnessConfigurationForUser(c, userId, packageName);
710     }
711 
712     /**
713      * Gets the global display brightness configuration or the default curve if one hasn't been set.
714      *
715      * @hide
716      */
717     @SystemApi
718     @TestApi
719     @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS)
getBrightnessConfiguration()720     public BrightnessConfiguration getBrightnessConfiguration() {
721         return getBrightnessConfigurationForUser(mContext.getUserId());
722     }
723 
724     /**
725      * Gets the global display brightness configuration or the default curve if one hasn't been set
726      * for a specific user.
727      *
728      * Note this requires the INTERACT_ACROSS_USERS permission if getting the configuration for a
729      * user other than the one you're currently running as.
730      *
731      * @hide
732      */
getBrightnessConfigurationForUser(int userId)733     public BrightnessConfiguration getBrightnessConfigurationForUser(int userId) {
734         return mGlobal.getBrightnessConfigurationForUser(userId);
735     }
736 
737     /**
738      * Gets the default global display brightness configuration or null one hasn't
739      * been configured.
740      *
741      * @hide
742      */
743     @SystemApi
744     @TestApi
745     @RequiresPermission(Manifest.permission.CONFIGURE_DISPLAY_BRIGHTNESS)
746     @Nullable
getDefaultBrightnessConfiguration()747     public BrightnessConfiguration getDefaultBrightnessConfiguration() {
748         return mGlobal.getDefaultBrightnessConfiguration();
749     }
750 
751     /**
752      * Temporarily sets the brightness of the display.
753      * <p>
754      * Requires the {@link android.Manifest.permission#CONTROL_DISPLAY_BRIGHTNESS} permission.
755      * </p>
756      *
757      * @param brightness The brightness value from 0 to 255.
758      *
759      * @hide Requires signature permission.
760      */
setTemporaryBrightness(int brightness)761     public void setTemporaryBrightness(int brightness) {
762         mGlobal.setTemporaryBrightness(brightness);
763     }
764 
765     /**
766      * Temporarily sets the auto brightness adjustment factor.
767      * <p>
768      * Requires the {@link android.Manifest.permission#CONTROL_DISPLAY_BRIGHTNESS} permission.
769      * </p>
770      *
771      * @param adjustment The adjustment factor from -1.0 to 1.0.
772      *
773      * @hide Requires signature permission.
774      */
setTemporaryAutoBrightnessAdjustment(float adjustment)775     public void setTemporaryAutoBrightnessAdjustment(float adjustment) {
776         mGlobal.setTemporaryAutoBrightnessAdjustment(adjustment);
777     }
778 
779     /**
780      * Returns the minimum brightness curve, which guarantess that any brightness curve that dips
781      * below it is rejected by the system.
782      * This prevent auto-brightness from setting the screen so dark as to prevent the user from
783      * resetting or disabling it, and maps lux to the absolute minimum nits that are still readable
784      * in that ambient brightness.
785      *
786      * @return The minimum brightness curve (as lux values and their corresponding nits values).
787      *
788      * @hide
789      */
790     @SystemApi
getMinimumBrightnessCurve()791     public Pair<float[], float[]> getMinimumBrightnessCurve() {
792         return mGlobal.getMinimumBrightnessCurve();
793     }
794 
795     /**
796      * Listens for changes in available display devices.
797      */
798     public interface DisplayListener {
799         /**
800          * Called whenever a logical display has been added to the system.
801          * Use {@link DisplayManager#getDisplay} to get more information about
802          * the display.
803          *
804          * @param displayId The id of the logical display that was added.
805          */
onDisplayAdded(int displayId)806         void onDisplayAdded(int displayId);
807 
808         /**
809          * Called whenever a logical display has been removed from the system.
810          *
811          * @param displayId The id of the logical display that was removed.
812          */
onDisplayRemoved(int displayId)813         void onDisplayRemoved(int displayId);
814 
815         /**
816          * Called whenever the properties of a logical {@link android.view.Display},
817          * such as size and density, have changed.
818          *
819          * @param displayId The id of the logical display that changed.
820          */
onDisplayChanged(int displayId)821         void onDisplayChanged(int displayId);
822     }
823 
824     /**
825      * Interface for accessing keys belonging to {@link
826      * android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER}.
827      * @hide
828      */
829     public interface DeviceConfig {
830 
831         /**
832          * Key for refresh rate in the zone defined by thresholds.
833          *
834          * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER
835          * @see android.R.integer#config_defaultZoneBehavior
836          */
837         String KEY_REFRESH_RATE_IN_ZONE = "refresh_rate_in_zone";
838 
839         /**
840          * Key for accessing the display brightness thresholds for the configured refresh rate zone.
841          * The value will be a pair of comma separated integers representing the minimum and maximum
842          * thresholds of the zone, respectively, in display backlight units (i.e. [0, 255]).
843          *
844          * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER
845          * @see android.R.array#config_brightnessThresholdsOfPeakRefreshRate
846          * @hide
847          */
848         String KEY_PEAK_REFRESH_RATE_DISPLAY_BRIGHTNESS_THRESHOLDS =
849                 "peak_refresh_rate_brightness_thresholds";
850 
851         /**
852          * Key for accessing the ambient brightness thresholds for the configured refresh rate zone.
853          * The value will be a pair of comma separated integers representing the minimum and maximum
854          * thresholds of the zone, respectively, in lux.
855          *
856          * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER
857          * @see android.R.array#config_ambientThresholdsOfPeakRefreshRate
858          * @hide
859          */
860         String KEY_PEAK_REFRESH_RATE_AMBIENT_BRIGHTNESS_THRESHOLDS =
861                 "peak_refresh_rate_ambient_thresholds";
862 
863         /**
864          * Key for default peak refresh rate
865          *
866          * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER
867          * @see android.R.integer#config_defaultPeakRefreshRate
868          * @hide
869          */
870         String KEY_PEAK_REFRESH_RATE_DEFAULT = "peak_refresh_rate_default";
871 
872         /**
873          * Key for controlling which packages are explicitly blocked from running at refresh rates
874          * higher than 60hz. An app may be added to this list if they exhibit performance issues at
875          * higher refresh rates.
876          *
877          * @see android.provider.DeviceConfig#NAMESPACE_DISPLAY_MANAGER
878          * @see android.R.array#config_highRefreshRateBlacklist
879          * @hide
880          */
881         String KEY_HIGH_REFRESH_RATE_BLACKLIST = "high_refresh_rate_blacklist";
882     }
883 }
884