FileDocCategorySizeDatePackage
SurfaceControl.javaAPI DocAndroid 5.1 API29024Thu Mar 12 22:22:10 GMT 2015android.view

SurfaceControl

public class SurfaceControl extends Object
SurfaceControl
hide

Fields Summary
private static final String
TAG
private final dalvik.system.CloseGuard
mCloseGuard
private final String
mName
long
mNativeObject
public static final int
HIDDEN
Surface creation flag: Surface is created hidden
public static final int
SECURE
Surface creation flag: The surface contains secure content, special measures will be taken to disallow the surface's content to be copied from another process. In particular, screenshots and VNC servers will be disabled, but other measures can take place, for instance the surface might not be hardware accelerated.
public static final int
NON_PREMULTIPLIED
Surface creation flag: Creates a surface where color components are interpreted as "non pre-multiplied" by their alpha channel. Of course this flag is meaningless for surfaces without an alpha channel. By default surfaces are pre-multiplied, which means that each color component is already multiplied by its alpha value. In this case the blending equation used is:

DEST = SRC + DEST * (1-SRC_ALPHA)

By contrast, non pre-multiplied surfaces use the following equation:

DEST = SRC * SRC_ALPHA * DEST * (1-SRC_ALPHA)

pre-multiplied surfaces must always be used if transparent pixels are composited on top of each-other into the surface. A pre-multiplied surface can never lower the value of the alpha component of a given pixel.

In some rare situations, a non pre-multiplied surface is preferable.

public static final int
OPAQUE
Surface creation flag: Indicates that the surface must be considered opaque, even if its pixel format is set to translucent. This can be useful if an application needs full RGBA 8888 support for instance but will still draw every pixel opaque.

This flag is ignored if setAlpha() is used to make the surface non-opaque. Combined effects are (assuming a buffer format with an alpha channel):

  • OPAQUE + alpha(1.0) == opaque composition
  • OPAQUE + alpha(0.x) == blended composition
  • !OPAQUE + alpha(1.0) == blended composition
  • !OPAQUE + alpha(0.x) == blended composition
