# DirectionalLight

> A light that is infinitely far away, such as the sun.

## API Reference

> Source set: Common

```kotlin
public class DirectionalLight(
    override val color: Color,
    public val directionX: Float,
    public val directionY: Float,
    public val directionZ: Float,
    @FloatRange(from = 0.0) override val intensity: Float,
) : Light()
```

A light that is infinitely far away, such as the sun.

The light is described by the vector `(directionX, directionY, directionZ)`, which points from
the lit surface *towards* the light. It says where the light is coming from rather than where it
is shining. Only the ratio between the three components matters, as the vector is normalized
before use.

`directionZ` is normally positive, which places the light in front of the surface on the viewer's
side. A light level with or behind the surface leaves it unlit.

#### Parameters

| | |
| --- | --- |
| color | color emitted by this light. |
| 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. |
| directionX | the `x` component of the vector pointing towards the light. Positive values are to the right. |
| directionY | the `y` component of the vector pointing towards the light. Positive values are downwards. |
| directionZ | the `z` component of the vector pointing towards the light. Positive values are towards the viewer. Larger values light the surface more evenly, as the light moves towards being head on. |

## 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,
            planeAngleDegrees: Float,
            elevationDegrees: Float,
            @FloatRange(from = 0.0) intensity: Float,
        ): DirectionalLight
```

Creates a [DirectionalLight](https://composables.com/jetpack-compose/androidx.compose.ui/ui/classes/DirectionalLight/api.md) from angles instead of a direction vector.

#### Parameters

| | |
| --- | --- |
| color | color emitted by this light. |
| planeAngleDegrees | where the light comes from within the plane of the surface, in degrees clockwise from the right: `0` is from the right, `90` from below, `180` from the left and `270` from above. |
| elevationDegrees | how far the light is raised above the surface, in degrees: `90` shines head on from the viewer, and `0` is level with the surface, which leaves it unlit. |
| 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. |

## Code Examples

### IlluminateWithDirectionalLightSample

```kotlin
@Sampled
@Composable
fun IlluminateWithDirectionalLightSample() {
    // 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) }
    Box(
        Modifier.size(160.dp)
            .background(surfaceColor)
            .illuminate(
                lights =
                    listOf(
                        DirectionalLight(
                            color = Color.White,
                            // Points towards the light: above and to the left of the surface.
                            directionX = -1f,
                            directionY = -1f,
                            intensity = 1f,
                            directionZ = 1f,
                        )
                    ),
                surfaceMaterial = SurfaceMaterial.diffuse(Color.White),
                surfaceGeometrySpec =
                    SurfaceGeometrySpec.convex(
                        shape = surfaceShape,
                        thickness = 1.dp,
                        bevelWidth = 12.dp,
                    ),
            )
    )
}
```
