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

# SpotLight

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/Light.kt+class:androidx.compose.ui.lighting.SpotLight) Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01) Common/All
- Cmn

  ```
  class SpotLight : Light
  ```

|---|---|---|
| [kotlin.Any](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html) |||
| ↳ | [androidx.compose.ui.lighting.Light](https://developer.android.com/reference/kotlin/androidx/compose/ui/lighting/Light.md.txt) ||
|   | ↳ | [androidx.compose.ui.lighting.SpotLight](https://developer.android.com/reference/kotlin/androidx/compose/ui/lighting/SpotLight.md.txt) |

*** ** * ** ***

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.

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

| Throws |
|---|---|
| `IllegalArgumentException` | if `targetOffset` is `DpOffset.Unspecified`, or if `elevation` or `falloffRadius` is `Dp.Unspecified`. |

## 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` | `hashCode()` | Cmn |
| `open String` | `toString()` | Cmn |

| ### Public properties |
|---|---|---|
| `open Color` | `color` color emitted by this light. | Cmn |
| `@FloatRange(from = 0.0, to = 180.0) Float` | `coneAngleDegrees` half angle of the cone, in degrees. | Cmn |
| `Dp` | `elevation` distance of the light in front of the plane the surface rests on, towards the viewer. | Cmn |
| `Dp` | `falloffRadius` distance at which the light has fully faded out. | Cmn |
| `open @FloatRange(from = 0.0) Float` | `intensity` multiplier applied to `color`. | Cmn |
| `open LightPosition` | `position` where the light sits in the plane of the surface. | Cmn |
| `DpOffset` | `targetOffset` the in-plane offset from `position` to the point on the surface that the cone aims at. | Cmn |

## Public companion functions

### fromAngles

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

| Throws |
|---|---|
| `IllegalArgumentException` | if `elevationDegrees` is not in `(0, 90]`, or if `elevation` or `falloffRadius` is `Dp.Unspecified`. |

## Public constructors

### SpotLight

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn

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

### hashCode

Cmn

```
open fun hashCode(): Int
```

### toString

Cmn

```
open fun toString(): String
```

## Public properties

### color

Cmn

```
open val color: Color
```

color emitted by this light.

### coneAngleDegrees

Cmn Added in [1.14.0-alpha01](https://developer.android.com/jetpack/androidx/releases/compose-ui.md.txt#1.14.0-alpha01)

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

Cmn

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

Cmn

```
val falloffRadius: Dp
```

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

### intensity

Cmn

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

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

### position

Cmn

```
open val position: LightPosition
```

where the light sits in the plane of the surface.

### targetOffset

Cmn

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