DirectionalLight


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.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
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.DirectionalLight
import androidx.compose.ui.lighting.SurfaceGeometrySpec
import androidx.compose.ui.lighting.SurfaceMaterial
import androidx.compose.ui.lighting.illuminate
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) }
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,
                ),
        )
)

Summary

Public companion functions

DirectionalLight
fromAngles(
    color: Color,
    planeAngleDegrees: Float,
    elevationDegrees: Float,
    intensity: @FloatRange(from = 0.0) Float
)

Creates a DirectionalLight from angles instead of a direction vector.

Cmn

Public constructors

DirectionalLight(
    color: Color,
    directionX: Float,
    directionY: Float,
    directionZ: Float,
    intensity: @FloatRange(from = 0.0) Float
)
Cmn

Public functions

open operator Boolean
equals(other: Any?)
Cmn
open Int
Cmn
open String
Cmn

Public properties

open Color

color emitted by this light.

Cmn
Float

the x component of the vector pointing towards the light.

Cmn
Float

the y component of the vector pointing towards the light.

Cmn
Float

the z component of the vector pointing towards the light.

Cmn
open @FloatRange(from = 0.0) Float

multiplier applied to color.

Cmn

Inherited properties

From androidx.compose.ui.lighting.Light
open LightPosition

Where the light sits.

Cmn

Public companion functions

fromAngles

fun fromAngles(
    color: Color,
    planeAngleDegrees: Float,
    elevationDegrees: Float,
    intensity: @FloatRange(from = 0.0) Float
): DirectionalLight

Creates a DirectionalLight from angles instead of a direction vector.

Parameters
color: Color

color emitted by this light.

planeAngleDegrees: Float

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: Float

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: @FloatRange(from = 0.0) Float

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

Public constructors

DirectionalLight

DirectionalLight(
    color: Color,
    directionX: Float,
    directionY: Float,
    directionZ: Float,
    intensity: @FloatRange(from = 0.0) Float
)
Parameters
color: Color

color emitted by this light.

directionX: Float

the x component of the vector pointing towards the light. Positive values are to the right.

directionY: Float

the y component of the vector pointing towards the light. Positive values are downwards.

directionZ: Float

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.

intensity: @FloatRange(from = 0.0) Float

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

Public functions

equals

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

hashCode

open fun hashCode(): Int

toString

open fun toString(): String

Public properties

color

open val color: Color

color emitted by this light.

directionX

val directionX: Float

the x component of the vector pointing towards the light. Positive values are to the right.

directionY

val directionY: Float

the y component of the vector pointing towards the light. Positive values are downwards.

directionZ

val directionZ: Float

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.

intensity

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

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