com.unity.polyspatial.visionos@2.1.2

## [2.1.2] - 2024-11-26

### Added

### Changed
- Restored `PolySpatialWindowManagerAccess.entityForIdentifier`/`identifierForEntity` that was removed when adding multi-volume support and added `entitiesForUnityInstanceId` to return Entities from all volumes.
- Improved performance of blend shapes by enabling asynchronous processing.
- Entities merged via static batching now include the source entities' synchronized components (sort groups, image based light receivers, environment lighting configurations, grounding shadows, and hover effects).
- Updated Metal Samples presentation image and added known limitations section to the Play to Device Section.

### Deprecated

### Removed

### Fixed
- Fixed edge cases with blend shape support: support meshes with no vertices and meshes with no bone weights.
- Fixed issue where raycastable UGUI components would not be removed from scene when hidden (when scrolling, e.g.)
- Fixed a bug with tracked images over play to device.

### Security

Author: Unity Technologies

.signature

@@ -0,0 +1 @@
+{"timestamp":1732673778,"signature":"GstTTuoebO+Fn13ydZI/oE5oZlbYwsVxLMvpiHGzIBY/nGoyuDhycazAet90bH9XOIxx6gsCvGlnbmKq7c9II/iqAfTItvFWkkzBZTyxIGAzLyaPHKi0QuM02prr453VpK+/3e/tuBez8kzHY4nhlnbN1RGbU74uzorMwx8Io+1okLKKM6Cqo5xjPHI6LHUUIEoZ+XA6ubR8EbvVsU08zop8ExqBqkJceYJJw4HMsCi1cbNVgV7Qil23kY176a1dmDSAq4lMQHfEoW4vfbJa6lHMHRt9uO+0d/9D9r8NWXXODnWxWd5z7k8f9y4siyKvQD7XzRZJhcJD837XgwJ5gxazA3Qh6Nn1QhhqjMA5xzyFPWCijSAzdhHJ0l1QDPos6hpfjwosBHBeuNZRTeQ1WKE7WW0dLlVbYZBLKf5zwasN9hhAyIFMtMcvw9XRTV/C/ZSiWTlENHAFO2NCj+GNmD8jPVjHG0/bqeee3WzD2m9ZPtWmbe/H5ikeE/TG6pn4","publicKey":"LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQm9qQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FZOEFNSUlCaWdLQ0FZRUFzdUhXYUhsZ0I1cVF4ZEJjTlJKSAordHR4SmoxcVY1NTdvMlZaRE1XaXhYRVBkRTBEMVFkT1JIRXNSS1RscmplUXlERU83ZlNQS0ZwZ1A3MU5TTnJCCkFHM2NFSU45aHNQVDhOVmllZmdWem5QTkVMenFkVmdEbFhpb2VpUnV6OERKWFgvblpmU1JWKytwbk9ySTRibG4KS0twelJlNW14OTc1SjhxZ1FvRktKT0NNRlpHdkJMR2MxSzZZaEIzOHJFODZCZzgzbUovWjBEYkVmQjBxZm13cgo2ZDVFUXFsd0E5Y3JZT1YyV1VpWXprSnBLNmJZNzRZNmM1TmpBcEFKeGNiaTFOaDlRVEhUcU44N0ZtMDF0R1ZwCjVNd1pXSWZuYVRUemEvTGZLelR5U0pka0tldEZMVGdkYXpMYlpzUEE2aHBSK0FJRTJhc0tLTi84UUk1N3UzU2cKL2xyMnZKS1IvU2l5eEN1Q20vQWJkYnJMbXk0WjlSdm1jMGdpclA4T0lLQWxBRWZ2TzV5Z2hSKy8vd1RpTFlzUQp1SllDM0V2UE16ZGdKUzdGR2FscnFLZzlPTCsxVzROY05yNWdveVdSUUJ0cktKaWlTZEJVWmVxb0RvSUY5NHpCCndGbzJJT1JFdXFqcU51M3diMWZIM3p1dGdtalFra3IxVjJhd3hmcExLWlROQWdNQkFBRT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg"}

CHANGELOG.md

@@ -9,6 +9,27 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 For general changes to PolySpatial, refer to the [PolySpatial Changelog](https://docs.unity3d.com/Packages/com.unity.polyspatial@latest?subfolder=/changelog/CHANGELOG.html).
 
+## [2.1.2] - 2024-11-26
+
+### Added
+
+### Changed
+- Restored `PolySpatialWindowManagerAccess.entityForIdentifier`/`identifierForEntity` that was removed when adding multi-volume support and added `entitiesForUnityInstanceId` to return Entities from all volumes.
+- Improved performance of blend shapes by enabling asynchronous processing.
+- Entities merged via static batching now include the source entities' synchronized components (sort groups, image based light receivers, environment lighting configurations, grounding shadows, and hover effects).
+- Updated Metal Samples presentation image and added known limitations section to the Play to Device Section.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+- Fixed edge cases with blend shape support: support meshes with no vertices and meshes with no bone weights.
+- Fixed issue where raycastable UGUI components would not be removed from scene when hidden (when scrolling, e.g.)
+- Fixed a bug with tracked images over play to device.
+
+### Security
+
 ## [2.0.4] - 2024-09-25
 
 ### Added

Documentation~/MetalApps.md

@@ -19,29 +19,9 @@ Set the App Mode to **Metal Rendering with Compositor Services**. If you are usi
 
 ![MetalAppSetting](images/ReferenceGuide/MetalAppSettings.png)
 
-The Apple visionOS project settings menu has a few properties pertaining to the **Metal Rendering with Compositor Services** app mode.
-
-[//]: # (TODO: LXR-3988 Once visionOS plug-in docs page is created, put the below into that docs page.)
-| **Property**                            | **Description**                                                                                                                                                                                                                                                                                                                                                                          |
-|:----------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| **Initialize Hand Tracking On Startup** | Initializes hand tracking when application starts up.                                                                                                                                                                                                                                                                                                                                    |
-| **Metal Immersion Style**               | Defines the immersion style to be used in Metal-based apps. Immersion style determines whether an app will have pass-through. For Metal-based apps, only two immersion styles are valid - **Mixed** and **Full**. The **Progressive** immersion style is not supported with Metal-based apps.                                                                                            |
-|     *Automatic*     | For Metal-based apps, choosing **Automatic** will cause the app to fallback to **Mixed** immersion style.                                                                                                                                                                                                                                                                                |
-|     *Full*          | With this immersion style, pass-through is disabled, and only the skybox will be shown.                                                                                                                                                                                                                                                                                                  |
-|     *Mixed*         | With this immersion style, apps will have pass-through video feed. This immersion style allows an app to switch at runtime between allowing pass-through and rendering the skybox.                                                                                                                                                                                                       |
-| **RealityKit Immersion Style**          | Defines the immersion style to be used in RealityKit-based apps. Immersion style determines whether your application will have pass-through. Although all immersion styles are applicable to RealityKit-based apps, the effects of some immersion styles will differ depending on the **VolumeCamera** **Mode**.                                                                         |
-|     *Automatic*     | For RealityKit-based apps, choosing **Automatic** will cause the app to fallback to **Mixed** immersion style.                                                                                                                                                                                                                                                                           |
-|     *Full*          | If all **VolumeCamera**s are set to **Bounded** **Mode**, content will still appear with pass-through, as if the app was in **Mixed** immersion style. If one **VolumeCamera** in the scene is set to **Unbounded** **Mode**, pass-through will be disabled and replaced with a black background, and only content will be visible. The **Digital Crown** will have no effect.           |
-|     *Mixed*         | With this immersion style, apps will have pass-through video feed. **VolumeCamera** **Mode** will have no effect on this immersion style.                                                                                                                                                                                                                                                |
-|     *Progressive*   | If all **VolumeCamera**s are set to **Bounded** **Mode**, content will still appear with pass-through, as if the app was in **Mixed** immersion style. If one **VolumeCamera** in the scene is set to **Unbounded** **Mode**, content will appear inside a radial portal with a black background. See [Progressive Immersion](RealityKitApps.md#progressive-immersion) for more details. |
-| **Upper Limb Visibility**               | This option allows for controlling whether the hands are visible within the app. This option is ignored if the **App Mode** is Windowed, or if the **App Mode** is  set to RealityKit but the scene consists of only **Bounded** **VolumeCamera**s.                                                                                                                                      |
-|     *Automatic*     | Hands visibility will be determined by visionOS's default hands setting, which will depend on the context.                                                                                                                                                                                                                                                                               |
-|     *Visible*       | In **Metal** **App Mode**, the hands will always be visible in the app. Hands always render on top of virtual content. In **RealityKit** **App Mode**, the hands are blended with virtual content based on depth.                                                                                                                                                                        |
-|     *Hidden*        | In **Metal** **App Mode**, the hands will be hidden, which may be beneficial if you wish to present virtual hands instead. In **RealityKit** **App Mode**, the hands will be displayed behind virtual content.                                                                                                                                                                           |
-| **Foveated Rendering**                  | This option controls whether foveated rendering is enabled or disabled. This option only applies to Metal-based content, and requires the Universal Render Pipeline.                                                                                                                                                                                                                     |
-| **IL2CPP Large Exe Workaround**         | When building your project in Xcode, you may encounter an error such as `ARM64 branch out of range`, especially with larger projects. This option will patch the project to work around this error.                                                                                                                                                                                      |
-
-After modifying the project settings, select and build for the visionOS platform in the **Build Profiles** menu. This will generate a Unity XCode Project. From here on, you'll continue the build process in the XCode project, debugging in XCode as needed.
+The [visionOS project settings](VisionOSSettings.md) menu has a few properties pertaining to the **Metal Rendering with Compositor Services** app mode.
+
+After modifying the visionOS settings, select and build for the visionOS platform in the **Build Profiles** menu. This will generate a Unity XCode Project. From here on, you'll continue the build process in the XCode project, debugging in XCode as needed.
 
 >Please note that Unity is still building towards feature parity with the Metal API on XCode, so you might observe warnings from Metal’s API validation layer. To work around this, you can turn off the Metal API Validation Layer via XCode’s scheme menu.
 

Documentation~/MetalSamples.md

@@ -18,7 +18,7 @@ The **XR Interaction Toolkit** is required by the sample scenes, but the **XR Ha
 
 ## Scene elements
 
-The [ARSession](xref:arfoundation-session) and [ARInputManager](xref:arfoundation-session#ar-input-manager) components must exist in all Metal and Hybrid scenes on visionOS. These components are required because the visionOS platform provides head and hand tracking data through Apple's ARKit. These components can be on any GameObject in your scene, but only one of each should be present. In the Metal Sample scene, the components are on the GameObject named "AR Session." In addition to head and hand tracking data, ARKit on visionOS provides world meshes, planes, and image markers tracked by the device.
+The [ARSession](xref:arfoundation-session) and [ARInputManager](xref:arfoundation-session#ar-input-manager) components must exist in all Metal and Hybrid scenes on visionOS. These components are required because the visionOS platform provides head and hand tracking data through Apple's ARKit. These components can be on any GameObject in your scene, but only one of each should be present. In the Metal Sample scene, the components are on the GameObject named "AR Session." In addition to head and hand tracking data, ARKit on visionOS provides world meshes, planes, and image markers tracked by the device.  With visionOS 2.0 we support object tracking and environment probes as well.
 
 > [!NOTE]
 > On visionOS, Apple ARKit features are implemented by the [Apple visionOS XR Plugin](https://docs.unity3d.com/Packages/com.unity.xr.visionos@latest) package (com.unity.xr.visionos). You do not need the [Apple ARKit](https://docs.unity3d.com/Packages/com.unity.xr.arkit@latest) package (com.unity.xr.arkit), which implements ARKit features for iOS.

Documentation~/PlayToDevice.md

@@ -163,3 +163,13 @@ As explained above, you must use a version of the Play to Device Host app that m
   * In the build details view, tap `Install`.
 
 You can find more information about TestFlight and how to test previous builds in the [official documentation](https://testflight.apple.com/#testing-previous-builds).
+
+## Limitations of using Play To Device
+
+Even though the Play to Device feature is a powerful tool for iterating on your content, it will not replace how some features will work in a real device. Here are some limitations to keep in mind:
+
+* Video Component: The [VisionOSVideoComponent](VideoComponent.md#visionosvideocomponent) may not work as expected when connected to a PlayToDevice host. Over a network, the VisionOSVideoComponent will not work, while the Unity VideoPlayer component will work, albeit with a performance cost.
+* PlayToDevice may incur a performance hit when using render textures, and render textures may render slowly or may stutter while connected.
+* Play to Device may not be able to accommodate your `VolumeCamera`'s specific `Output Dimension`. The number of available `VolumeCamera` window sizes (`OutputDimension`) is limited in PlayToDevice, and PlayToDevice will attempt to match user requested dimensions to available window sizes.
+* Object tracking is not supported in the Play to Device app.
+* XR Meshes over windows are not supported over Play to Device.

Documentation~/PolySpatialLighting.md

@@ -3,12 +3,12 @@ uid: psl-vos-polyspatial-lighting
 ---
 
 # 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 Node supports directional lightmaps, light probes, and up to four dynamic lights (point, spot, or directional).
+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](ImageBasedLight.md) (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 Node`.
+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.
@@ -19,8 +19,22 @@ There are two additional settings that control shadow behavior specific to visio
 
 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
-To add PolySpatial lighting to a shader graph, create an instance of the `PolySpatial Lighting Node` using the `Create Node` command in the shader graph editor.
+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.