# OpenVR SDK 2.2.3

* New VREvent_DesktopMightBeVisible: Sent when any known desktop related overlay is visible
* New VREvent_DesktopMightBeHidden: Sent when all known desktop related overlays are hidden

IVRCompositor:
* Added SubmitWithArrayIndex.

IVRDisplayComponent:
* Add documentation on the new ComputeInverseDistortion method.

IVRChaperone:
* Amend comments about GetPlayAreaRect to the correct description of its behavior.
* Add documentation on the chaperone json file.

[git-p4: depot-paths = "//vr/steamvr/sdk_release/": change = 8643635]

codegen/api_shared.py

@@ -522,8 +522,12 @@ def outputinterfaces(namespace, data):
 							paramlist.append('ref ' + paramtype + ' ' + param['paramname'])
 					else:
 						paramlist.append(paramtype + ' ' + param['paramname'])
+					if(paramtype == 'bool'):
+						paramlist[-1] = '[MarshalAs(UnmanagedType.I1)] ' + paramlist[-1];
 
 			print("\t\t[UnmanagedFunctionPointer(CallingConvention.StdCall)]")
+			if(returntype == 'bool'):
+				print("\t\t[return: MarshalAs(UnmanagedType.I1)]")
 			print("\t\tinternal delegate "+returntype+" _"+methodname+"("+", ".join(paramlist)+");")
 			print("\t\t[MarshalAs(UnmanagedType.FunctionPtr)]")
 			print("\t\tinternal _"+methodname+" "+methodname+";\n")

codegen/openvr_capi.h.py

@@ -241,6 +241,12 @@ def OutputStructFields(struct):
 	VREvent_InputBindingLoad_t inputBinding;
 	VREvent_InputActionManifestLoad_t actionManifest;
 	VREvent_SpatialAnchor_t spatialAnchor;
+	VREvent_ProgressUpdate_t progressUpdate;
+	VREvent_ShowUI_t showUi;
+	VREvent_ShowDevTools_t showDevTools;
+	VREvent_HDCPError_t hdcpError;
+	VREvent_AudioVolumeControl_t audioVolumeControl;
+	VREvent_AudioMuteControl_t audioMuteControl;
 } VREvent_Data_t;
 
 #if defined(__linux__) || defined(__APPLE__) 

codegen/openvr_interop.cs.py

@@ -101,6 +101,8 @@
 		[FieldOffset(0)] public VREvent_ShowUI_t showUi;
 		[FieldOffset(0)] public VREvent_ShowDevTools_t showDevTools;
 		[FieldOffset(0)] public VREvent_HDCPError_t hdcpError;
