SpotLightComponent
A component that defines a spotlight source.
Declaration
struct SpotLightComponentMentioned in
Overview
A spotlight illuminates a cone-shaped volume in the entity’s local forward direction along the z-axis’s negative direction, or [0.0, 0.0, -1.0]. Change the a spotlight’s direction with the Entity/orientation or look(at:from:upVector:relativeTo:) method, of the Entity with a spotlight component.
The light’s innerAngleInDegrees and outerAngleInDegrees reflect the size of the light’s cone relative to the entity’s forward direction. The light is at full intensity between 0 degrees and innerAngleInDegrees. RealityKit attenuates the light’s intensity between the inner angle and the outer angle. The spotlight’s intensity is 0.0 beyond the outer angle.
The following table shows some real-world scenarios, to better explain how you can use intensity to control the brightness of the light in lumens, and attenuationRadius to control how the level of brightness diminishes with distance from the light source:
Scenario | Approximate Lumens | Attenuation Radius | Description |
|---|---|---|---|
Small Accent Spotlight | 100-200 lumens | 5-10 meters | Highlights small objects or artwork |
LED flashlight | 300-600 lumens | 50-70 meters | Beams a long distance illumination |
Theatrical Spotlight | 500-1,000 lumens | 20-40 meters | Focuses attention to performers on a stage |
Outdoor Security Spotlight | 1,000-2,000 lumens | 20-30 meters | Brightly illuminates specific outdoor areas |
Film/TV Production Spotlight | 5,000-10,000 lumens | 50-100 meters | Provides focused, high-intensity lighting for sets |
Large-Scale Event Spotlight | 50,000-100,000 lumens | 200-500 meters | Lights large outdoor events or concerts |
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. Both the number of lights and each light’s coverage affect performance, so use properties like attenuationRadius to keep a light’s influence no larger than your scene needs. Monitor the thermal state and reduce usage 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
Configuring the spotlight
Supporting types
Specifying the render layers
Defining the light contribution
Structures
Initializers
init(color:intensity:innerAngleInDegrees:outerAngleInDegrees:attenuationRadius:)init(color:intensity:innerAngleInDegrees:outerAngleInDegrees:attenuationRadius:attenuationFalloffExponent:)