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.os.IBinder;
     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;
     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