> Documentation index: https://developer.android.com/reference/llms.txt

# illuminate

Common/All

## Functions summary

|---|---|---|
| `Modifier` | `Modifier.illuminate(blendMode: BlendMode, block: IlluminationScope.() -> Unit)` Draws a lighting pass over the content, shading it as though it were a physical surface, with the lighting configured in `block`. | Cmn |
| `Modifier` | `Modifier.illuminate( lights: List<Light>, surfaceMaterial: SurfaceMaterial, surfaceGeometrySpec: SurfaceGeometrySpec, blendMode: BlendMode )` Draws a lighting pass over the content, shading it as though it were a physical surface. | Cmn |

## Functions

### Modifier.illuminate

Cmn Artifact: [androidx.compose.ui:ui](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/lighting/IlluminationModifier.kt+function:illuminate)

```
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` 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: BlendMode = BlendMode.SrcOver` | 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: IlluminationScope.() -> Unit` | 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` is not one that lighting supports. |

| See also |
|---|---|
| `IlluminationScope` |   |
| `lightAnchor` |   |

### Modifier.illuminate

Cmn Artifact: [androidx.compose.ui:ui](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt) [View Source](https://cs.android.com/search?q=file:androidx/compose/ui/lighting/IlluminationModifier.kt+function:illuminate) Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

```
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.

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.lighting.LightPosition
import androidx.compose.ui.lighting.PointLight
import androidx.compose.ui.lighting.SurfaceGeometrySpec
import androidx.compose.ui.lighting.SurfaceMaterial
import androidx.compose.ui.lighting.illuminate
import androidx.compose.ui.unit.DpOffset
import androidx.compose.ui.unit.dp

// 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,
                ),
        )
)
```

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.offset
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.lighting.LightPosition
import androidx.compose.ui.lighting.SpotLight
import androidx.compose.ui.lighting.SurfaceGeometrySpec
import androidx.compose.ui.lighting.SurfaceMaterial
import androidx.compose.ui.lighting.illuminate
import androidx.compose.ui.unit.DpOffset
import androidx.compose.ui.unit.dp

// 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),
        )
)
```

```kotlin
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.lighting.DirectionalLight
import androidx.compose.ui.lighting.SurfaceGeometrySpec
import androidx.compose.ui.lighting.SurfaceMaterial
import androidx.compose.ui.lighting.illuminate
import androidx.compose.ui.unit.dp

// 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,
                ),
        )
)
```

| Parameters |
|---|---|
| `lights: List<Light>` | the lights illuminating the surface. At most `IlluminationScope.MaxLightsAllowed` lights are supported. Lights positioned with `LightPosition.Anchored` contribute nothing until their anchor has been placed. |
| `surfaceMaterial: 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: SurfaceGeometrySpec` | the virtual three-dimensional shape the surface is treated as having. |
| `blendMode: BlendMode = BlendMode.SrcOver` | 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` is not one that lighting supports. |

| See also |
|---|---|
| `lightAnchor` |   |
| `SurfaceGeometrySpec` |   |
| `SurfaceMaterial` |   |