Added in API level 1

SurfaceView


open class SurfaceView : View
kotlin.Any
   ↳ android.view.View
   ↳ android.view.SurfaceView

Provides a dedicated drawing surface embedded inside of a view hierarchy. You can control the format of this surface and, if you like, its size; the SurfaceView takes care of placing the surface at the correct location on the screen

The surface is Z ordered so that it is behind the window holding its SurfaceView; the SurfaceView punches a hole in its window to allow its surface to be displayed. The view hierarchy will take care of correctly compositing with the Surface any siblings of the SurfaceView that would normally appear on top of it. This can be used to place overlays such as buttons on top of the Surface, though note however that it can have an impact on performance since a full alpha-blended composite will be performed each time the Surface changes.

The transparent region that makes the surface visible is based on the layout positions in the view hierarchy. If the post-layout transform properties are used to draw a sibling view on top of the SurfaceView, the view may not be properly composited with the surface.

Access to the underlying surface is provided via the SurfaceHolder interface, which can be retrieved by calling getHolder.

The Surface will be created for you while the SurfaceView's window is visible; you should implement SurfaceHolder.Callback#surfaceCreated and SurfaceHolder.Callback#surfaceDestroyed to discover when the Surface is created and destroyed as the window is shown and hidden.

One of the purposes of this class is to provide a surface in which a secondary thread can render into the screen. If you are going to use it this way, you need to be aware of some threading semantics:

Note: Starting in platform version android.os.Build.VERSION_CODES#N, SurfaceView's window position is updated synchronously with other View rendering. This means that translating and scaling a SurfaceView on screen will not cause rendering artifacts. Such artifacts may occur on previous versions of the platform when its window is positioned asynchronously.

Note: Starting in platform version android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE, SurfaceView will support arbitrary alpha blending. Prior platform versions ignored alpha values on the SurfaceView if they were between 0 and 1. If the SurfaceView is configured with Z-above, then the alpha is applied directly to the Surface. If the SurfaceView is configured with Z-below, then the alpha is applied to the hole punch directly. Note that when using Z-below, overlapping SurfaceViews may not blend properly as a consequence of not applying alpha to the surface content directly.

Summary

Inherited XML attributes
Constants
static Int

Default lifecycle of the Surface owned by this SurfaceView.

static Int

The Surface lifecycle is tied to SurfaceView attachment.

static Int

The Surface lifecycle is tied to SurfaceView visibility.

Inherited constants
Public constructors
SurfaceView(context: Context!)

SurfaceView(context: Context!, attrs: AttributeSet!)

SurfaceView(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

SurfaceView(context: Context!, attrs: AttributeSet!, defStyleAttr: Int, defStyleRes: Int)

Public methods
open Unit

Adds a transaction that would be applied synchronously with displaying the SurfaceView's next frame.

open Unit
draw(canvas: Canvas)

open Boolean

open SurfaceHolder!

Return the SurfaceHolder providing access and control over this SurfaceView's underlying surface.

open IBinder?

A token used for constructing SurfaceControlViewHost.

open Int

open SurfaceControl!

Return a SurfaceControl which can be used for parenting Surfaces to this SurfaceView.

open Boolean

open Unit
setAlpha(alpha: Float)

open Unit

Display the view-hierarchy embedded within a SurfaceControlViewHost.SurfacePackage within this SurfaceView.

open Unit
setClipBounds(clipBounds: Rect!)

open Unit
setDesiredHdrHeadroom(desiredHeadroom: Float)

Sets the desired amount of HDR headroom to be used when HDR content is presented on this SurfaceView.

open Unit
setSecure(isSecure: Boolean)

Control whether the surface view's content should be treated as secure, preventing it from appearing in screenshots or from being viewed on non-secure displays.

open Unit
setSurfaceLifecycle(lifecycleStrategy: Int)

Controls the lifecycle of the Surface owned by this SurfaceView.

open Unit
setVisibility(visibility: Int)

open Unit
setZOrderMediaOverlay(isMediaOverlay: Boolean)

Control whether the surface view's surface is placed on top of another regular surface view in the window (but still behind the window itself).

open Unit

Control whether the surface view's surface is placed on top of its window.

Protected methods
open Unit

open Unit

open Unit

open Unit
onFocusChanged(gainFocus: Boolean, direction: Int, previouslyFocusedRect: Rect?)

Called by the view system when the focus state of this view changes.

open Unit
onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int)

