SpotLight


A light that sits in front of the surface like a PointLight, but emits only within a cone, so it lights a bounded pool of the surface rather than all of it.

The cone axis runs from the light to the point on the surface at targetOffset from position, and coneAngleDegrees opens the cone out around that axis. The cone edge is hard: a pixel is either inside the cone and fully lit or outside it and not lit at all, with no soft penumbra.

As with a PointLight, elevation is measured from the plane the surface rests on, so the light is elevation - thickness above a surface with a thickness (see SurfaceGeometrySpec). The point the cone aims at is on the surface. Brightness within the cone falls away with distance exactly as it does for a PointLight. The falloffRadius must be comfortably larger than elevation - thickness for the light to reach the surface.

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

Summary

Public companion functions

SpotLight
fromAngles(
    color: Color,
    position: LightPosition,
    planeAngleDegrees: Float,
    elevationDegrees: @FloatRange(from = 0.0, to = 90.0, fromInclusive = false) Float,
    elevation: Dp,
    falloffRadius: Dp,
    coneAngleDegrees: @FloatRange(from = 0.0, to = 180.0) Float,
    intensity: @FloatRange(from = 0.0) Float
)

Creates a SpotLight whose cone axis is given by angles instead of a targetOffset.

Cmn

Public constructors

SpotLight(
    color: Color,
    position: LightPosition,
    targetOffset: DpOffset,
    elevation: Dp,
    falloffRadius: Dp,
    coneAngleDegrees: @FloatRange(from = 0.0, to = 180.0) Float,
    intensity: @FloatRange(from = 0.0) Float
)
Cmn

Public functions

open operator Boolean
equals(other: Any?)
Cmn
open Int
Cmn
open String
Cmn

Public properties

open Color

color emitted by this light.

Cmn
@FloatRange(from = 0.0, to = 180.0) Float

half angle of the cone, in degrees.

Cmn
Dp

distance of the light in front of the plane the surface rests on, towards the viewer.

Cmn
Dp

distance at which the light has fully faded out.

Cmn
open @FloatRange(from = 0.0) Float

multiplier applied to color.

Cmn
open LightPosition

where the light sits in the plane of the surface.

Cmn
DpOffset

the in-plane offset from position to the point on the surface that the cone aims at.

Cmn

Public companion functions

fromAngles

fun fromAngles(
    color: Color,
    position: LightPosition,
    planeAngleDegrees: Float,
    elevationDegrees: @FloatRange(from = 0.0, to = 90.0, fromInclusive = false) Float,
    elevation: Dp,
    falloffRadius: Dp,
    coneAngleDegrees: @FloatRange(from = 0.0, to = 180.0) Float,
    intensity: @FloatRange(from = 0.0) Float
): SpotLight

Creates a SpotLight whose cone axis is given by angles instead of a targetOffset.

The angles decide where the light aims at from its position. They are measured as if the surface had no thickness, so on a thicker surface the light arrives slightly lower than elevationDegrees.

Parameters
color: Color

color emitted by this light.

position: LightPosition

where the light sits in the plane of the surface.

planeAngleDegrees: Float

where the light comes from within the plane of the surface, as seen from the point it aims at, in degrees clockwise from the right: 0 is from the right, 90 from below, 180 from the left and 270 from top.

elevationDegrees: @FloatRange(from = 0.0, to = 90.0, fromInclusive = false) Float

angle between the cone axis and the surface, in degrees: 90 aims at the point directly beneath the light, and smaller values tilt the cone further across the surface. Must be in (0, 90], as an axis level with the surface or behind it never reaches the surface.

elevation: Dp

distance of the light in front of the plane the surface rests on, towards the viewer. The light's height above the surface itself is elevation - thickness.

falloffRadius: Dp

distance at which the light has fully faded out. A radius of zero or less disables falloff entirely.

coneAngleDegrees: @FloatRange(from = 0.0, to = 180.0) Float

half angle of the cone, in degrees. This is measured from the axis to the cone edge, so the full width of the cone is twice this value. Pixels outside the cone are not lit.

intensity: @FloatRange(from = 0.0) Float

multiplier applied to color. A light with an intensity of 0 contributes nothing.

Public constructors

SpotLight

SpotLight(
    color: Color,
    position: LightPosition,
    targetOffset: DpOffset,
    elevation: Dp,
    falloffRadius: Dp,
    coneAngleDegrees: @FloatRange(from = 0.0, to = 180.0) Float,
    intensity: @FloatRange(from = 0.0) Float
)
Parameters
color: Color

color emitted by this light.

position: LightPosition

where the light sits in the plane of the surface.

targetOffset: DpOffset

the in-plane offset from position to the point on the surface that the cone aims at. Together with elevation this defines the cone axis, which points from the light onto the surface. DpOffset.Zero aims at the point directly beneath the light, so the cone meets the surface head on.

elevation: Dp

distance of the light in front of the plane the surface rests on, towards the viewer. The light's height above the surface itself is elevation - thickness.

falloffRadius: Dp

distance at which the light has fully faded out. A radius of zero or less disables falloff entirely.

coneAngleDegrees: @FloatRange(from = 0.0, to = 180.0) Float

half angle of the cone, in degrees. This is measured from the axis to the cone edge, so the full width of the cone is twice this value. Pixels outside the cone are not lit.

intensity: @FloatRange(from = 0.0) Float

multiplier applied to color. A light with an intensity of 0 contributes nothing.

Public functions

equals

open operator fun equals(other: Any?): Boolean

hashCode

open fun hashCode(): Int

toString

open fun toString(): String

Public properties

color

open val color: Color

color emitted by this light.

coneAngleDegrees

val coneAngleDegrees: @FloatRange(from = 0.0, to = 180.0) Float

half angle of the cone, in degrees. This is measured from the axis to the cone edge, so the full width of the cone is twice this value. Pixels outside the cone are not lit.

elevation

val elevation: Dp

distance of the light in front of the plane the surface rests on, towards the viewer. The light's height above the surface itself is elevation - thickness.

falloffRadius

val falloffRadius: Dp

distance at which the light has fully faded out. A radius of zero or less disables falloff entirely.

intensity

open val intensity: @FloatRange(from = 0.0) Float

multiplier applied to color. A light with an intensity of 0 contributes nothing.

position

open val position: LightPosition

where the light sits in the plane of the surface.

targetOffset

val targetOffset: DpOffset

the in-plane offset from position to the point on the surface that the cone aims at. Together with elevation this defines the cone axis, which points from the light onto the surface. DpOffset.Zero aims at the point directly beneath the light, so the cone meets the surface head on.