SurfaceControlCompat
@RequiresApi(value = 29)
class SurfaceControlCompat
Handle to an on-screen Surface managed by the system compositor. SurfaceControlCompat is a combination of a buffer source, and metadata about how to display the buffers. By constructing a Surface from this SurfaceControl you can submit buffers to be composited. Using SurfaceControlCompat.Transaction you can manipulate various properties of how the buffer will be displayed on-screen. SurfaceControlCompats are arranged into a scene-graph like hierarchy, and as such any SurfaceControlCompat may have a parent. Geometric properties like transform, crop, and Z-ordering will be inherited from the parent, as if the child were content in the parents buffer stream.
This class differs slightly than SurfaceControl in that it backports some functionality to Android R and above by delegating to the related APIs available in the NDK. For newer Android versions, this leverages the equivalent SurfaceControl API available in the SDK
Summary
Nested types |
|---|
|
Builder class for |
@RequiresApi(value = 29)An atomic set of changes to a set of |
|
Interface to handle request to |
Constants |
|
|---|---|
const Int |
The identity transformation. |
const Int |
Mirrors the buffer horizontally. |
const Int |
Mirrors the buffer vertically. |
const Int |
Rotates the buffer 180 degrees clockwise. |
const Int |
Rotates the buffer 270 degrees clockwise. |
const Int |
Rotates the buffer 90 degrees clockwise. |
const Int |
Change the frame rate even if the transition is going to be non-seamless, i.e. with visual interruptions for the user. |
const Int |
Change the frame rate only if the transition is going to be seamless. |
const Int |
There are no inherent restrictions on the frame rate. |
const Int |
This compositing layer is being used to display content with an inherently fixed frame rate, e.g. a video that has a specific frame rate. |
Public functions |
|
|---|---|
Boolean |
isValid()Check whether this instance points to a valid layer with the system-compositor. |
Unit |
release()Release the local reference to the server-side surface. |
Constants
BUFFER_TRANSFORM_IDENTITY
const val BUFFER_TRANSFORM_IDENTITY = 0: Int
The identity transformation. Maps a coordinate (x, y) onto itself.
BUFFER_TRANSFORM_MIRROR_HORIZONTAL
const val BUFFER_TRANSFORM_MIRROR_HORIZONTAL = 1: Int
Mirrors the buffer horizontally. Maps a point (x, y) to (-x, y)
BUFFER_TRANSFORM_MIRROR_VERTICAL
const val BUFFER_TRANSFORM_MIRROR_VERTICAL = 2: Int
Mirrors the buffer vertically. Maps a point (x, y) to (x, -y)
BUFFER_TRANSFORM_ROTATE_180
const val BUFFER_TRANSFORM_ROTATE_180 = 3: Int
Rotates the buffer 180 degrees clockwise. Maps a point (x, y) to (-x, -y)
BUFFER_TRANSFORM_ROTATE_270
const val BUFFER_TRANSFORM_ROTATE_270 = 7: Int
Rotates the buffer 270 degrees clockwise. Maps a point (x, y) to (y, -x)
BUFFER_TRANSFORM_ROTATE_90
const val BUFFER_TRANSFORM_ROTATE_90 = 4: Int
Rotates the buffer 90 degrees clockwise. Maps a point (x, y) to (-y, x)
CHANGE_FRAME_RATE_ALWAYS
const val CHANGE_FRAME_RATE_ALWAYS = 1: Int
Change the frame rate even if the transition is going to be non-seamless, i.e. with visual interruptions for the user.
CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS
const val CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS = 0: Int
Change the frame rate only if the transition is going to be seamless.
FRAME_RATE_COMPATIBILITY_DEFAULT
const val FRAME_RATE_COMPATIBILITY_DEFAULT = 0: Int
There are no inherent restrictions on the frame rate. When the system selects a frame rate other than what the app requested, the app will be able to run at the system frame rate without requiring pull down (the mechanical process of "pulling", physically moving, frame content downward to advance it from one frame to the next at a repetitive rate). This value should be used when displaying game content, UIs, and anything that isn't video.
FRAME_RATE_COMPATIBILITY_FIXED_SOURCE
const val FRAME_RATE_COMPATIBILITY_FIXED_SOURCE = 1: Int
This compositing layer is being used to display content with an inherently fixed frame rate, e.g. a video that has a specific frame rate. When the system selects a frame rate other than what the app requested, the app will need to do pull down or use some other technique to adapt to the system's frame rate. Pull down involves the mechanical process of "pulling", physically moving, frame content downward to advance it from one frame to the next at a repetitive rate). The user experience is likely to be worse (e.g. more frame stuttering) than it would be if the system had chosen the app's requested frame rate. This value should be used for video content.
Public functions
isValid
fun isValid(): Boolean
Check whether this instance points to a valid layer with the system-compositor. For example this may be false if the layer was released (release).
release
fun release(): Unit
Release the local reference to the server-side surface. The Surface may continue to exist on-screen as long as its parent continues to exist. To explicitly remove a Surface from the screen use Transaction.reparent with a null-parent. After release, isValid will return false and other methods will throw an exception. Always call release when you are done with a SurfaceControlCompat instance.