XRInterface
Inherited by: MobileVRInterface, OpenXRInterface
Base class for an XR interface implementation.
Description
Section titled “Description”This class needs to be implemented to make an AR or VR platform available to Gobu and these should be implemented as C++ modules or NativeExtension modules. Part of the interface is exposed to Grost so you can detect, enable and configure an AR or VR platform.
Interfaces should be written in such a way that simply enabling them will give us a working setup. You can query the available interfaces through XR.
Properties
Section titled “Properties”| Type | Name | Default |
|---|---|---|
| bool | ar_is_anchor_detection_enabled | false |
| XRInterface.EnvironmentBlendMode | environment_blend_mode | 0 |
| bool | interface_is_primary | false |
| XRInterface.PlayAreaMode | xr_play_area_mode | 1 |
Methods
Section titled “Methods”| Returns | Method |
|---|---|
| int | get_camera_feed_id() |
| int | get_capabilities() |
| StringName | get_name() |
[]Vector3 | get_play_area() |
| Projection | get_projection_for_view(view, aspect, near, far) |
| Vector2 | get_render_target_size() |
| Array | get_supported_environment_blend_modes() |
| Dictionary | get_system_info() |
| XRInterface.TrackingStatus | get_tracking_status() |
| Transform3D | get_transform_for_view(view, cam_transform) |
| int | get_view_count() |
| bool | initialize() |
| bool | is_initialized() |
| bool | is_passthrough_enabled() |
| bool | is_passthrough_supported() |
| bool | set_environment_blend_mode(mode) |
| bool | set_play_area_mode(mode) |
| bool | start_passthrough() |
| void | stop_passthrough() |
| bool | supports_play_area_mode(mode) |
| void | trigger_haptic_pulse(action_name, tracker_name, frequency, amplitude, duration_sec, delay_sec) |
| void | uninitialize() |
Signals
Section titled “Signals”play_area_changed
Section titled “play_area_changed”play_area_changed(mode: int)Emitted when the play area is changed. This can be a result of the player resetting the boundary or entering a new play area, the player changing the play area mode, the world scale changing or the player resetting their headset orientation.
Enumerations and constants
Section titled “Enumerations and constants”enum Capabilities
Section titled “enum Capabilities”- XR_NONE =
0— No XR capabilities.
- XR_MONO =
1— This interface can work with normal rendering output (non-HMD based AR).
- XR_STEREO =
2— This interface supports stereoscopic rendering.
- XR_QUAD =
4— This interface supports quad rendering (not yet supported by Gobu).
- XR_VR =
8— This interface supports VR.
- XR_AR =
16— This interface supports AR (video background and real world tracking).
- XR_EXTERNAL =
32— This interface outputs to an external device. If the main viewport is used, the on screen output is an unmodified buffer of either the left or right eye (stretched if the viewport size is not changed to the same aspect ratio ofget_render_target_size()). Using a separate viewport actor frees up the main viewport for other purposes.
enum TrackingStatus
Section titled “enum TrackingStatus”- XR_NORMAL_TRACKING =
0— Tracking is behaving as expected.
- XR_EXCESSIVE_MOTION =
1— Tracking is hindered by excessive motion (the player is moving faster than tracking can keep up).
- XR_INSUFFICIENT_FEATURES =
2— Tracking is hindered by insufficient features, it’s too dark (for camera-based tracking), player is blocked, etc.
- XR_UNKNOWN_TRACKING =
3— We don’t know the status of the tracking or this interface does not provide feedback.
- XR_NOT_TRACKING =
4— Tracking is not functional (camera not plugged in or obscured, lighthouses turned off, etc.).
enum PlayAreaMode
Section titled “enum PlayAreaMode”- XR_PLAY_AREA_UNKNOWN =
0— Play area mode not set or not available.
- XR_PLAY_AREA_3DOF =
1— Play area only supports orientation tracking, no positional tracking, area will center around player.
- XR_PLAY_AREA_SITTING =
2— Player is in seated position, limited positional tracking, fixed guardian around player.
- XR_PLAY_AREA_ROOMSCALE =
3— Player is free to move around, full positional tracking.
- XR_PLAY_AREA_STAGE =
4— Same asXR_PLAY_AREA_ROOMSCALEbut origin point is fixed to the center of the physical space. In this mode, system-level recentering may be disabled, requiring the use ofXR.center_on_hmd().
- XR_PLAY_AREA_CUSTOM =
2147483647— Custom play area set by a NativeExtension.
enum EnvironmentBlendMode
Section titled “enum EnvironmentBlendMode”- XR_ENV_BLEND_MODE_OPAQUE =
0— Opaque blend mode. This is typically used for VR devices.
- XR_ENV_BLEND_MODE_ADDITIVE =
1— Additive blend mode. This is typically used for AR devices or VR devices with passthrough.
- XR_ENV_BLEND_MODE_ALPHA_BLEND =
2— 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.
enum VRSTextureFormat
Section titled “enum VRSTextureFormat”- XR_VRS_TEXTURE_FORMAT_UNIFIED =
0— The texture format is the same as returned byXRVRS.make_vrs_texture().
- XR_VRS_TEXTURE_FORMAT_FRAGMENT_SHADING_RATE =
1— The texture format is the same as expected by the VulkanVK_KHR_fragment_shading_rateextension.
- XR_VRS_TEXTURE_FORMAT_FRAGMENT_DENSITY_MAP =
2— The texture format is the same as expected by the VulkanVK_EXT_fragment_density_mapextension.
Property descriptions
Section titled “Property descriptions”ar_is_anchor_detection_enabled
Section titled “ar_is_anchor_detection_enabled”bool ar_is_anchor_detection_enabled = false
Setter/getter: set_anchor_detection_is_enabled(), get_anchor_detection_is_enabled()
On an AR interface, true if anchor detection is enabled.
environment_blend_mode
Section titled “environment_blend_mode”XRInterface.EnvironmentBlendMode environment_blend_mode = 0
Setter/getter: set_environment_blend_mode(), get_environment_blend_mode()
Specify how XR should blend in the environment. This is specific to certain AR and passthrough devices where camera images are blended in by the XR compositor.
interface_is_primary
Section titled “interface_is_primary”bool interface_is_primary = false
Setter/getter: set_primary(), is_primary()
true if this is the primary interface.
xr_play_area_mode
Section titled “xr_play_area_mode”XRInterface.PlayAreaMode xr_play_area_mode = 1
Setter/getter: set_play_area_mode(), get_play_area_mode()
The play area mode for this interface.
Method descriptions
Section titled “Method descriptions”get_camera_feed_id
Section titled “get_camera_feed_id”int get_camera_feed_id()
If this is an AR interface that requires displaying a camera feed as the background, this method returns the feed ID in the CameraDevices for this interface.
get_capabilities
Section titled “get_capabilities”int get_capabilities() const
Returns a combination of Capabilities flags providing information about the capabilities of this interface.
get_name
Section titled “get_name”StringName get_name() const
Returns the name of this interface ("OpenXR", "OpenVR", "OpenHMD", "ARKit", etc.).
get_play_area
Section titled “get_play_area”[]Vector3 get_play_area() const
Returns an array of vectors that represent the physical play area mapped to the virtual space around the XROrigin3D point. The points form a convex polygon that can be used to react to or visualize the play area. This returns an empty array if this feature is not supported or if the information is not yet available.
get_projection_for_view
Section titled “get_projection_for_view”Projection get_projection_for_view(view: int, aspect: float, near: float, far: float)
Returns the projection matrix for a view/eye.
get_render_target_size
Section titled “get_render_target_size”Vector2 get_render_target_size()
Returns the resolution at which we should render our intermediate results before things like lens distortion are applied by the VR platform.
get_supported_environment_blend_modes
Section titled “get_supported_environment_blend_modes”Array get_supported_environment_blend_modes()
Returns the an array of supported environment blend modes, see EnvironmentBlendMode.
get_system_info
Section titled “get_system_info”Dictionary get_system_info()
Returns a Dictionary with extra system info. Interfaces are expected to return XRRuntimeName and XRRuntimeVersion providing info about the used XR runtime. Additional entries may be provided specific to an interface.
**Note:**This information may only be available after initialize() was successfully called.
get_tracking_status
Section titled “get_tracking_status”XRInterface.TrackingStatus get_tracking_status() const
If supported, returns the status of our tracking. This will allow you to provide feedback to the user whether there are issues with positional tracking.
get_transform_for_view
Section titled “get_transform_for_view”Transform3D get_transform_for_view(view: int, cam_transform: Transform3D)
Returns the transform for a view/eye.
view is the view/eye index.
cam_transform is the transform that maps device coordinates to scene coordinates, typically the Spatial3D.global_transform of the current XROrigin3D.
get_view_count
Section titled “get_view_count”int get_view_count()
Returns the number of views that need to be rendered for this device. 1 for Monoscopic, 2 for Stereoscopic.
initialize
Section titled “initialize”bool initialize()
Call this to initialize this interface. The first interface that is initialized is identified as the primary interface and it will be used for rendering output.
After initializing the interface you want to use you then need to enable the AR/VR mode of a viewport and rendering should commence.
Note: You must enable the XR mode on the main viewport for any device that uses the main output of Gobu, such as for mobile VR.
If you do this for a platform that handles its own output (such as OpenVR) Gobu will show just one eye without distortion on screen. Alternatively, you can add a separate viewport actor to your scene and enable AR/VR on that viewport. It will be used to output to the HMD, leaving you free to do anything you like in the main window, such as using a separate camera as a spectator camera or rendering something completely different.
While currently not used, you can activate additional interfaces. You may wish to do this if you want to track controllers from other platforms. However, at this point in time only one interface can render to an HMD.
is_initialized
Section titled “is_initialized”bool is_initialized() const
Returns true if this interface has been initialized.
is_passthrough_enabled
Section titled “is_passthrough_enabled”bool is_passthrough_enabled()
Returns true if passthrough is enabled.
is_passthrough_supported
Section titled “is_passthrough_supported”bool is_passthrough_supported()
Returns true if this interface supports passthrough.
set_environment_blend_mode
Section titled “set_environment_blend_mode”bool set_environment_blend_mode(mode: XRInterface.EnvironmentBlendMode)
Sets the active environment blend mode.
mode is the environment blend mode starting with the next frame.
Note: Not all runtimes support all environment blend modes, so it is important to check this at startup. For example:
fn _ready() { if xr_interface := XR.find_interface("OpenXR"), xr_interface.is_initialized() { vp : Viewport = get_viewport() vp.use_xr = true acceptable_modes : []int = [XRInterface.XR_ENV_BLEND_MODE_OPAQUE, XRInterface.XR_ENV_BLEND_MODE_ADDITIVE] modes : Array = xr_interface.get_supported_environment_blend_modes() for mode : int in acceptable_modes { if mode in modes { xr_interface.set_environment_blend_mode(mode) break } } }}set_play_area_mode
Section titled “set_play_area_mode”bool set_play_area_mode(mode: XRInterface.PlayAreaMode)
Sets the active play area mode, will return false if the mode can’t be used with this interface.
Note: Changing this after the interface has already been initialized can be jarring for the player, so it’s recommended to recenter on the HMD with XR.center_on_hmd() (if switching to XR_PLAY_AREA_STAGE) or make the switch during a scene change.
start_passthrough
Section titled “start_passthrough”bool start_passthrough()
Starts passthrough, will return false if passthrough couldn’t be started.
Note: The viewport used for XR must have a transparent background, otherwise passthrough may not properly render.
stop_passthrough
Section titled “stop_passthrough”void stop_passthrough()
Stops passthrough.
supports_play_area_mode
Section titled “supports_play_area_mode”bool supports_play_area_mode(mode: XRInterface.PlayAreaMode)
Call this to find out if a given play area mode is supported by this interface.
trigger_haptic_pulse
Section titled “trigger_haptic_pulse”void trigger_haptic_pulse(action_name: String, tracker_name: StringName, frequency: float, amplitude: float, duration_sec: float, delay_sec: float)
Triggers a haptic pulse on a device associated with this interface.
action_name is the name of the action for this pulse.
tracker_name is optional and can be used to direct the pulse to a specific device provided that device is bound to this haptic.
frequency is the frequency of the pulse, set to 0.0 to have the system use a default frequency.
amplitude is the amplitude of the pulse between 0.0 and 1.0.
duration_sec is the duration of the pulse in seconds.
delay_sec is a delay in seconds before the pulse is given.
uninitialize
Section titled “uninitialize”void uninitialize()
Turns the interface off.