1 /*
2  * Copyright (C) 2013 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 package android.hardware.display;
17 
18 import android.annotation.Nullable;
19 import android.content.Context;
20 import android.view.Display;
21 import android.view.Surface;
22 
23 /**
24  * Represents a virtual display. The content of a virtual display is rendered to a
25  * {@link android.view.Surface} that you must provide to {@link DisplayManager#createVirtualDisplay
26  * createVirtualDisplay()}.
27  * <p>
28  * Because a virtual display renders to a surface provided by the application, it will be
29  * released automatically when the process terminates and all remaining windows on it will
30  * be forcibly removed.  However, you should also explicitly call {@link #release} when
31  * you're done with it.
32  * </p>
33  *
34  * @see DisplayManager#createVirtualDisplay
35  */
36 public final class VirtualDisplay {
37     private final DisplayManagerGlobal mGlobal;
38     private final Display mDisplay;
39     private IVirtualDisplayCallback mToken;
40     private Surface mSurface;
41     /**
42      * Store the WindowContext in a field. If it is a local variable, and it is garbage collected
43      * during a MediaProjection session, the WindowContainer listener no longer exists.
44      */
45     @Nullable private final Context mWindowContext;
46 
VirtualDisplay(DisplayManagerGlobal global, Display display, IVirtualDisplayCallback token, Surface surface, Context windowContext)47     VirtualDisplay(DisplayManagerGlobal global, Display display,
48             IVirtualDisplayCallback token, Surface surface, Context windowContext) {
49         mGlobal = global;
50         mDisplay = display;
51         mToken = token;
52         mSurface = surface;
53         mWindowContext = windowContext;
54     }
55 
56     /**
57      * Gets the virtual display.
58      */
getDisplay()59     public Display getDisplay() {
60         return mDisplay;
61     }
62 
63     /**
64      * Gets the surface that backs the virtual display.
65      */
getSurface()66     public Surface getSurface() {
67         return mSurface;
68     }
69 
70     /**
71      * Sets the surface that backs the virtual display.
72      * <p>
73      * Detaching the surface that backs a virtual display has a similar effect to
74      * turning off the screen.
75      * </p><p>
76      * It is still the caller's responsibility to destroy the surface after it has
77      * been detached.
78      * </p>
79      *
80      * @param surface The surface to set, or null to detach the surface from the virtual display.
81      */
setSurface(Surface surface)82     public void setSurface(Surface surface) {
83         if (mSurface != surface) {
84             mGlobal.setVirtualDisplaySurface(mToken, surface);
85             mSurface = surface;
86         }
87     }
88 
89     /**
90      * Asks the virtual display to resize.
91      *<p>
92      * This is really just a convenience to allow applications using
93      * virtual displays to adapt to changing conditions without having
94      * to tear down and recreate the display.
95      * </p>
96      */
resize(int width, int height, int densityDpi)97     public void resize(int width, int height, int densityDpi) {
98         mGlobal.resizeVirtualDisplay(mToken, width, height, densityDpi);
99     }
100 
101     /**
102      * Releases the virtual display and destroys its underlying surface.
103      * <p>
104      * All remaining windows on the virtual display will be forcibly removed
105      * as part of releasing the virtual display.
106      * </p>
107      */
release()108     public void release() {
109         if (mToken != null) {
110             mGlobal.releaseVirtualDisplay(mToken);
111             mToken = null;
112         }
113     }
114 
115     /**
116      * Sets the on/off state for a virtual display.
117      *
118      * @param isOn Whether the display should be on or off.
119      * @hide
120      */
setDisplayState(boolean isOn)121     public void setDisplayState(boolean isOn) {
122         if (mToken != null) {
123             mGlobal.setVirtualDisplayState(mToken, isOn);
124         }
125     }
126 
127     @Override
toString()128     public String toString() {
129         return "VirtualDisplay{display=" + mDisplay + ", token=" + mToken
130                 + ", surface=" + mSurface + "}";
131     }
132 
133     /**
134      * Interface for receiving information about a {@link VirtualDisplay}'s state changes.
135      */
136     public static abstract class Callback {
137         /**
138          * Called when the virtual display video projection has been
139          * paused by the system or when the surface has been detached
140          * by the application by calling setSurface(null).
141          * The surface will not receive any more buffers while paused.
142          */
onPaused()143          public void onPaused() { }
144 
145         /**
146          * Called when the virtual display video projection has been
147          * resumed after having been paused.
148          */
onResumed()149          public void onResumed() { }
150 
151         /**
152          * Called when the virtual display video projection has been
153          * stopped by the system.  It will no longer receive frames
154          * and it will never be resumed.  It is still the responsibility
155          * of the application to release() the virtual display.
156          */
onStopped()157         public void onStopped() { }
158     }
159 }
160