If the underlying buffer lacks an alpha channel, the OPAQUE flag is effectively set automatically.
public static final int
PROTECTED_APP
Surface creation flag: Application requires a hardware-protected path to an external display sink. If a hardware-protected path is not available, then this surface will not be displayed on the external sink.
public static final int
CURSOR_WINDOW
Surface creation flag: Window represents a cursor glyph.
public static final int
FX_SURFACE_NORMAL
Surface creation flag: Creates a normal surface. This is the default.
public static final int
FX_SURFACE_DIM
Surface creation flag: Creates a Dim surface. Everything behind this surface is dimmed by the amount specified in {@link #setAlpha}. It is an error to lock a Dim surface, since it doesn't have a backing store.
public static final int
FX_SURFACE_MASK
Mask used for FX values above.
private static final int
SURFACE_HIDDEN
Surface flag: Hide the surface. Equivalent to calling hide(). Updates the value set during Surface creation (see {@link #HIDDEN}).
private static final int
SURFACE_OPAQUE
Surface flag: composite without blending when possible. Updates the value set during Surface creation (see {@link #OPAQUE}).
public static final int
BUILT_IN_DISPLAY_ID_MAIN
Built-in physical display id: Main display. Use only with {@link SurfaceControl#getBuiltInDisplay(int)}.
public static final int
BUILT_IN_DISPLAY_ID_HDMI
Built-in physical display id: Attached HDMI display. Use only with {@link SurfaceControl#getBuiltInDisplay(int)}.
public static final int
POWER_MODE_OFF
public static final int
POWER_MODE_DOZE
Display power mode doze: used while putting the screen into low power mode. Use only with {@link SurfaceControl#setDisplayPowerMode}.
public static final int
POWER_MODE_NORMAL
Display power mode normal: used while unblanking the screen. Use only with {@link SurfaceControl#setDisplayPowerMode}.
public static final int
POWER_MODE_DOZE_SUSPEND
Display power mode doze: used while putting the screen into a suspended low power mode. Use only with {@link SurfaceControl#setDisplayPowerMode}.
Constructors Summary
public SurfaceControl(SurfaceSession session, String name, int w, int h, int format, int flags)
Create a surface with a name.

The surface creation flags specify what kind of surface to create and certain options such as whether the surface can be assumed to be opaque and whether it should be initially hidden. Surfaces should always be created with the {@link #HIDDEN} flag set to ensure that they are not made visible prematurely before all of the surface's properties have been configured.

Good practice is to first create the surface with the {@link #HIDDEN} flag specified, open a transaction, set the surface layer, layer stack, alpha, and position, call {@link #show} if appropriate, and close the transaction.

param
session The surface session, must not be null.
param
name The surface name, must not be null.
param
w The surface initial width.
param
h The surface initial height.
param
flags The surface creation flags. Should always include {@link #HIDDEN} in the creation flags.
throws
throws OutOfResourcesException If the SurfaceControl cannot be created.


                                                                                                                                                                         
      
                     
                      
        if (session == null) {
            throw new IllegalArgumentException("session must not be null");
        }
        if (name == null) {
            throw new IllegalArgumentException("name must not be null");
        }

        if ((flags & SurfaceControl.HIDDEN) == 0) {
            Log.w(TAG, "Surfaces should always be created with the HIDDEN flag set "
                    + "to ensure that they are not made visible prematurely before "
                    + "all of the surface's properties have been configured.  "
                    + "Set the other properties and make the surface visible within "
                    + "a transaction.  New surface name: " + name,
                    new Throwable());
        }

        mName = name;
        mNativeObject = nativeCreate(session, name, w, h, format, flags);
        if (mNativeObject == 0) {
            throw new OutOfResourcesException(
                    "Couldn't allocate SurfaceControl native object");
        }

        mCloseGuard.open("release");
Methods Summary
private voidcheckNotReleased()

        if (mNativeObject == 0) throw new NullPointerException(
                "mNativeObject is null. Have you called release() already?");
public static booleanclearAnimationFrameStats()

        return nativeClearAnimationFrameStats();
public booleanclearContentFrameStats()

        checkNotReleased();
        return nativeClearContentFrameStats(mNativeObject);
public static voidcloseTransaction()
end a transaction

        nativeCloseTransaction();
public static android.os.IBindercreateDisplay(java.lang.String name, boolean secure)

        if (name == null) {
            throw new IllegalArgumentException("name must not be null");
        }
        return nativeCreateDisplay(name, secure);
public voiddestroy()
Free all server-side state associated with this surface and release this object's reference. This method can only be called from the process that created the service.

        if (mNativeObject != 0) {
            nativeDestroy(mNativeObject);
            mNativeObject = 0;
        }
        mCloseGuard.close();
public static voiddestroyDisplay(android.os.IBinder displayToken)

        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        nativeDestroyDisplay(displayToken);
protected voidfinalize()

        try {
            if (mCloseGuard != null) {
                mCloseGuard.warnIfOpen();
            }
            if (mNativeObject != 0) {
                nativeRelease(mNativeObject);
            }
        } finally {
            super.finalize();
        }
public static intgetActiveConfig(android.os.IBinder displayToken)

        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        return nativeGetActiveConfig(displayToken);
public static booleangetAnimationFrameStats(WindowAnimationFrameStats outStats)

        return nativeGetAnimationFrameStats(outStats);
public static android.os.IBindergetBuiltInDisplay(int builtInDisplayId)

        return nativeGetBuiltInDisplay(builtInDisplayId);
public booleangetContentFrameStats(WindowContentFrameStats outStats)

        checkNotReleased();
        return nativeGetContentFrameStats(mNativeObject, outStats);
public static android.view.SurfaceControl$PhysicalDisplayInfo[]getDisplayConfigs(android.os.IBinder displayToken)

        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        return nativeGetDisplayConfigs(displayToken);
public voidhide()

        checkNotReleased();
        nativeSetFlags(mNativeObject, SURFACE_HIDDEN, SURFACE_HIDDEN);
private static native booleannativeClearAnimationFrameStats()

private static native booleannativeClearContentFrameStats(long nativeObject)
private static native voidnativeCloseTransaction()
private static native longnativeCreate(SurfaceSession session, java.lang.String name, int w, int h, int format, int flags)
private static native android.os.IBindernativeCreateDisplay(java.lang.String name, boolean secure)
private static native voidnativeDestroy(long nativeObject)
private static native voidnativeDestroyDisplay(android.os.IBinder displayToken)
private static native intnativeGetActiveConfig(android.os.IBinder displayToken)
private static native booleannativeGetAnimationFrameStats(WindowAnimationFrameStats outStats)
private static native android.os.IBindernativeGetBuiltInDisplay(int physicalDisplayId)
private static native booleannativeGetContentFrameStats(long nativeObject, WindowContentFrameStats outStats)
private static native android.view.SurfaceControl$PhysicalDisplayInfo[]nativeGetDisplayConfigs(android.os.IBinder displayToken)
private static native voidnativeOpenTransaction()
private static native voidnativeRelease(long nativeObject)
private static native android.graphics.BitmapnativeScreenshot(android.os.IBinder displayToken, android.graphics.Rect sourceCrop, int width, int height, int minLayer, int maxLayer, boolean allLayers, boolean useIdentityTransform, int rotation)
private static native voidnativeScreenshot(android.os.IBinder displayToken, Surface consumer, android.graphics.Rect sourceCrop, int width, int height, int minLayer, int maxLayer, boolean allLayers, boolean useIdentityTransform)
private static native booleannativeSetActiveConfig(android.os.IBinder displayToken, int id)
private static native voidnativeSetAlpha(long nativeObject, float alpha)
private static native voidnativeSetAnimationTransaction()
private static native voidnativeSetDisplayLayerStack(android.os.IBinder displayToken, int layerStack)
private static native voidnativeSetDisplayPowerMode(android.os.IBinder displayToken, int mode)
private static native voidnativeSetDisplayProjection(android.os.IBinder displayToken, int orientation, int l, int t, int r, int b, int L, int T, int R, int B)
private static native voidnativeSetDisplaySize(android.os.IBinder displayToken, int width, int height)
private static native voidnativeSetDisplaySurface(android.os.IBinder displayToken, long nativeSurfaceObject)
private static native voidnativeSetFlags(long nativeObject, int flags, int mask)
private static native voidnativeSetLayer(long nativeObject, int zorder)
private static native voidnativeSetLayerStack(long nativeObject, int layerStack)
private static native voidnativeSetMatrix(long nativeObject, float dsdx, float dtdx, float dsdy, float dtdy)
private static native voidnativeSetPosition(long nativeObject, float x, float y)
private static native voidnativeSetSize(long nativeObject, int w, int h)
private static native voidnativeSetTransparentRegionHint(long nativeObject, android.graphics.Region region)
private static native voidnativeSetWindowCrop(long nativeObject, int l, int t, int r, int b)
public static voidopenTransaction()
start a transaction
        nativeOpenTransaction();
    
public voidrelease()
Release the local reference to the server-side surface.
Always call release() when you're done with a Surface.
This will make the surface invalid.
        if (mNativeObject != 0) {
            nativeRelease(mNativeObject);
            mNativeObject = 0;
        }
        mCloseGuard.close();
    
public static voidscreenshot(android.os.IBinder display, Surface consumer, int width, int height, int minLayer, int maxLayer, boolean useIdentityTransform)
Copy the current screen contents into the provided {@link Surface}
param
display The display to take the screenshot of.
param
consumer The {@link Surface} to take the screenshot into.
param
width The desired width of the returned bitmap; the raw
screen will be scaled down to this size.
param
height The desired height of the returned bitmap; the raw
screen will be scaled down to this size.
param
minLayer The lowest (bottom-most Z order) surface layer to
include in the screenshot.
param
maxLayer The highest (top-most Z order) surface layer to
include in the screenshot.
param
useIdentityTransform Replace whatever transformation (rotation,
scaling, translation) the surface layers are currently using with the
identity transformation while taking the screenshot.
        screenshot(display, consumer, new Rect(), width, height, minLayer, maxLayer,
                false, useIdentityTransform);
    
public static voidscreenshot(android.os.IBinder display, Surface consumer, int width, int height)
Copy the current screen contents into the provided {@link Surface}
param
display The display to take the screenshot of.
param
consumer The {@link Surface} to take the screenshot into.
param
width The desired width of the returned bitmap; the raw
screen will be scaled down to this size.
param
height The desired height of the returned bitmap; the raw
screen will be scaled down to this size.
        screenshot(display, consumer, new Rect(), width, height, 0, 0, true, false);
    
public static voidscreenshot(android.os.IBinder display, Surface consumer)
Copy the current screen contents into the provided {@link Surface}
param
display The display to take the screenshot of.
param
consumer The {@link Surface} to take the screenshot into.
        screenshot(display, consumer, new Rect(), 0, 0, 0, 0, true, false);
    
public static android.graphics.Bitmapscreenshot(android.graphics.Rect sourceCrop, int width, int height, int minLayer, int maxLayer, boolean useIdentityTransform, int rotation)
Copy the current screen contents into a bitmap and return it.

CAVEAT: Versions of screenshot that return a {@link Bitmap} can
be extremely slow; avoid use unless absolutely necessary; prefer
the versions that use a {@link Surface} instead, such as
{@link SurfaceControl#screenshot(IBinder, Surface)}.
param
sourceCrop The portion of the screen to capture into the Bitmap;
caller may pass in 'new Rect()' if no cropping is desired.
param
width The desired width of the returned bitmap; the raw
screen will be scaled down to this size.
param
height The desired height of the returned bitmap; the raw
screen will be scaled down to this size.
param
minLayer The lowest (bottom-most Z order) surface layer to
include in the screenshot.
param
maxLayer The highest (top-most Z order) surface layer to
include in the screenshot.
param
useIdentityTransform Replace whatever transformation (rotation,
scaling, translation) the surface layers are currently using with the
identity transformation while taking the screenshot.
param
rotation Apply a custom clockwise rotation to the screenshot, i.e.
Surface.ROTATION_0,90,180,270. Surfaceflinger will always take
screenshots in its native portrait orientation by default, so this is
useful for returning screenshots that are independent of device
orientation.
return
Returns a Bitmap containing the screen contents, or null
if an error occurs. Make sure to call Bitmap.recycle() as soon as
possible, once its content is not needed anymore.
        // TODO: should take the display as a parameter
        IBinder displayToken = SurfaceControl.getBuiltInDisplay(
                SurfaceControl.BUILT_IN_DISPLAY_ID_MAIN);
        return nativeScreenshot(displayToken, sourceCrop, width, height,
                minLayer, maxLayer, false, useIdentityTransform, rotation);
    
public static android.graphics.Bitmapscreenshot(int width, int height)
Like {@link SurfaceControl#screenshot(int, int, int, int, boolean)} but
includes all Surfaces in the screenshot.
param
width The desired width of the returned bitmap; the raw
screen will be scaled down to this size.
param
height The desired height of the returned bitmap; the raw
screen will be scaled down to this size.
return
Returns a Bitmap containing the screen contents, or null
if an error occurs. Make sure to call Bitmap.recycle() as soon as
possible, once its content is not needed anymore.
        // TODO: should take the display as a parameter
        IBinder displayToken = SurfaceControl.getBuiltInDisplay(
                SurfaceControl.BUILT_IN_DISPLAY_ID_MAIN);
        return nativeScreenshot(displayToken, new Rect(), width, height, 0, 0, true,
                false, Surface.ROTATION_0);
    
private static voidscreenshot(android.os.IBinder display, Surface consumer, android.graphics.Rect sourceCrop, int width, int height, int minLayer, int maxLayer, boolean allLayers, boolean useIdentityTransform)
        if (display == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        if (consumer == null) {
            throw new IllegalArgumentException("consumer must not be null");
        }
        nativeScreenshot(display, consumer, sourceCrop, width, height,
                minLayer, maxLayer, allLayers, useIdentityTransform);
    
public static booleansetActiveConfig(android.os.IBinder displayToken, int id)
        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        return nativeSetActiveConfig(displayToken, id);
    
public voidsetAlpha(float alpha)
Sets an alpha value for the entire Surface. This value is combined with the
per-pixel alpha. It may be used with opaque Surfaces.
        checkNotReleased();
        nativeSetAlpha(mNativeObject, alpha);
    
public static voidsetAnimationTransaction()
flag the transaction as an animation
        nativeSetAnimationTransaction();
    
public static voidsetDisplayLayerStack(android.os.IBinder displayToken, int layerStack)
        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        nativeSetDisplayLayerStack(displayToken, layerStack);
    
public static voidsetDisplayPowerMode(android.os.IBinder displayToken, int mode)
        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        nativeSetDisplayPowerMode(displayToken, mode);
    
public static voidsetDisplayProjection(android.os.IBinder displayToken, int orientation, android.graphics.Rect layerStackRect, android.graphics.Rect displayRect)
        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        if (layerStackRect == null) {
            throw new IllegalArgumentException("layerStackRect must not be null");
        }
        if (displayRect == null) {
            throw new IllegalArgumentException("displayRect must not be null");
        }
        nativeSetDisplayProjection(displayToken, orientation,
                layerStackRect.left, layerStackRect.top, layerStackRect.right, layerStackRect.bottom,
                displayRect.left, displayRect.top, displayRect.right, displayRect.bottom);
    
public static voidsetDisplaySize(android.os.IBinder displayToken, int width, int height)
        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }
        if (width <= 0 || height <= 0) {
            throw new IllegalArgumentException("width and height must be positive");
        }

        nativeSetDisplaySize(displayToken, width, height);
    
public static voidsetDisplaySurface(android.os.IBinder displayToken, Surface surface)
        if (displayToken == null) {
            throw new IllegalArgumentException("displayToken must not be null");
        }

        if (surface != null) {
            synchronized (surface.mLock) {
                nativeSetDisplaySurface(displayToken, surface.mNativeObject);
            }
        } else {
            nativeSetDisplaySurface(displayToken, 0);
        }
    
public voidsetLayer(int zorder)
        checkNotReleased();
        nativeSetLayer(mNativeObject, zorder);
    
public voidsetLayerStack(int layerStack)
        checkNotReleased();
        nativeSetLayerStack(mNativeObject, layerStack);
    
public voidsetMatrix(float dsdx, float dtdx, float dsdy, float dtdy)
        checkNotReleased();
        nativeSetMatrix(mNativeObject, dsdx, dtdx, dsdy, dtdy);
    
public voidsetOpaque(boolean isOpaque)
Sets the opacity of the surface. Setting the flag is equivalent to creating the
Surface with the {@link #OPAQUE} flag.
        checkNotReleased();
        if (isOpaque) {
            nativeSetFlags(mNativeObject, SURFACE_OPAQUE, SURFACE_OPAQUE);
        } else {
            nativeSetFlags(mNativeObject, 0, SURFACE_OPAQUE);
        }
    
public voidsetPosition(float x, float y)
        checkNotReleased();
        nativeSetPosition(mNativeObject, x, y);
    
public voidsetSize(int w, int h)
        checkNotReleased();
        nativeSetSize(mNativeObject, w, h);
    
public voidsetTransparentRegionHint(android.graphics.Region region)
        checkNotReleased();
        nativeSetTransparentRegionHint(mNativeObject, region);
    
public voidsetWindowCrop(android.graphics.Rect crop)
        checkNotReleased();
        if (crop != null) {
            nativeSetWindowCrop(mNativeObject,
                crop.left, crop.top, crop.right, crop.bottom);
        } else {
            nativeSetWindowCrop(mNativeObject, 0, 0, 0, 0);
        }
    
public voidshow()
        checkNotReleased();
        nativeSetFlags(mNativeObject, 0, SURFACE_HIDDEN);
    
public java.lang.StringtoString()
        return "Surface(name=" + mName + ")";