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.view.Display; 19import 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 */ 34public final class VirtualDisplay { 35 private final DisplayManagerGlobal mGlobal; 36 private final Display mDisplay; 37 private IVirtualDisplayCallback mToken; 38 private Surface mSurface; 39 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 */ 51 public Display getDisplay() { 52 return mDisplay; 53 } 54 55 /** 56 * Gets the surface that backs the virtual display. 57 */ 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 */ 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 */ 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 */ 100 public void release() { 101 if (mToken != null) { 102 mGlobal.releaseVirtualDisplay(mToken); 103 mToken = null; 104 } 105 } 106 107 @Override 108 public String toString() { 109 return "VirtualDisplay{display=" + mDisplay + ", token=" + mToken 110 + ", surface=" + mSurface + "}"; 111 } 112 113 /** 114 * Interface for receiving information about a {@link VirtualDisplay}'s state changes. 115 */ 116 public static abstract class Callback { 117 /** 118 * Called when the virtual display video projection has been 119 * paused by the system or when the surface has been detached 120 * by the application by calling setSurface(null). 121 * The surface will not receive any more buffers while paused. 122 */ 123 public void onPaused() { } 124 125 /** 126 * Called when the virtual display video projection has been 127 * resumed after having been paused. 128 */ 129 public void onResumed() { } 130 131 /** 132 * Called when the virtual display video projection has been 133 * stopped by the system. It will no longer receive frames 134 * and it will never be resumed. It is still the responsibility 135 * of the application to release() the virtual display. 136 */ 137 public void onStopped() { } 138 } 139} 140