# PointLight

> A light that radiates equally in every direction from a single point in front of the surface, like a bare bulb.

## API Reference

> Source set: Common

```kotlin
public class PointLight(
    override val color: Color,
    override val position: LightPosition,
    public val elevation: Dp,
    public val falloffRadius: Dp,
    @FloatRange(from = 0.0) override val intensity: Float,
) : Light()
```

A light that radiates equally in every direction from a single point in front of the surface,
like a bare bulb.

`elevation` is measured from the plane the surface rests on. A surface with a thickness (see
[SurfaceGeometrySpec](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/SurfaceGeometrySpec/api.md)) rises towards the light, so the light's height above it is `elevation -
thickness`. Keep `elevation` larger than the thickness so the light stays in front of the
surface.

Brightness falls away with distance and reaches zero at `falloffRadius`. The distance is measured
in three dimensions, so it includes the light's height above the surface: a light raised
`falloffRadius` or more above the surface cannot reach it at all, and lights nothing. Keep
`falloffRadius` comfortably larger than `elevation - thickness`.

#### Parameters

| | |
| --- | --- |
| color | color emitted by this light. |
| position | where the light sits in the plane of 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, so the light reaches the whole surface at full strength. |
| 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 [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,
    )
```

## Code Examples

### IlluminateSample

```kotlin
@Sampled
@Composable
fun IlluminateSample() {
    // Since our light color is white, we set a darker background so that its visible.
    val backgroundColor = remember { Color.Black }
    val surfaceShape = remember { RoundedCornerShape(24.dp) }
    Box(
        Modifier.size(160.dp)
            .background(backgroundColor)
            .illuminate(
                lights =
                    listOf(
                        PointLight(
                            color = Color.White,
                            // Above the top-left corner of the lit composable.
                            position = LightPosition.Local(DpOffset(x = 0.dp, y = 0.dp)),
                            elevation = 48.dp,
                            falloffRadius = 320.dp,
                            intensity = 1f,
                        )
                    ),
                surfaceMaterial =
                    SurfaceMaterial.diffuse(Color.White).specular(Color.White, shininess = 32f),
                surfaceGeometrySpec =
                    SurfaceGeometrySpec.convex(
                        shape = surfaceShape,
                        thickness = 1.dp,
                        bevelWidth = 12.dp,
                    ),
            )
    )
}
```
