illuminate
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 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 is not one that lighting supports.
illuminate
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 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 is not one that lighting supports.