illuminate

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

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.

Modifier.illuminate

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.

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,
                ),
        )
)
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),
        )
)
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.