From d7d171c45c31a53b06ea319928cf1434460f97cf Mon Sep 17 00:00:00 2001
From: Ron Bessems <rbessems@magicleap.com>
Date: Thu, 2 Feb 2023 09:14:16 -0500
Subject: Add XR Environment Blend Mode Support

---
 doc/classes/XRInterface.xml | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

(limited to 'doc')

diff --git a/doc/classes/XRInterface.xml b/doc/classes/XRInterface.xml
index 05d5eb6673..db65ce62f2 100644
--- a/doc/classes/XRInterface.xml
+++ b/doc/classes/XRInterface.xml
@@ -51,6 +51,12 @@
 				Returns the resolution at which we should render our intermediate results before things like lens distortion are applied by the VR platform.
 			</description>
 		</method>
+		<method name="get_supported_environment_blend_modes">
+			<return type="Array" />
+			<description>
+				Returns the an array of supported environment blend modes, see [enum XRInterface.EnvironmentBlendMode].
+			</description>
+		</method>
 		<method name="get_tracking_status" qualifiers="const">
 			<return type="int" enum="XRInterface.TrackingStatus" />
 			<description>
@@ -101,6 +107,28 @@
 				Is [code]true[/code] if this interface supports passthrough.
 			</description>
 		</method>
+		<method name="set_environment_blend_mode">
+			<return type="bool" />
+			<param index="0" name="mode" type="int" enum="XRInterface.EnvironmentBlendMode" />
+			<description>
+				Sets the active environment blend mode.
+				[param mode] is the [enum XRInterface.EnvironmentBlendMode] starting with the next frame.
+				[b]Note:[/b] Not all runtimes support all environment blend modes, so it is important to check this at startup. For example:
+				[codeblock]
+				                func _ready():
+				                    var xr_interface : XRInterface = XRServer.find_interface("OpenXR")
+				                    if xr_interface and xr_interface.is_initialized():
+				                        var vp : Viewport = get_viewport()
+				                        vp.use_xr = true
+				                        var acceptable_modes = [ XRInterface.XR_ENV_BLEND_MODE_OPAQUE, XRInterface.XR_ENV_BLEND_MODE_ADDITIVE ]
+				                        var modes = xr_interface.get_supported_environment_blend_modes()
+				                        for mode in acceptable_modes:
+				                            if mode in modes:
+				                                xr_interface.set_environment_blend_mode(mode)
+				                                break
+				[/codeblock]
+			</description>
+		</method>
 		<method name="set_play_area_mode">
 			<return type="bool" />
 			<param index="0" name="mode" type="int" enum="XRInterface.PlayAreaMode" />
@@ -220,5 +248,14 @@
 		<constant name="XR_PLAY_AREA_STAGE" value="4" enum="PlayAreaMode">
 			Same as roomscale but origin point is fixed to the center of the physical space, XRServer.center_on_hmd disabled.
 		</constant>
+		<constant name="XR_ENV_BLEND_MODE_OPAQUE" value="0" enum="EnvironmentBlendMode">
+			Opaque blend mode. This is typically used for VR devices.
+		</constant>
+		<constant name="XR_ENV_BLEND_MODE_ADDITIVE" value="1" enum="EnvironmentBlendMode">
+			Additive blend mode. This is typically used for AR devices or VR devices with passthrough.
+		</constant>
+		<constant name="XR_ENV_BLEND_MODE_ALPHA_BLEND" value="2" enum="EnvironmentBlendMode">
+			Alpha blend mode. This is typically used for AR or VR devices with passthrough capabilities. The alpha channel controls how much of the passthrough is visible. Alpha of 0.0 means the passthrough is visible and this pixel works in ADDITIVE mode. Alpha of 1.0 means that the passthrough is not visible and this pixel works in OPAQUE mode.
+		</constant>
 	</constants>
 </class>
-- 
cgit v1.2.3