Home | History | Annotate | Download | only in display 
      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 
     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