AndroidExternalSurface

@Composable
fun AndroidExternalSurface(
    modifier: Modifier = Modifier,
    isOpaque: Boolean = true,
    surfaceSize: IntSize = IntSize.Zero,
    zOrder: AndroidExternalSurfaceZOrder = AndroidExternalSurfaceZOrder.Behind,
    isSecure: Boolean = false,
    onInit: AndroidExternalSurfaceScope.() -> Unit
): Unit

Provides a dedicated drawing Surface as a separate layer positioned by default behind the window holding the AndroidExternalSurface composable. Because AndroidExternalSurface uses a separate window layer, graphics composition is handled by the system compositor which can bypass the GPU and provide better performance and power usage characteristics compared to AndroidEmbeddedExternalSurface. It is therefore recommended to use AndroidExternalSurface over AndroidEmbeddedExternalSurface whenever possible.

The Surface provided can be used to present content that's external to Compose, such as a video stream (from a camera or a media player), OpenGL, Vulkan...The provided Surface can be rendered into using a thread different from the main thread.

The z-ordering of the surface can be controlled using the zOrder parameter:

• AndroidExternalSurfaceZOrder.Behind: positions the surface behind the window

• AndroidExternalSurfaceZOrder.MediaOverlay: positions the surface behind the window but above other AndroidExternalSurfaceZOrder.Behind surfaces

• AndroidExternalSurfaceZOrder.OnTop: positions the surface above the window

The drawing surface is opaque by default, which can be controlled with the isOpaque parameter. When the surface is transparent, you may need to change the z-order to see something behind the surface.

To start rendering, the caller must first acquire the Surface when it's created. This is achieved by providing the onInit lambda, which allows the caller to register an appropriate AndroidExternalSurfaceScope.onSurface callback. The onInit lambda can also be used to initialize/cache resources needed once a surface is available.

After acquiring a surface, the caller can start rendering into it. Rendering into a surface can be done from any thread.

It is recommended to register the SurfaceScope.onChanged and SurfaceScope.onDestroyed callbacks to properly handle the lifecycle of the surface and react to dimension changes. You must ensure that the rendering thread stops interacting with the surface when the SurfaceScope.onDestroyed callback is invoked.

If a surfaceSize is specified (set to non-IntSize.Zero), the surface will use the specified size instead of the layout size of this composable. The surface will be stretched at render time to fit the layout size. This can be used for instance to render at a lower resolution for performance reasons.

import androidx.compose.foundation.AndroidExternalSurface
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.height
import androidx.compose.runtime.withFrameNanos
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.lerp
import androidx.compose.ui.graphics.toArgb
import androidx.compose.ui.unit.dp

AndroidExternalSurface(modifier = Modifier.fillMaxWidth().height(400.dp)) {
    // Resources can be initialized/cached here

    // A surface is available, we can start rendering
    onSurface { surface, width, height ->
        var w = width
        var h = height

        // Initial draw to avoid a black frame
        surface.lockCanvas(Rect(0, 0, w, h)).apply {
            drawColor(Color.Blue.toArgb())
            surface.unlockCanvasAndPost(this)
        }

        // React to surface dimension changes
        surface.onChanged { newWidth, newHeight ->
            w = newWidth
            h = newHeight
        }

        // Cleanup if needed
        surface.onDestroyed {}

        // Render loop, automatically cancelled on surface destruction
        while (true) {
            withFrameNanos { time ->
                surface.lockCanvas(Rect(0, 0, w, h)).apply {
                    val timeMs = time / 1_000_000L
                    val t = 0.5f + 0.5f * sin(timeMs / 1_000.0f)
                    drawColor(lerp(Color.Blue, Color.Green, t).toArgb())
                    surface.unlockCanvasAndPost(this)
                }
            }
        }
    }
}