Contents

DirectionalLightComponent

A component that defines a directional light source.

Declaration

struct DirectionalLightComponent

Mentioned in

Overview

A directional light shines in the entity’s forward direction [0, 0, -1].

Change the a directional light’s direction with the Entity/orientation or look(at:from:upVector:relativeTo:) method of the Entity with a DirectionalLightComponent. The position of the entity does not play a part in the directional light’s effect.

Use this component with shadows by adding DirectionalLightComponent and DirectionalLightComponent.Shadow to an entity’s components set. In this example, the light’s color is red, and the intensity is 10_000, which is an approximate lux for ambient daylight:

let lightEntity = Entity()

let redLightComponent = DirectionalLightComponent(
    color: .red, intensity: 10_000
)
let lightShadowComponent = DirectionalLightComponent.Shadow()
lightEntity.components.set([redLightComponent, lightShadowComponent])

The directional light illuminates entities evenly in the direction it derives from the orientation of lightEntity. Here is a visual example of how the above code snippet could illuminates entities in a scene:

Without a directional light

With a directional light

[Image]

[Image]

Dynamic light capacity

On older hardware, only a limited number of dynamic lights can affect each object. Devices that support MTLGPUFamily.apple6 or later lift this limit.

Excessive use of dynamic lights may contribute to user-noticeable frame drops and can cause the device to heat up in graphically demanding situations. Monitor the thermal state and reduce the number of lights as a mitigation, if necessary.

Because this behavior varies by device, verify your scene’s lighting on the oldest hardware you support. You can check for this support at runtime with MTLDevice.supportsFamily(.apple6).

Topics

Creating a directional light

Setting the color

Setting intensity and shadows

Supporting types

Assigning render layers

Structures

Initializers

Instance Properties

See Also

Directional lights and their shadows