+		[FieldOffset(0)] public VREvent_AudioVolumeControl_t audioVolumeControl;
+		[FieldOffset(0)] public VREvent_AudioMuteControl_t audioMuteControl;
 		[FieldOffset(0)] public VREvent_Keyboard_t keyboard; // This has to be at the end due to a mono bug
 	}
 	""")

docs/Driver_API_Documentation.md

@@ -78,6 +78,7 @@
         - [Binding Duplication](#binding-duplication)
         - [Emulateable Devices](#emulateable-devices)
     - [Render Models](#render-models)
+    - [Chaperone](#chaperone)
     - [Building & Development Environment](#building--development-environment)
         - [Debugging SteamVR with Visual Studio](#debugging-steamvr-with-visual-studio)
 - [Further Examples](#further-examples)
@@ -1171,6 +1172,26 @@ right and covers a single eye.
 * `float fU` - The current U coordinate.
 * `float fV` - The current V coordinate.
 
+```c++
+virtual bool ComputeInverseDistortion( HmdVector2_t *pResult, EVREye eEye, uint32_t unChannel, float fU, float fV ) = 0;
+```
+`ComputeInverseDistortion` is called by the runtime to get the result of the inverse distortion function for the specified eye,
+channel and uv.
+
+Drivers **may** return false from this method to indicate that the runtime should infer an estimate from
+the result returned by `IVRDisplayComponent::ComputeDistortion`.
+
+Returning true from method indicates to the runtime that it should not try to estimate the inverse, and instead use the
+values provided by the driver.
+
+* `HmdVector2_t *pResult` - Driver should write into this with the result for the specified UV.
+* `EVREye eEye` - The eye to get the distortion for. The possible options are:
+    * `Eye_Left` - The left eye.
+    * `Eye_Right` - The right eye.
+* `uint32_t unChannel` - Which channel is requested. 0 for red, 1 for blue, 2 for green.
+* `float fU` - The current U coordinate.
+* `float fV` - The current V coordinate.
+
 #### IVRDriverDirectModeComponent
 
 `IVRDriverDirectModeComponent` is used for drivers that implement direct mode entirely on their own without allowing the
@@ -3486,6 +3507,82 @@ will be set in the override property container.
     * `legacy_buttons` - `[ 0, 1, 2, 32, 33 ]`
     * `legacy_axis` - `[ 1, 3, 0, 0, 0 ]`
 
+## Chaperone
+
+The SteamVR Chaperone system provides visible boundaries for users when inside VR, which should be
+shown at the edges of the play space to avoid collisions with other objects.  
+
+The chaperone system is also responsible for keeping track of the relation between the driver's raw
+tracking space (the tracking space in which the driver provides poses to the runtime through 
+`IVRServerDriverHost::TrackedDevicePoseUpdate`) and the seated and standing universe origins that applications
+query poses relative to.
+
+A description of each of the universes is below, along with their corresponding json property:
+
+    * `TrackingUniverseSeated (seated)` - Useful for applications that need to render content relative to the user's resting head position, such as presenting a cockpit view in simulators.
+    * `TrackingUniverseStanding (standing)` - This is some point on the floor of the tracking space, where y = 0 **must** always be the floor in this tracking space. Useful for applications that want to render content that should scale to the user's real world setup, such as placing the floor at the same location.
+    * "Setup standing (setup_standing2)" - An origin from the raw tracking space. This is some point on the floor which is the center of the play space. The universe is not visible to applications, but the driver **may** choose to use it to break the dependency between where the standing origin should be, and where SteamVR should place the collision bounds relative to. It is optional for the driver to provide this, and if ommitted, it will default to being the same as the standing universe.
+
+Any driver that provides its own tracking solution **should** provide its own chaperone setup.
+
+A driver provides its chaperone setup as a json file. A driver **may** either provide an absolute path
+to the chaperone json file it wishes to present to SteamVR, or provide a json string by setting
+the `Prop_DriverProvidedChaperoneJson_String` property of the HMD container.
+
+A driver **may** provide multiple "universes", where (in this context), a universe represents a different
+location in the real world that requires a separate chaperone setup, such as switching to a different room.
+
+SteamVR only allows one chaperone universe to be active at a time. A driver **must** specify the 
+universe that it wishes to use by setting the `Prop_CurrentUniverseId_Uint64` property to the universe id
+it wises to use (more details below).
+
+The provided json **must** be valid, with no trailing commas, but **may** contain comments prefixed by `//`.
+
+    * `json_id` - **required**. Set to `chaperone_info`.
+    * `version` - **required**. Current chaperone json version is `5`.
+    * `time` - **required**. The ISO timestamp when the chaperone file was last modified.   
+    * `universes` - A json array containing json objects that contain:
+        * `collision_bounds` - An array that contains sets of polygons (An array that **should** 
+            contain arrays that contains arrays of 4 elements (the polygons),
+            where each element is an array that contains the x,y,z positions of each vertex).
+            Collision bounds are relative to the **setup standing** play space.
+            Drivers **should** provide 4 vertices per face they are drawing. Drivers **should**
+            provide vertices that are all on the same vertical plane as eachother.
+        * `play_area` - An array that contains two values: `[width, height]` of the play space.
+            The width and height are driver-defined, but **should** represent largest rectangle that 
+            can represent the playable area.
+        * `<seated/standing/setup_standing2>` - A json object that represents the relation between the driver's raw
+            tracking space and the specified universe origin. Drivers **must** provide seated and standing relations,
+            but **may** omit the setup standing universe. In this case, the setup standing universe will be
+            set to what was set for the standing property (see next paragraph). Each **must** contain the following properties:
+            * `translation` - The position offset between the raw origin and the universe's origin
+            * `yaw` - The rotation on the x,z plane between the raw space and universe's space
+        * `universeID` - The id of the universe. This **must** be a uint32 number and **must** be 
+            unique for each different universe.
+
+The driver **must** either:
+1. Set both the setup standing and standing origins.
+    * In this case, the setup standing origin is treated as the center of the play area. The standing origin is free to be placed elsewhere
+2. Set only the standing origin.
+    * In this case, the standing origin is treated as the center of the play area.
+
+### Recentering
+
+The recentering feature in SteamVR allows the user to update the standing and seated universe positions
+while inside SteamVR. This can be useful to reposition your height in a cockpit, or to reposition
+room-scale content relative to a different real-world position.
+
+Initially, the transforms for the standing and seated universes are set by the driver provided chaperone file.
+When a user requests a recenter, SteamVR updates the standing and seated transforms it holds in memory,
+and will attempt to update the seated universe (and only seated universe) in the chaperone file if
+the driver provided one, and that file is writeable. SteamVR **will not** attempt to modify the standing transform.
+
+If a driver wants to configure the way recentering is handled,
+it **may** configure the `Prop_Driver_RecenterSupport_Int32` property with one of the following values:
+* `k_EVRDriverRecenterSupport_SteamVRHandlesRecenter` - Default. SteamVR shows a recenter but and will do the above when a user requests a recenter.
+* `k_EVRDriverRecenterSupport_NoRecenter` - Recentering is not supported and no recenter button will be shown in the UI.
+* `k_EVRDriverRecenterSupport_DriverHandlesRecenter` - A recenter button is shown and an event **will** be triggered for the driver to handle the recenter, but SteamVR will do no additional processing.
+
 ## Render Models
 
 A render model is a 3D model that represents a device in VR. A render model **should** provide a graphical

headers/openvr.h

@@ -16,8 +16,8 @@
 namespace vr
 {
 	static const uint32_t k_nSteamVRVersionMajor = 2;
-	static const uint32_t k_nSteamVRVersionMinor = 0;
-	static const uint32_t k_nSteamVRVersionBuild = 10;
+	static const uint32_t k_nSteamVRVersionMinor = 2;
+	static const uint32_t k_nSteamVRVersionBuild = 3;
 } // namespace vr
 
 // public_vrtypes.h
@@ -531,6 +531,7 @@ enum ETrackedDeviceProperty
 	Prop_Hmd_SupportsHDR10_Bool					= 2093,
 	Prop_Hmd_EnableParallelRenderCameras_Bool	= 2094,
 	Prop_DriverProvidedChaperoneJson_String		= 2095, // higher priority than Prop_DriverProvidedChaperonePath_String
+	Prop_ForceSystemLayerUseAppPoses_Bool		= 2096,
 
 	Prop_IpdUIRangeMinMeters_Float 				= 2100,
 	Prop_IpdUIRangeMaxMeters_Float 				= 2101,
@@ -547,6 +548,10 @@ enum ETrackedDeviceProperty
 	Prop_DSCSliceCount_Int32					= 2111,
 	Prop_DSCBPPx16_Int32						= 2112,
 
+	Prop_Hmd_MaxDistortedTextureWidth_Int32		= 2113,
+	Prop_Hmd_MaxDistortedTextureHeight_Int32	= 2114,
+	Prop_Hmd_AllowSupersampleFiltering_Bool		= 2115,
+
 	// Driver requested mura correction properties
 	Prop_DriverRequestedMuraCorrectionMode_Int32		= 2200,
 	Prop_DriverRequestedMuraFeather_InnerLeft_Int32		= 2201,
@@ -558,10 +563,16 @@ enum ETrackedDeviceProperty
 	Prop_DriverRequestedMuraFeather_OuterTop_Int32		= 2207,
 	Prop_DriverRequestedMuraFeather_OuterBottom_Int32	= 2208,
 
-	Prop_Audio_DefaultPlaybackDeviceId_String		= 2300,
-	Prop_Audio_DefaultRecordingDeviceId_String		= 2301,
-	Prop_Audio_DefaultPlaybackDeviceVolume_Float = 2302,
-	Prop_Audio_SupportsDualSpeakerAndJackOutput_Bool = 2303,
+	Prop_Audio_DefaultPlaybackDeviceId_String				= 2300,
+	Prop_Audio_DefaultRecordingDeviceId_String				= 2301,
+	Prop_Audio_DefaultPlaybackDeviceVolume_Float			= 2302,
+	Prop_Audio_SupportsDualSpeakerAndJackOutput_Bool		= 2303,
+	Prop_Audio_DriverManagesPlaybackVolumeControl_Bool		= 2304,
+	Prop_Audio_DriverPlaybackVolume_Float					= 2305,
+	Prop_Audio_DriverPlaybackMute_Bool						= 2306,
+	Prop_Audio_DriverManagesRecordingVolumeControl_Bool		= 2307,
+	Prop_Audio_DriverRecordingVolume_Float					= 2308,
+	Prop_Audio_DriverRecordingMute_Bool						= 2309,
 
 	// Properties that are unique to TrackedDeviceClass_Controller
 	Prop_AttachedDeviceId_String				= 3000,
@@ -610,7 +621,8 @@ enum ETrackedDeviceProperty
 	Prop_HasCameraComponent_Bool				= 6004,
 	Prop_HasDriverDirectModeComponent_Bool		= 6005,
 	Prop_HasVirtualDisplayComponent_Bool		= 6006,
-	Prop_HasSpatialAnchorsSupport_Bool		    = 6007,
+	Prop_HasSpatialAnchorsSupport_Bool			= 6007,
+	Prop_SupportsXrTextureSets_Bool				= 6008,
 
 	// Properties that are set internally based on other information provided by drivers
 	Prop_ControllerType_String					= 7000,
@@ -870,6 +882,9 @@ enum EVREventType
 
 	VREvent_DashboardThumbChanged			= 535, // Sent when a dashboard thumbnail image changes
 
+	VREvent_DesktopMightBeVisible			= 536, // Sent when any known desktop related overlay is visible
+	VREvent_DesktopMightBeHidden			= 537, // Sent when all known desktop related overlays are hidden
+
 	VREvent_Notification_Shown				= 600,
 	VREvent_Notification_Hidden				= 601,
 	VREvent_Notification_BeginInteraction	= 602,
@@ -990,6 +1005,11 @@ enum EVREventType
 	VREvent_Monitor_ShowHeadsetView			= 2000, // data is process
 	VREvent_Monitor_HideHeadsetView			= 2001, // data is process
 
+	VREvent_Audio_SetSpeakersVolume			= 2100,
+	VREvent_Audio_SetSpeakersMute			= 2101,
+	VREvent_Audio_SetMicrophoneVolume		= 2102,
+	VREvent_Audio_SetMicrophoneMute			= 2103,
+
 	// Vendors are free to expose private events in this reserved region
 	VREvent_VendorSpecific_Reserved_Start	= 10000,
 	VREvent_VendorSpecific_Reserved_End		= 19999,
@@ -1302,6 +1322,16 @@ struct VREvent_HDCPError_t
 	EHDCPError eCode;
 };
 
+struct VREvent_AudioVolumeControl_t
+{
+	float fVolumeLevel;
+};
+
+struct VREvent_AudioMuteControl_t
+{
+	bool bMute;
+};
+
 typedef union
 {
 	VREvent_Reserved_t reserved;
@@ -1333,7 +1363,9 @@ typedef union
 	VREvent_ShowUI_t showUi;
 	VREvent_ShowDevTools_t showDevTools;
 	VREvent_HDCPError_t hdcpError;
-    /** NOTE!!! If you change this you MUST manually update openvr_interop.cs.py */
+	VREvent_AudioVolumeControl_t audioVolumeControl;
+	VREvent_AudioMuteControl_t audioMuteControl;
+	/** NOTE!!! If you change this you MUST manually update openvr_interop.cs.py and openvr_api_flat.h.py */
 } VREvent_Data_t;
 
 
@@ -1865,6 +1897,7 @@ enum EVRInitError
 	VRInitError_Compositor_CannotConnectToDisplayServer							= 497,
 	VRInitError_Compositor_GnomeNoDRMLeasing									= 498,
 	VRInitError_Compositor_FailedToInitializeEncoder							= 499,
+	VRInitError_Compositor_CreateBlurTexture									= 500,
 
 	VRInitError_VendorSpecific_UnableToConnectToOculusRuntime		= 1000,
 	VRInitError_VendorSpecific_WindowsNotInDevMode					= 1001,
@@ -2882,6 +2915,11 @@ namespace vr
 	static const char * const k_pch_SteamVR_UsePrism_Bool = "usePrism";
 	static const char * const k_pch_SteamVR_AllowFallbackMirrorWindowLinux_Bool = "allowFallbackMirrorWindowLinux";
 
+	//-----------------------------------------------------------------------------
+	// openxr keys
+	static const char * const k_pch_OpenXR_Section = "openxr";
+	static const char * const k_pch_OpenXR_MetaUnityPluginCompatibility_Int32 = "metaUnityPluginCompatibility";
+
 	//-----------------------------------------------------------------------------
 	// direct mode keys
 	static const char * const k_pch_DirectMode_Section = "direct_mode";
@@ -3145,12 +3183,16 @@ class IVRChaperone
 	* Tracking space center (0,0,0) is the center of the Play Area. **/
 	virtual bool GetPlayAreaSize( float *pSizeX, float *pSizeZ ) = 0;
 
-	/** Returns the 4 corner positions of the Play Area (formerly named Soft Bounds).
-	* Corners are in counter-clockwise order.
-	* Standing center (0,0,0) is the center of the Play Area.
-	* It's a rectangle.
-	* 2 sides are parallel to the X axis and 2 sides are parallel to the Z axis.
-	* Height of every corner is 0Y (on the floor). **/
+	/** Returns a quad describing the Play Area (formerly named Soft Bounds).
+	 * The corners form a rectangle. 
+	 * Corners are in counter-clockwise order, starting at the front-right.
+	 * The positions are given relative to the standing origin.
+	 * The center of the rectangle is the center of the user's calibrated play space, not necessarily the standing
+	 * origin. 
+	 * The Play Area's forward direction goes from its center through the mid-point of a line drawn between the
+	 * first and second corner. 
+	 * The quad lies on the XZ plane (height = 0y), with 2 sides parallel to the X-axis and two sides parallel
+	 * to the Z-axis of the user's calibrated Play Area. **/
 	virtual bool GetPlayAreaRect( HmdQuad_t *rect ) = 0;
 
 	/** Reload Chaperone data from the .vrchap file on disk. */
@@ -3452,6 +3494,8 @@ class IVRCompositor
 	*	- AlreadySubmitted (app has submitted two left textures or two right textures in a single frame - i.e. before calling WaitGetPoses again)
 	*/
 	virtual EVRCompositorError Submit( EVREye eEye, const Texture_t *pTexture, const VRTextureBounds_t* pBounds = 0, EVRSubmitFlags nSubmitFlags = Submit_Default ) = 0;
+	virtual EVRCompositorError SubmitWithArrayIndex( EVREye eEye, const Texture_t *pTexture, uint32_t unTextureArrayIndex,
+		const VRTextureBounds_t *pBounds = 0, EVRSubmitFlags nSubmitFlags = Submit_Default ) = 0;
 
 	/** Clears the frame that was sent with the last call to Submit. This will cause the
 	* compositor to show the grid until Submit is called again. */
@@ -3631,7 +3675,7 @@ class IVRCompositor
 	virtual EVRCompositorError GetPosesForFrame( uint32_t unPosePredictionID, VR_ARRAY_COUNT( unPoseArrayCount ) TrackedDevicePose_t* pPoseArray, uint32_t unPoseArrayCount ) = 0;
 };
 
-static const char * const IVRCompositor_Version = "IVRCompositor_027";
+static const char * const IVRCompositor_Version = "IVRCompositor_028";
 
 } // namespace vr