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.FlaggedApi; 19 import android.view.Display; 20 import 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 */ 35 public final class VirtualDisplay { 36 private final DisplayManagerGlobal mGlobal; 37 private final Display mDisplay; 38 private IVirtualDisplayCallback mToken; 39 private Surface mSurface; VirtualDisplay(DisplayManagerGlobal global, Display display, IVirtualDisplayCallback token, Surface surface)40 VirtualDisplay(DisplayManagerGlobal global, Display display, IVirtualDisplayCallback token, 41 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 * @hide 64 */ getToken()65 public IVirtualDisplayCallback getToken() { 66 return mToken; 67 } 68 69 /** 70 * Sets the surface that backs the virtual display. 71 * <p> 72 * Detaching the surface that backs a virtual display has a similar effect to 73 * turning off the screen. 74 * </p><p> 75 * It is still the caller's responsibility to destroy the surface after it has 76 * been detached. 77 * </p> 78 * 79 * @param surface The surface to set, or null to detach the surface from the virtual display. 80 */ setSurface(Surface surface)81 public void setSurface(Surface surface) { 82 if (mSurface != surface) { 83 mGlobal.setVirtualDisplaySurface(mToken, surface); 84 mSurface = surface; 85 } 86 } 87 88 /** 89 * Asks the virtual display to resize. 90 *<p> 91 * This is really just a convenience to allow applications using 92 * virtual displays to adapt to changing conditions without having 93 * to tear down and recreate the display. 94 * </p> 95 */ resize(int width, int height, int densityDpi)96 public void resize(int width, int height, int densityDpi) { 97 mGlobal.resizeVirtualDisplay(mToken, width, height, densityDpi); 98 } 99 100 /** 101 * Releases the virtual display and destroys its underlying surface. 102 * <p> 103 * All remaining windows on the virtual display will be forcibly removed 104 * as part of releasing the virtual display. 105 * </p> 106 */ release()107 public void release() { 108 if (mToken != null) { 109 mGlobal.releaseVirtualDisplay(mToken); 110 mToken = null; 111 } 112 } 113 114 /** 115 * Sets the rotation of the virtual display. 116 * 117 * @param rotation the new rotation of the display. May be one of {@link Surface#ROTATION_0}, 118 * {@link Surface#ROTATION_90}, {@link Surface#ROTATION_180}, {@link Surface#ROTATION_270}. 119 * Upon creation, the rotation of the virtual display is always {@link Surface#ROTATION_0}. 120 */ 121 @FlaggedApi(android.companion.virtualdevice.flags.Flags.FLAG_VIRTUAL_DISPLAY_ROTATION_API) setRotation(@urface.Rotation int rotation)122 public void setRotation(@Surface.Rotation int rotation) { 123 if (!android.companion.virtualdevice.flags.Flags.virtualDisplayRotationApi()) { 124 return; 125 } 126 if (rotation != Surface.ROTATION_0 && rotation != Surface.ROTATION_90 127 && rotation != Surface.ROTATION_180 && rotation != Surface.ROTATION_270) { 128 throw new IllegalArgumentException( 129 "Invalid virtual display rotation value: " + rotation); 130 } 131 if (mToken != null && mDisplay.getRotation() != rotation) { 132 mGlobal.setVirtualDisplayRotation(mToken, rotation); 133 } 134 } 135 136 @Override toString()137 public String toString() { 138 return "VirtualDisplay{display=" + mDisplay + ", token=" + mToken 139 + ", surface=" + mSurface + "}"; 140 } 141 142 /** 143 * Interface for receiving information about a {@link VirtualDisplay}'s state changes. 144 */ 145 public static abstract class Callback { 146 /** 147 * Called when the virtual display video projection has been 148 * paused by the system or when the surface has been detached 149 * by the application by calling setSurface(null). 150 * The surface will not receive any more buffers while paused. 151 */ onPaused()152 public void onPaused() { } 153 154 /** 155 * Called when the virtual display video projection has been 156 * resumed after having been paused. 157 */ onResumed()158 public void onResumed() { } 159 160 /** 161 * Called when the virtual display video projection has been 162 * stopped by the system. It will no longer receive frames 163 * and it will never be resumed. It is still the responsibility 164 * of the application to release() the virtual display. 165 */ onStopped()166 public void onStopped() { } 167 } 168 } 169