# SurfaceScope

Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/AndroidExternalSurface.android.kt+class:androidx.compose.foundation.SurfaceScope) Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.6.0) Common/AllAndroid/JVM
- android

  ```
  interface SurfaceScope
  ```
Known direct subclasses [SurfaceCoroutineScope](https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceCoroutineScope)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceCoroutineScope` | `https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceCoroutineScope` is a scoped environment provided by `https://developer.android.com/reference/kotlin/androidx/compose/foundation/AndroidExternalSurface.composable#AndroidExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.foundation.AndroidExternalSurfaceZOrder,kotlin.Boolean,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/AndroidEmbeddedExternalSurface.composable#AndroidEmbeddedExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.ui.graphics.Matrix,kotlin.Function1)` when a new `https://developer.android.com/reference/android/view/Surface.html` is created. |

*** ** * ** ***

`https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope` is a scoped environment provided by `https://developer.android.com/reference/kotlin/androidx/compose/foundation/AndroidExternalSurface.composable#AndroidExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.foundation.AndroidExternalSurfaceZOrder,kotlin.Boolean,kotlin.Function1)` and `https://developer.android.com/reference/kotlin/androidx/compose/foundation/AndroidEmbeddedExternalSurface.composable#AndroidEmbeddedExternalSurface(androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.unit.IntSize,androidx.compose.ui.graphics.Matrix,kotlin.Function1)` to handle `https://developer.android.com/reference/android/view/Surface.html` lifecycle events.

```kotlin
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)
                }
            }
        }
    }
}
```

## Summary

| ### Public functions |
|---|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/android/view/Surface.html.https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope#(android.view.Surface).onChanged(kotlin.Function3)(onChanged: https://developer.android.com/reference/android/view/Surface.html.(width: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html, height: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Invokes `https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope#(android.view.Surface).onChanged(kotlin.Function3)` when the surface's geometry (width and height) changes. | android |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/android/view/Surface.html.https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope#(android.view.Surface).onDestroyed(kotlin.Function1)(onDestroyed: https://developer.android.com/reference/android/view/Surface.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Invokes `https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope#(android.view.Surface).onDestroyed(kotlin.Function1)` when the surface is destroyed. | android |

## Public functions

### Surface.onChanged

android Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/AndroidExternalSurface.android.kt+function:onChanged) Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.6.0)

```
fun Surface.onChanged(onChanged: Surface.(width: Int, height: Int) -> Unit): Unit
```

Invokes `https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope#(android.view.Surface).onChanged(kotlin.Function3)` when the surface's geometry (width and height) changes. Always invoked on the main thread.

### Surface.onDestroyed

android Artifact: [androidx.compose.foundation:foundation](https://developer.android.com/jetpack/androidx/releases/compose-foundation) [View Source](https://cs.android.com/search?q=file:androidx/compose/foundation/AndroidExternalSurface.android.kt+function:onDestroyed) Added in [1.6.0](https://developer.android.com/jetpack/androidx/releases/compose-foundation#1.6.0)

```
fun Surface.onDestroyed(onDestroyed: Surface.() -> Unit): Unit
```

Invokes `https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope#(android.view.Surface).onDestroyed(kotlin.Function1)` when the surface is destroyed. All rendering into the surface should stop immediately after `https://developer.android.com/reference/kotlin/androidx/compose/foundation/SurfaceScope#(android.view.Surface).onDestroyed(kotlin.Function1)` is invoked. Always invoked on the main thread.