struct · iOS 13.0+ · SDK 27.1
struct DirectionalLightComponentA component that defines a directional light source. 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 ``HasTransform/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. - Tip: Turn on shadows for a directional light by adding the ``Shadow`` component to an entity that has a `DirectionalLightComponent`. Use this component with shadows by adding `DirectionalLightComponent` and ``Shadow`` to an entity's ``Entity/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: ```swift 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 | |:-:|:-:| |  |  | - Note: The green arrows in the above illustration are only a visual representation of the light's direction. ## 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)`.
get isRealWorldProxy(): booleanvar isRealWorldProxy: BoolA Boolean that you use to control whether the directional light operates as a proxy for a real-world light. Set the value to `true` when you want the light to cast shadows on virtual content without illuminating anything in the scene. You can use this to create shadows on occlusion materials that accept dynamic lighting.
set isRealWorldProxy(value: boolean)var isRealWorldProxy: BoolA Boolean that you use to control whether the directional light operates as a proxy for a real-world light. Set the value to `true` when you want the light to cast shadows on virtual content without illuminating anything in the scene. You can use this to create shadows on occlusion materials that accept dynamic lighting.
get layers(): RenderLayer_Setvar layers: RenderLayer.Set { get set }The layers this light illuminates. A directional light illuminates an entity when the layers of the entity's ``RenderLayerComponent`` intersect with this set. Entities without a ``RenderLayerComponent`` belong to ``RenderLayer/defaultLayer``, which is the only member of `layers` by default. Define your custom layers in an extension to ``RenderLayer`` and assign them to lights and entities to control which lights affect which entities: ```swift extension RenderLayer { static let hero = RenderLayer("com.myapp.hero") } var light = DirectionalLightComponent(color: .white, intensity: 10_000) light.layers = [.hero] ``` Lights can be restricted by layer on devices with Apple6 GPU family feature support.
set layers(value: RenderLayer_Set)var layers: RenderLayer.Set { get set }The layers this light illuminates. A directional light illuminates an entity when the layers of the entity's ``RenderLayerComponent`` intersect with this set. Entities without a ``RenderLayerComponent`` belong to ``RenderLayer/defaultLayer``, which is the only member of `layers` by default. Define your custom layers in an extension to ``RenderLayer`` and assign them to lights and entities to control which lights affect which entities: ```swift extension RenderLayer { static let hero = RenderLayer("com.myapp.hero") } var light = DirectionalLightComponent(color: .white, intensity: 10_000) light.layers = [.hero] ``` Lights can be restricted by layer on devices with Apple6 GPU family feature support.
get intensity(): numbervar intensity: FloatThe intensity of the directional light, measured in lumen per square meter. Lumen per square meter, also known as lux, measures how much light is spread over an area. It tells you how bright a surface appears based on the light it receives. The default value for this property is `2145.7078`. Use the following table as an estimate for Lux levels: | Environment | Typical Lux Level | |:-|:-| | Full moon | 0.1 - 1 lux | | Street lighting | 10 - 20 lux | | Living room lighting | 50 - 100 lux | | Classroom | 250 - 750 lux | | Office lighting | 300 - 500 lux | | Sunrise/Sunset on a clear day | 400 lux | | Overcast daylight | 1000 - 2000 lux | | Photography studio lighting | 1,000 - 2,000 lux | | Ambient daylight | 10,000 - 25,000 lux | | Direct sunlight | 32,000 - 100,000 lux |
set intensity(value: number)var intensity: FloatThe intensity of the directional light, measured in lumen per square meter. Lumen per square meter, also known as lux, measures how much light is spread over an area. It tells you how bright a surface appears based on the light it receives. The default value for this property is `2145.7078`. Use the following table as an estimate for Lux levels: | Environment | Typical Lux Level | |:-|:-| | Full moon | 0.1 - 1 lux | | Street lighting | 10 - 20 lux | | Living room lighting | 50 - 100 lux | | Classroom | 250 - 750 lux | | Office lighting | 300 - 500 lux | | Sunrise/Sunset on a clear day | 400 lux | | Overcast daylight | 1000 - 2000 lux | | Photography studio lighting | 1,000 - 2,000 lux | | Ambient daylight | 10,000 - 25,000 lux | | Direct sunlight | 32,000 - 100,000 lux |
No declarations were skipped in this snapshot.