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

## API Reference

> Source set: Common

```kotlin
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](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/PointLight/api.md), 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](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/PointLight/api.md), `elevation` is measured from the plane the surface rests on, so the light
is `elevation - thickness` above a surface with a thickness (see [SurfaceGeometrySpec](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceGeometrySpec/api.md)). 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](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/PointLight/api.md). 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](https://composables.com/jetpack-compose/androidx.compose.foundation/foundation/functions/position/api.md) to the point on the surface that the cone aims at. Together with [elevation](#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](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/Color/api.md). A light with an intensity of `0` contributes nothing. |

#### Throws: IllegalArgumentException

if [targetOffset](#targetoffset) is `DpOffset.Unspecified`, or if [elevation](#elevation) or [falloffRadius](#falloffradius) is `Dp.Unspecified`.

## Functions

### equals

> Source set: Common

```kotlin
override fun equals(other: Any?): Boolean
```

### hashCode

> Source set: Common

```kotlin
override fun hashCode(): Int
```

### toString

> Source set: Common

```kotlin
override fun toString(): String
```

### copy

> Source set: Common

```kotlin
override fun copy(position: LightPosition): Light
```

### packUniforms

> Source set: Common

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

```kotlin
public companion object
```

## Functions

### fromAngles

> Source set: Common

```kotlin
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](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SpotLight/api.md) 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](https://composables.com/jetpack-compose/androidx.compose.ui/ui-graphics/classes/Color/api.md). A light with an intensity of `0` contributes nothing. |

#### Throws: IllegalArgumentException

if `elevationDegrees` is not in `(0, 90]`, or if [elevation](#elevation) or [falloffRadius](#falloffradius) is `Dp.Unspecified`.

## Code Examples

### IlluminateWithSpotLightSample

```kotlin
@Sampled
@Composable
fun IlluminateWithSpotLightSample() {
    // 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),
            )
    )
}
```
