SpotLightComponent

struct · iOS 13.0+ · SDK 27.1

struct SpotLightComponent

A component that defines a spotlight source. 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 ``HasTransform/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. - Tip: Turn on shadows for a spotlight by adding the ``Shadow`` component to an entity that has a `SpotLightComponent`. 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)`.

Members (12)

get attenuationRadius(): number

var attenuationRadius: Float

set attenuationRadius(value: number)

var attenuationRadius: Float

get innerAngleInDegrees(): number

var innerAngleInDegrees: Float

set innerAngleInDegrees(value: number)

var innerAngleInDegrees: Float

get outerAngleInDegrees(): number

var outerAngleInDegrees: Float

set outerAngleInDegrees(value: number)

var outerAngleInDegrees: Float

get attenuationFalloffExponent(): number

var attenuationFalloffExponent: Float { get set }

set attenuationFalloffExponent(value: number)

var attenuationFalloffExponent: Float { get set }

get layers(): RenderLayer_Set

var layers: RenderLayer.Set { get set }

set layers(value: RenderLayer_Set)

var layers: RenderLayer.Set { get set }

get intensity(): number

var intensity: Float

set intensity(value: number)

var intensity: Float

All RealityFoundation types →