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