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