# illuminate

> Draws a lighting pass over the content, shading it as though it were a physical surface.

## Code Examples

### IlluminateSample

```kotlin
@Sampled
@Composable
fun IlluminateSample() {
    // Since our light color is white, we set a darker background so that its visible.
    val backgroundColor = remember { Color.Black }
    val surfaceShape = remember { RoundedCornerShape(24.dp) }
    Box(
        Modifier.size(160.dp)
            .background(backgroundColor)
            .illuminate(
                lights =
                    listOf(
                        PointLight(
                            color = Color.White,
                            // Above the top-left corner of the lit composable.
                            position = LightPosition.Local(DpOffset(x = 0.dp, y = 0.dp)),
                            elevation = 48.dp,
                            falloffRadius = 320.dp,
                            intensity = 1f,
                        )
                    ),
                surfaceMaterial =
                    SurfaceMaterial.diffuse(Color.White).specular(Color.White, shininess = 32f),
                surfaceGeometrySpec =
                    SurfaceGeometrySpec.convex(
                        shape = surfaceShape,
                        thickness = 1.dp,
                        bevelWidth = 12.dp,
                    ),
            )
    )
}
```

### IlluminateWithSpotLightSample

```kotlin
@Sampled
@Composable
fun IlluminateWithSpotLightSample() {
    // Since our light color is white, we set a darker background so that its visible.
    val surfaceColor = remember { Color.Black }
    val surfaceShape = remember { RoundedCornerShape(24.dp) }
    val lightPosition = remember { DpOffset(x = 20.dp, y = 20.dp) }
    Box(
        Modifier.size(160.dp)
            .background(surfaceColor)
            .illuminate(
                lights =
                    listOf(
                        SpotLight(
                            color = Color.White,
                            position = LightPosition.Local(lightPosition),
                            // Aim at the middle of the 160.dp surface, the offset from the light
                            // to the point the cone should land on.
                            targetOffset = DpOffset(x = 160.dp / 2, y = 160.dp / 2) - lightPosition,
                            elevation = 60.dp,
                            falloffRadius = 200.dp,
                            coneAngleDegrees = 30f,
                            intensity = 1f,
                        )
                    ),
                surfaceMaterial =
                    SurfaceMaterial.diffuse(Color.White)
                        .specular(Color.White, shininess = 48f)
                        .fresnel(reflectivity = 0.04f),
                surfaceGeometrySpec =
                    SurfaceGeometrySpec.flat(shape = surfaceShape, thickness = 1.dp),
            )
    )
}
```

### IlluminateWithDirectionalLightSample

```kotlin
@Sampled
@Composable
fun IlluminateWithDirectionalLightSample() {
    // Since our light color is white, we set a darker background so that its visible.
    val surfaceColor = remember { Color.Black }
    val surfaceShape = remember { RoundedCornerShape(24.dp) }
    Box(
        Modifier.size(160.dp)
            .background(surfaceColor)
            .illuminate(
                lights =
                    listOf(
                        DirectionalLight(
                            color = Color.White,
                            // Points towards the light: above and to the left of the surface.
                            directionX = -1f,
                            directionY = -1f,
                            intensity = 1f,
                            directionZ = 1f,
                        )
                    ),
                surfaceMaterial = SurfaceMaterial.diffuse(Color.White),
                surfaceGeometrySpec =
                    SurfaceGeometrySpec.convex(
                        shape = surfaceShape,
                        thickness = 1.dp,
                        bevelWidth = 12.dp,
                    ),
            )
    )
}
```
