Class

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.

Source set: Common
public class SpotLight(
    override val color: Color,
    override val position: LightPosition,
    public val targetOffset: DpOffset,
    public val elevation: Dp,
    public val falloffRadius: Dp,
    @FloatRange(from = 0.0, to = 180.0) public val coneAngleDegrees: Float,
    @FloatRange(from = 0.0) override val intensity: Float,
) : Light()

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.

Parameters

color color emitted by this light.
position where the light sits in the plane of the surface.
targetOffset 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 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 distance at which the light has fully faded out. A radius of zero or less disables falloff entirely.
coneAngleDegrees 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 multiplier applied to color. A light with an intensity of 0 contributes nothing.

Throws: IllegalArgumentException

if targetOffset is DpOffset.Unspecified, or if elevation or falloffRadius is Dp.Unspecified.

Functions

equals

Source set: Common
override fun equals(other: Any?): Boolean

hashCode

Source set: Common
override fun hashCode(): Int

toString

Source set: Common
override fun toString(): String

copy

Source set: Common
override fun copy(position: LightPosition): Light

packUniforms

Source set: Common
override fun Density.packUniforms(
        index: Int,
        lightTypes: IntArray,
        lightColors: FloatArray,
        lightPositions: FloatArray,
        lightDirections: FloatArray,
        lightFalloffRadii: FloatArray,
        lightCutoffCosines: FloatArray,
        lightIntensities: FloatArray,
    )

Members

Companion

Source set: Common
public companion object

Functions

fromAngles

Source set: Common
public fun fromAngles(
            color: Color,
            position: LightPosition,
            planeAngleDegrees: Float,
            @FloatRange(from = 0.0, to = 90.0, fromInclusive = false) elevationDegrees: Float,
            elevation: Dp,
            falloffRadius: Dp,
            @FloatRange(from = 0.0, to = 180.0) coneAngleDegrees: Float,
            @FloatRange(from = 0.0) intensity: 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 emitted by this light.
position where the light sits in the plane of the surface.
planeAngleDegrees 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 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 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 distance at which the light has fully faded out. A radius of zero or less disables falloff entirely.
coneAngleDegrees 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 multiplier applied to color. A light with an intensity of 0 contributes nothing.

Throws: IllegalArgumentException

if elevationDegrees is not in (0, 90], or if elevation or falloffRadius is Dp.Unspecified.

Jetpack Compose beyond MaterialFree components, screens and templates for apps that don’t look like Google’s. Copy them into your app, or let your coding agent add them.Browse for free

Content updated: