com.unity.polyspatial.visionos@2.0.0-pre.9

## [2.0.0-pre.9] - 2024-07-24

### Added
- Added `Hybrid` app mode. This allows an application to switch between Metal and RealityKit mode at runtime. Hybrid mode requires PolySpatial. Refer to the **PolySpatial Hybrid apps on visionOS** section of the PolySpatial VisionOS documentation for more information.
- Added the ability to create multiple volume cameras. Refer to the **Volume cameras** section of the PolySpatial VisionOS documentation for more information.

### Changed
- Updated instructions for setting up 2.x prerelease packages. This currently requires manually pointing your project's manifest.json at the appropriate package versions.
- Several VisionOS prefixed components (such as VisionOSVideoComponent and VisionOSImageBasedLight) have had DisallowMultipleComponent applied to them, and cannot be added multiple times to the same GameObject.

Author: Unity Technologies

CHANGELOG.md

@@ -9,12 +9,24 @@ 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.0.0-pre.3] - 2024-04-22
+## [2.0.0-pre.9] - 2024-07-24
 
 ### Added
+- Added `Hybrid` app mode. This allows an application to switch between Metal and RealityKit mode at runtime. Hybrid mode requires PolySpatial. Refer to the **PolySpatial Hybrid apps on visionOS** section of the PolySpatial VisionOS documentation for more information.
+- Added the ability to create multiple volume cameras. Refer to the **Volume cameras** section of the PolySpatial VisionOS documentation for more information. 
+
+### Changed
+- Updated instructions for setting up 2.x prerelease packages. This currently requires manually pointing your project's manifest.json at the appropriate package versions.
+- Several VisionOS prefixed components (such as VisionOSVideoComponent and VisionOSImageBasedLight) have had DisallowMultipleComponent applied to them, and cannot be added multiple times to the same GameObject.
+
 
+## [2.0.0-pre.3] - 2024-04-22
+
+### Added
 - Added a loading screen during initial Play To Device loading
 - Added support for procedural skinned meshes. Updating a skinned mesh will now notify all skinned mesh renderers using that mesh to update.
+- Added support for adding new reference images at runtime, refer to [ARFoundation](https://docs.unity3d.com/Packages/com.unity.xr.arfoundation@6.0/manual/features/image-tracking.html#add-new-reference-images-at-runtime) documentation.
+- Added tracked image support to the "PolySpatial XR" Plug-in Provider, under XR Plug-in Managment.
 
 ### Changed
 

Documentation~/Assets.md

@@ -15,11 +15,7 @@ Please refer to [PolySpatial Material Support](Materials.md) for detailed inform
 Please refer to [Shader Graph Support](ShaderGraph.md) for detailed information about how custom shaders defined via Unity Shader Graph are converted to MaterialX to interop with RealityKit.
 
 ## Textures
-Unity provides support for 2D textures on visionOS, and takes advantage of native texture compression options. 
-
-RealityKit for visionOS does not support 3D textures or cubemaps, so PolySpatial emulates these using 2D textures.  This carries two limitations:
-* First, the height times the depth (where cube maps have a fixed depth of 6) must be less than or equal to visionOS's maximum texture height (currently 8192).  This means that cube maps with power-of-two dimensions must be sized 1024 or smaller, and 3D textures with equal power-of-two dimensions cannot be larger than 64.
-* Second, due to the way that 3D texture coordinates are mapped to slices within a 2D texture, artifacts may appear when displaying texture mipmap levels whose sizes are not evenly divisible by their compressed texture block size (e.g., 6 for ASTC6x6).  If this becomes apparent, consider switching to an uncompressed texture format.
+Unity provides support for 2D textures, 3D textures, and cube maps on visionOS, and takes advantage of native texture compression options. 
 
 ### Render Textures
 Please refer to [PolySpatial Render Texture Support](RenderTextures.md) for detailed information about support for render textures.

Documentation~/Billboard.md

@@ -0,0 +1,13 @@
+---
+uid: psl-vos-billboard
+---
+# Billboard
+
+The **VisionOSBillboard** component ensures an object always faces the user, even in modes where head position isn't directly available, such as shared mode. This is particularly useful for text, UI, and other oriented content.  In visionOS, this maps directly to the [BillboardComponent](https://developer.apple.com/documentation/realitykit/billboardcomponent), and is ignored on other platforms. In  Unity play mode, we provide similar functionality which will show only the Game view targeting the main camera.
+
+| **Property** | **Description** |
+| --- | --- |
+| **Blend Factor** | "Degree" that entity rotates towards camera.  |
+| **Forward Direction** | Vector in local space that will point towards camera. |
+| **Up Direction** | Direction in local space to align with world up. |
+| **Rotation Axis** | World space axis to rotate around, if any. |

Documentation~/CustomFunctionNode.md

@@ -35,7 +35,7 @@ Swizzling vector values is supported.  For example, `float3(1, 2, 3).xz` is equi
 ## Supported Functions
 
 ### HLSL Intrinsic Functions
-The parser supports a subset of HLSL's intrinsic functions: `abs`, `acos`, `all`, `any`, `asin`, `atan`, `atan2`, `ceil`, `clamp`, `cos`, `cosh`, `cross`, `degrees`, `distance`, `dot`, `exp`, `exp2`, `floor`, `fmod`, `frac`, `isinf`, `isnan`, `length`, `lerp`, `log`, `max`, `min`, `mul`, `normalize`, `pow`, `radians`, `rcp`, `reflect`, `refract`, `round`, `rsqrt`, `saturate`, `sign`, `sin`, `sinh`, `smoothstep`, `sqrt`, `step`, `tan`, `tanh`, `transpose`, `trunc`
+The parser supports a subset of HLSL's intrinsic functions: `abs`, `acos`, `all`, `any`, `asin`, `atan`, `atan2`, `ceil`, `clamp`, `cos`, `cosh`, `cross`, `ddx`, `ddy`, `degrees`, `distance`, `dot`, `exp`, `exp2`, `floor`, `fmod`, `frac`, `fwidth`, `isinf`, `isnan`, `length`, `lerp`, `log`, `max`, `min`, `mul`, `normalize`, `pow`, `radians`, `rcp`, `reflect`, `refract`, `round`, `rsqrt`, `saturate`, `sign`, `sin`, `sinh`, `smoothstep`, `sqrt`, `step`, `tan`, `tanh`, `transpose`, `trunc`
 
 ### PolySpatial-Specific Functions
 Additionally, the parser supports the custom `splitlr` function, which implements the splitlr function described in the [MaterialX Spec](https://materialx.org/assets/MaterialX.v1.38.Spec.pdf):
@@ -45,7 +45,7 @@ genType splitlr(genType valuel, genType valuer, float center, float2 texcoord);
 (where `genType` is one of `float`, `float2`, `float3`, or `float4`)
 
 ### Unity Macros
-For sampling textures, the parser supports Unity macros: `SAMPLE_TEXTURE2D`, `SAMPLE_TEXTURE2D_LOD`, `SAMPLE_TEXTURE3D`, `SAMPLE_TEXTURE3D_LOD`, `SAMPLE_TEXTURECUBE_LOD`
+For sampling textures, the parser supports Unity macros: `GATHER_TEXTURE2D`, `SAMPLE_TEXTURE2D`, `SAMPLE_TEXTURE2D_LOD`, `SAMPLE_TEXTURE3D`, `SAMPLE_TEXTURE3D_LOD`, `SAMPLE_TEXTURECUBE_LOD`
 
 ## Supported Globals
 The parser supports several of Unity's built-in global variables: `_Time`, `_SinTime`, `_CosTime`, `unity_DeltaTime`, `unity_ObjectToWorld`, `unity_WorldToObject`, `UNITY_MATRIX_V`, `UNITY_MATRIX_I_V`, `UNITY_MATRIX_P`, `UNITY_MATRIX_I_P`, `UNITY_MATRIX_VP`, `UNITY_MATRIX_I_VP`

Documentation~/DevelopmentAndIteration.md

@@ -4,18 +4,20 @@ uid: psl-vos-development
 # Development & Iteration
 
 ## Prerequisites
-Please refer to [visionOS Mixed Reality Requirements & Limitations](Requirements.md) for information about supported hardware, software, and Unity features.
+Please refer to [visionOS Support Requirements & Limitations](Requirements.md) for information about supported hardware, software, and Unity features.
 
 <!-- TODO: ## Package Setup Instructions -->
 
-## Enable Mixed Reality mode
-visionOS support for Mixed Reality is provided via Unity PolySpatial. When the active build target is visionOS and "Mixed Reality" is selected as the App Mode in **Edit &gt; Project Settings &gt; XR Plugin-in Management &gt; Apple visionOS &gt; App Mode**, PolySpatial is automatically enabled and configured for visionOS. If Mixed Reality is not selected as the App Mode, or on other platforms, PolySpatial is disabled.
+## Enable RealityKit mode
+visionOS support for RealityKit is provided via Unity PolySpatial. When the active build target is visionOS and "RealityKit" or "Hybrid" is selected as the App Mode in **Edit &gt; Project Settings &gt; XR Plugin-in Management &gt; Apple visionOS &gt; App Mode**, PolySpatial is automatically enabled and configured for visionOS. If RealityKit or Hybrid is not selected as the App Mode, or on other platforms, PolySpatial is disabled.
 
 ## Iteration and Preview
-When targeting visionOS Mixed Reality, Unity's regular play mode and build workflows are used. Additionally, visionOS Mixed Reality supports "Play to Device" for rapid iteration on actual hardware via play mode.
+When targeting visionOS RealityKit, Unity's regular play mode and build workflows are used. Additionally, visionOS RealityKit supports "Play to Device" for rapid iteration on actual hardware via play mode.
 
 ### Play Mode
-The fastest way to preview content is to enter Play Mode within the Unity Editor. When targeting visionOS Mixed Reality, entering play mode will enable PolySpatial in the editor. A parallel hierarchy of GameObjects is created that represent the objects that will be visible on the PolySpatial target. When previewing in play mode in the editor, Volume Cameras are ignored, and the preview is displayed from the viewpoint of the a regular Unity Camera. PolySpatial objects are created in the PolySpatial layer. To ensure you are viewing the end result objects, make sure the active camera's culling mask shows only PolySpatial objects. In the editor, PolySpatial will attempt to manage this for you directly, and will create and configure a mirror of the main camera.
+The fastest way to preview content is to enter Play Mode within the Unity Editor. When targeting visionOS RealityKit, entering play mode will enable PolySpatial in the editor. A parallel hierarchy of GameObjects is created that represent the objects that will be visible on the PolySpatial target platform. When previewing in play mode in the editor, the preview is displayed from the viewpoint of the main Unity Camera. PolySpatial objects are created in the PolySpatial layer. To ensure you are viewing the end result objects, make sure the active camera's culling mask shows only PolySpatial objects. In the editor, PolySpatial will attempt to manage this for you directly, and will create and configure a mirror of the main camera.
+
+When working with multiple volumes, the **Target Display** of each Volume Camera can be set to a different value, allowing you to cycle between volumes in the Game tab. See [Volume Camera](VolumeCamera.md) for more information.
 
 When playing in the editor, Unity's rendering system is used instead of RealityKit, as it would be on visionOS. As such, it will not be a faithful representation of visuals or performance characteristics of visionOS.
 
@@ -25,7 +27,7 @@ Most options in build settings are analogous to those provided for iOS. visionOS
 As with iOS, when building for a device, you must configure a valid provisioning profile and signing certificate in order to deploy the built application.
 
 ### Play to Device
-Unity's visionOS Mixed Reality support includes **Play to Device**, a new workflow that allows you to enter Play Mode in the editor and instantly see your content on an attached device. You can inspect or make changes to your content live, and can provide input either via the device or the editor.
+Unity's visionOS RealityKit support includes **Play to Device**, a new workflow that allows you to enter Play Mode in the editor and instantly see your content on an attached device. You can inspect or make changes to your content live, and can provide input either via the device or the editor. See [Play To Device](PlayToDevice.md) for more information.
 
 ### Recording and Playback
 PolySpatial-based platforms support a recording and playback workflow that allows you to record a session (including input commands) and then play it back within the Unity Editor. For more information, see information about [PolySpatial tooling](Tooling.md)
@@ -35,7 +37,7 @@ The standard debugging workflow works normally on visionOS. Enable **Script Debu
 
 ## Project Validation
 
-Unity's visionOS Mixed Reality platform provides a way to validate your visionOS project before building and deploying to a device. Unsupported scene objects will be indicated by a warning icon in the Hierarchy view, while the Inspector view provides helpful UIs to navigate between these objects and address the issues. For detailed information about the validation system, please refer to the [Project Validation](PolySpatialXRProjectValidation.md) page.
+Unity's visionOS RealityKit platform provides a way to validate your visionOS project before building and deploying to a device. Unsupported scene objects will be indicated by a warning icon in the Hierarchy view, while the Inspector view provides helpful UIs to navigate between these objects and address the issues. For detailed information about the validation system, please refer to the [Project Validation](PolySpatialXRProjectValidation.md) page.
 
 ## Building Blocks in PolySpatial XR
 

Documentation~/Extensions.md

@@ -0,0 +1,15 @@
+---
+uid: psl-vos-extensions-package
+---
+# Extensions Package
+
+Unity’s **PolySpatial Extensions** package provides functionality that is either optional, or currently experimental. 
+
+> [!NOTE]
+> Experimental features are only being developed for Unity 6+ and URP with RenderGraph enabled.
+
+| Topic | Description |
+|-------|-------------|
+| [Stereo Render Targets *(Experimental)*](StereoRenderTargets.md) | Enables a camera to render into a single-pass-stereo framebuffer and then display this in various ways in visionOS RealityKit mode. |
+| DOTS/ECS Rendering | Synchronize DOTS/ECS over PolySpatial. |
+

Documentation~/ExtensionsImport.md

@@ -0,0 +1,14 @@
+---
+uid: psl-vos-extensions-package
+---
+# Import Extensions Package
+
+To add the extensions package to a project:
+
+1. [Install PolySpatial and visionOS support](xref:psl-vos-install).
+2. Open the Package Manager window (menu: **Window > Package Manager**).
+3. Open the **Add package by name** dialog.
+4. Enter the package ID `com.unity.polyspatial.extensions`.
+5. Click **Add**.
+
+The Unity Package Manager installs the extensions package in your project.