open Boolean
onSetAlpha(alpha: Int)

open Unit

Inherited functions
Inherited properties

Constants

SURFACE_LIFECYCLE_DEFAULT

Added in API level 34
static val SURFACE_LIFECYCLE_DEFAULT: Int

Default lifecycle of the Surface owned by this SurfaceView. The default lifecycle matches SURFACE_LIFECYCLE_FOLLOWS_VISIBILITY.

Value: 0

SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT

Added in API level 34
static val SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT: Int

The Surface lifecycle is tied to SurfaceView attachment. The Surface is created when the SurfaceView first becomes attached, but is not destroyed until this SurfaceView has been detached from the current window.

Value: 2

SURFACE_LIFECYCLE_FOLLOWS_VISIBILITY

Added in API level 34
static val SURFACE_LIFECYCLE_FOLLOWS_VISIBILITY: Int

The Surface lifecycle is tied to SurfaceView visibility. The Surface is created when the SurfaceView becomes visible, and is destroyed when the SurfaceView is no longer visible.

Value: 1

Public constructors

SurfaceView

Added in API level 1
SurfaceView(context: Context!)

SurfaceView

Added in API level 1
SurfaceView(
    context: Context!,
    attrs: AttributeSet!)

SurfaceView

Added in API level 1
SurfaceView(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int)

SurfaceView

Added in API level 21
SurfaceView(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int,
    defStyleRes: Int)

Public methods

applyTransactionToFrame

Added in API level 34
open fun applyTransactionToFrame(transaction: SurfaceControl.Transaction): Unit

Adds a transaction that would be applied synchronously with displaying the SurfaceView's next frame. Note that the exact frame that the transaction is applied with is only well-defined when SurfaceView rendering is paused prior to calling applyTransactionToFrame(), so that the transaction is applied with the next frame rendered after applyTransactionToFrame() is called. If frames are continuously rendering to the SurfaceView when applyTransactionToFrame() is called, then it is undefined which frame the transaction is applied with. It is also possible for the transaction to not be applied if no new frames are rendered to the SurfaceView after this is called.

Parameters
transaction SurfaceControl.Transaction: The transaction to apply. The system takes ownership of the transaction and promises to eventually apply the transaction. This value cannot be null.
Exceptions
java.lang.IllegalStateException if the underlying Surface does not exist (and therefore there is no next frame).

draw

Added in API level 1
open fun draw(canvas: Canvas): Unit
Parameters
canvas Canvas: The Canvas to which the View is rendered. This value cannot be null.

gatherTransparentRegion

Added in API level 1
open fun gatherTransparentRegion(region: Region?): Boolean
Parameters
region Region?: The transparent region for this ViewAncestor (window). This value may be null.
Return
Boolean Returns true if the effective visibility of the view at this point is opaque, regardless of the transparent region; returns false if it is possible for underlying windows to be seen behind the view.

getHolder

Added in API level 1
open fun getHolder(): SurfaceHolder!

Return the SurfaceHolder providing access and control over this SurfaceView's underlying surface.

Return
SurfaceHolder! SurfaceHolder The holder of the surface.

getHostToken

Added in API level 30
Deprecated in API level 35
open fun getHostToken(): IBinder?

Deprecated: Use AttachedSurfaceControl#getInputTransferToken() instead.

A token used for constructing SurfaceControlViewHost. This token should be passed from the host process to the client process.

Return
IBinder? The token This value may be null.

getImportantForAccessibility

Added in API level 16
open fun getImportantForAccessibility(): Int
Return
Int The mode for determining whether a view is important for accessibility, one of IMPORTANT_FOR_ACCESSIBILITY_AUTO, IMPORTANT_FOR_ACCESSIBILITY_YES, IMPORTANT_FOR_ACCESSIBILITY_NO, or IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS.

