Unity PolySpatial Lighting Support
VisionOS provides image based lighting as well as dynamic point, spot, and directional lights. PolySpatial also includes a lighting solution available to shader graphs that provides a subset of the lighting features available in Unity. The PolySpatial Lighting Data Extension and PolySpatial Lighting Node support directional lightmaps, light probes, and up to four dynamic lights (point, spot, or directional).
VisionOS Lighting
Lit materials (both standard shaders such as Universal Render Pipeline/Lit and shader graphs using Lit targets) use visionOS lighting by default. This lighting comprises image based lighting (derived from the device cameras and/or environment maps) and, optionally, dynamic point, spot, and directional lights. Spot and directional lights support shadows.
Because visionOS uses different lighting calculations from Unity, the appearance of lit objects in visionOS will not exactly match that of objects rendered in the Unity editor. To achieve a closer match for dynamic lights, you may wish to use the PolySpatial Lighting Data Extension or PolySpatial Lighting Node.
VisionOS Light Settings
To control the default behavior for dynamic lights in visionOS, use the Default VisionOS Lighting option under PolySpatial in Project Settings. This defaults to Image Based Only, but you can change it to Image Based and Dynamic Lights to enable point/spot/directional lights for standard Lit materials in visionOS, or to Image Based, Dynamic Lights, and Shadows to enable spot/directional shadows as well.
There are two additional settings that control shadow behavior specific to visionOS:
- Because visionOS uses only a fixed depth bias for shadows (versus Unity's fixed plus directional biases), the
Default VisionOS Shadow Bias Offsetsetting provides a means to add an additional depth bias amount to shadows on visionOS. - Because visionOS does not use cascaded shadow maps for directional lights, it requires a maximum distance to be set relatively close to the camera. The
Default VisionOS Directional Shadow Max Distancesetting controls the maximum distance away from the camera to render directional shadow maps. Set this to a small value (such as 2-3 meters) for typical indoor bounded scenes in order to maximize the apparent resolution of the shadow map.
To control visionOS light behavior on a per-light basis, add an instance of the VisionOS Light Settings component to the GameObject containing the Light instance. This has the same options as the defaults in the PolySpatial project settings.
PolySpatial Lighting Data Extension
To add PolySpatial lighting to a shader graph with a Lit material, add the PolySpatial Lighting data extension to the Data Extension Settings section, located under Target Settings in the Graph Inspector. This will cause the MaterialX version of the shader graph used in visionOS to include lighting functionality as determined by the extension options:
| Option | Description |
|---|---|
| Baked Lighting | The Unity baked lighting to include: either None, Lightmap or LightProbes. |
| Reflection Probes | The Unity reflection probe contribution: either None, Simple, or Blended. |
| Dynamic Lighting | If true, apply dynamic Unity point/spot/directional light contribution. |
| VisionOS Lighting | If true, also apply visionOS lighting (imaged based and dynamic point/spot/directional lights, as described in the previous section). |
In the Unity editor view (in or out of play mode), the PolySpatial Lighting Data Extension will have no visible effect: lit shader graphs will simply use Unity's standard lighting model. The options in the extension apply only to the appearance of the shader graph in visionOS. Without the extension, in visionOS, lit shader graphs will behave as if only the VisionOS Lighting option was enabled.
The Unity-specific lightmap, light probe, reflection probe, and dynamic lighting is subject to the limitations of the PolySpatial Lighting Node described in the following section.
PolySpatial Lighting Node
As an alternative to the PolySpatial Lighting Data Extension, you may instead include PolySpatial lighting by creating an instance of the PolySpatial Lighting Node using the Create Node command in the shader graph editor. This allows you to process the lighting output before routing it to an output block (such as Base Color or Emission), but it requires that you explicitly provide the lighting inputs such as Metallic and Smoothness to the node and it will only appear correctly in builds and in play mode. Because it requires information from the PolySpatial runtime, it will not appear correctly in material previews or the editor scene view.
Inputs
The inputs to the lighting node are largely the same as the inputs to the Lit shader graph target--Base Color (albedo), Normal (in tangent space), Metallic, Smoothness, Emission, and Ambient Occlusion--with the additional of a Lightmap UV input for lightmap texture coordinates.
Output
The output (Out) of the lighting node is a single color result. Depending on your application, you may wish to supply this output directly to the Base Color input of an Unlit target (if you wish to use only PolySpatial lighting) or to the Emission input of a Lit target (if you wish to combine PolySpatial lighting with visionOS's lighting).
Limitations
Only static directional lightmaps with dLDR encoding are supported.
Settings
Baked Lighting
The Baked Lighting setting has three options: None to omit baked lighting entirely, Lightmap to apply baked lightmaps, and LightProbes to obtain baked lighting from light probes. Typically, static objects use lightmaps and dynamic objects use light probes.
Reflection Probes
The Reflection Probes setting has three options: None to omit contribution from reflection probes, Simple to use a single reflection probe, and Blended to blend the contributions of up to two reflection probes.
Dynamic Lighting
The Dynamic Lighting toggle determines whether dynamic point/spot/directional lights (that is, lights represented by non-baked Light components) affect the output.
Light Selection
The Render Mode property of Light components may be used to control which dynamic lights are applied. Lights marked Not Important will never be included in the four lights used by the PolySpatial Lighting Node. Other lights will be sorted by the following criteria, in descending order of precedence:
- Directional lights take priority over point/spot lights.
- Shadow casting lights take priority over non-shadow-casting lights.
- Lights marked Important take priority over lights marked Auto (the default).
- Lights with positive instance IDs (typically loaded from scenes) take priority over lights with negative instance IDs (typically created at runtime).
- Lights with lower instance ID absolute values take priority over ones with higher absolute values (typically, this means lights created earlier take priority).
After sorting, the first four lights will be selected for use as dynamic lights.
PolySpatial Environment Radiance Node
To access visionOS's image based lighting (in either Lit or Unlit shader graphs), create an instance of the PolySpatial Environment Radiance Node. This accepts surface parameters (BaseColor, Roughness, Specular, Metallic, and Normal) and outputs Diffuse Radiance and Specular Radiance colors representing the lighting results. For example, to get an approximation of the ambient light level, use a BaseColor of white, Roughness of 1.0, Specular and Metallic of 0.0, and the default Normal. The Diffuse Radiance output will be approximately equal to the ambient light level. Note that the output of PolySpatial Enviroment Radiance is entirely separate from the lighting applied to Lit targets; for instance, if you add the Diffuse Radiance and Specular Radiance outputs together and connect them to the Emission output of a Lit target, you will end up with twice the overall brightness.