# illuminate

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

## API Reference

### illuminate

> Source set: Common

```kotlin
public fun Modifier.illuminate(
    lights: List<Light>,
    surfaceMaterial: SurfaceMaterial,
    surfaceGeometrySpec: SurfaceGeometrySpec,
    blendMode: BlendMode = BlendMode.SrcOver,
): Modifier
```

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

The content is drawn first. On top of it this modifier draws the light that a surface shaped like
`surfaceGeometrySpec`, made of `surfaceMaterial`, would reflect from `lights`.

Every light is evaluated independently and their contributions are summed, then clamped. The part
of the surface where the normals face away from the light, will not be lit by that particular
light.

Check compatibility with `IlluminationScope.isSupported`. Unsupported platforms will draw the
content unchanged.

#### Parameters

| | |
| --- | --- |
| lights | the lights illuminating the surface. At most `IlluminationScope.MaxLightsAllowed` lights are supported. Lights positioned with [LightPosition.Anchored](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/LightPosition.Anchored/api.md) contribute nothing until their anchor has been placed. |
| surfaceMaterial | how the surface reflects light. `SurfaceMaterial.None` reflects nothing, so at least one component must be set for this modifier to draw anything. |
| surfaceGeometrySpec | the virtual three-dimensional shape the surface is treated as having. |
| blendMode | how the lighting pass is composited over the content. The default is `BlendMode.SrcOver`. Note that you might need a different blendMode to maintain legibility since `BlendMode.SrcOver` can occlude the underlying content. |

#### Throws: IllegalArgumentException

if more than `IlluminationScope.MaxLightsAllowed` lights are supplied, or if the shape backing [surfaceGeometrySpec](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceGeometrySpec/api.md) is not one that lighting supports.

### illuminate

> Source set: Common

```kotlin
public fun Modifier.illuminate(
    blendMode: BlendMode = BlendMode.SrcOver,
    block: IlluminationScope.() -> Unit,
): Modifier
```

Draws a lighting pass over the content, shading it as though it were a physical surface, with the
lighting configured in `block`.

The content is drawn first. On top of it this modifier draws the light that a surface shaped like
`IlluminationScope.surfaceGeometrySpec`, made of `IlluminationScope.surfaceMaterial`, would
reflect from `IlluminationScope.lights`.

Check compatibility with `IlluminationScope.isSupported`. Unsupported platforms will draw the
content unchanged.

Prefer this overload when the lighting is backed by a `androidx.compose.runtime.State` or an
animated value, such as a moving light, as reading a state inside `block` only redraws the
surface without triggering recomposition and relayout.

`block` runs every time the surface is drawn, starting from a [IlluminationScope](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/IlluminationScope/api.md) with every
property at its default. It should therefore set every property it relies on, and do as little
other work as possible.

#### Parameters

| | |
| --- | --- |
| blendMode | how the lighting pass is composited over the content. The default is `BlendMode.SrcOver`. Note that you might need a different blendMode to maintain legibility since `BlendMode.SrcOver` can occlude the underlying content. |
| block | configures the light, material and geometry of the surface. |

#### Throws: IllegalArgumentException

if more than `IlluminationScope.MaxLightsAllowed` lights are supplied, or if the shape backing [IlluminationScope.surfaceGeometrySpec](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/IlluminationScope/api.md) is not one that lighting supports.

## 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,
                    ),
            )
    )
}
```