getSurfaceControl

Added in API level 29
open fun getSurfaceControl(): SurfaceControl!

Return a SurfaceControl which can be used for parenting Surfaces to this SurfaceView. Note that this SurfaceControl is effectively read-only. Its only well-defined usage is in using the SurfaceControl as a parent for an application's hierarchy of SurfaceControls. All other properties of the SurfaceControl, such as its position, may be mutated by the SurfaceView at any time which will override what the application is requesting. Do not apply any SurfaceControl.Transaction to this SurfaceControl except for reparenting child SurfaceControls. See: SurfaceControl.Transaction#reparent.

Return
SurfaceControl! The SurfaceControl for this SurfaceView.

hasOverlappingRendering

Added in API level 16
open fun hasOverlappingRendering(): Boolean
Return
Boolean true if the content in this view might overlap, false otherwise.

setAlpha

Added in API level 11
open fun setAlpha(alpha: Float): Unit
Parameters
alpha Float: The opacity of the view. Value is between 0.0 and 1.0 inclusive

setChildSurfacePackage

Added in API level 30
open fun setChildSurfacePackage(p: SurfaceControlViewHost.SurfacePackage): Unit

Display the view-hierarchy embedded within a SurfaceControlViewHost.SurfacePackage within this SurfaceView. This can be called independently of the SurfaceView lifetime callbacks. SurfaceView will internally manage reparenting the package to our Surface as it is created and destroyed. If this SurfaceView is above its host Surface (see setZOrderOnTop then the embedded Surface hierarchy will be able to receive input. This will take ownership of the SurfaceControl contained inside the SurfacePackage and free the caller of the obligation to call SurfaceControlViewHost.SurfacePackage#release. However, note that SurfaceControlViewHost.SurfacePackage#release and SurfaceControlViewHost#release are not the same. While the ownership of this particular SurfaceControlViewHost.SurfacePackage will be taken by the SurfaceView the underlying SurfaceControlViewHost remains managed by it's original remote-owner.

Parameters
p SurfaceControlViewHost.SurfacePackage: The SurfacePackage to embed. This value cannot be null.

setClipBounds

Added in API level 18
open fun setClipBounds(clipBounds: Rect!): Unit
Parameters
clipBounds Rect!: The rectangular area, in the local coordinates of this view, to which future drawing operations will be clipped.

setDesiredHdrHeadroom

Added in API level 35
open fun setDesiredHdrHeadroom(desiredHeadroom: Float): Unit

Sets the desired amount of HDR headroom to be used when HDR content is presented on this SurfaceView.

By default the system will choose an amount of HDR headroom that is appropriate for the underlying device capabilities & bit-depth of the panel. However, for some types of content this can end up being more headroom than necessary or desired. An example would be a messaging app or gallery thumbnail view where some amount of HDR pop is desired without overly influencing the perceived brightness of the majority SDR content. This can also be used to animate in/out of an HDR range for smoother transitions.

Note: The actual amount of HDR headroom that will be given is subject to a variety of factors such as ambient conditions, display capabilities, or bit-depth limitations. See Display#getHdrSdrRatio() for more information as well as how to query the current value.

Parameters
desiredHeadroom Float: The amount of HDR headroom that is desired. Must be >= 1.0 (no HDR) and <= 10,000.0. Passing 0.0 will reset to the default, automatically chosen value. Value is between 0.0f and 10000.0 inclusive

setSecure

Added in API level 17
open fun setSecure(isSecure: Boolean): Unit

Control whether the surface view's content should be treated as secure, preventing it from appearing in screenshots or from being viewed on non-secure displays.

Note that this must be set before the surface view's containing window is attached to the window manager.

See android.view.Display#FLAG_SECURE for details.

Parameters
isSecure Boolean: True if the surface view is secure.

setSurfaceLifecycle

Added in API level 34
open fun setSurfaceLifecycle(lifecycleStrategy: Int): Unit

Controls the lifecycle of the Surface owned by this SurfaceView.

By default, the lifecycycle strategy employed by the SurfaceView is SURFACE_LIFECYCLE_DEFAULT.

Parameters
lifecycleStrategy Int: The strategy for the lifecycle of the Surface owned by this SurfaceView. Value is android.view.SurfaceView#SURFACE_LIFECYCLE_DEFAULT, android.view.SurfaceView#SURFACE_LIFECYCLE_FOLLOWS_VISIBILITY, or android.view.SurfaceView#SURFACE_LIFECYCLE_FOLLOWS_ATTACHMENT

setVisibility

Added in API level 1
open fun setVisibility(visibility: Int): Unit
Parameters
visibility Int: One of VISIBLE, INVISIBLE, or GONE. Value is android.view.View#VISIBLE, android.view.View#INVISIBLE, or android.view.View#GONE

setZOrderMediaOverlay

Added in API level 5
open fun setZOrderMediaOverlay(isMediaOverlay: Boolean): Unit

Control whether the surface view's surface is placed on top of another regular surface view in the window (but still behind the window itself). This is typically used to place overlays on top of an underlying media surface view.

Note that this must be set before the surface view's containing window is attached to the window manager.

Calling this overrides any previous call to setZOrderOnTop.

setZOrderOnTop

Added in API level 5
open fun setZOrderOnTop(onTop: Boolean): Unit

Control whether the surface view's surface is placed on top of its window. Normally it is placed behind the window, to allow it to (for the most part) appear to composite with the views in the hierarchy. By setting this, you cause it to be placed above the window. This means that none of the contents of the window this SurfaceView is in will be visible on top of its surface.

Note that this must be set before the surface view's containing window is attached to the window manager. If you target Build.VERSION_CODES#R the Z ordering can be changed dynamically if the backing surface is created, otherwise it would be applied at surface construction time.

Calling this overrides any previous call to setZOrderMediaOverlay.

Parameters
onTop Boolean: Whether to show the surface on top of this view's window.

Protected methods

dispatchDraw

Added in API level 1
protected open fun dispatchDraw(canvas: Canvas): Unit
Parameters
canvas Canvas: the canvas on which to draw the view This value cannot be null.

onAttachedToWindow

Added in API level 1
protected open fun onAttachedToWindow(): Unit

onDetachedFromWindow

Added in API level 1
protected open fun onDetachedFromWindow(): Unit

onFocusChanged

Added in API level 1
protected open fun onFocusChanged(
    gainFocus: Boolean,
    direction: Int,
    previouslyFocusedRect: Rect?
): Unit

Called by the view system when the focus state of this view changes. When the focus change event is caused by directional navigation, direction and previouslyFocusedRect provide insight into where the focus is coming from. When overriding, be sure to call up through to the super class so that the standard focus handling will occur.
If you override this method you must call through to the superclass implementation.

Parameters
gainFocus Boolean: True if the View has focus; false otherwise.
direction Int: Value is android.view.View#FOCUS_BACKWARD, android.view.View#FOCUS_FORWARD, android.view.View#FOCUS_LEFT, android.view.View#FOCUS_UP, android.view.View#FOCUS_RIGHT, or android.view.View#FOCUS_DOWN
previouslyFocusedRect Rect?: This value may be null.

onMeasure

Added in API level 1
protected open fun onMeasure(
    widthMeasureSpec: Int,
    heightMeasureSpec: Int
): Unit
Parameters
widthMeasureSpec Int: horizontal space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.
heightMeasureSpec Int: vertical space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.

onSetAlpha

Added in API level 1
protected open fun onSetAlpha(alpha: Int): Boolean
Parameters
alpha Int: The alpha (0..255) to apply to the view's drawing
Return
Boolean true if the view can draw with the specified alpha.

onWindowVisibilityChanged

Added in API level 1
protected open fun onWindowVisibilityChanged(visibility: Int): Unit
Parameters
visibility Int: The new visibility of the window. Value is android.view.View#VISIBLE, android.view.View#INVISIBLE, or android.view.View#GONE