Table of Contents

Class XRInterface

Base class for an XR interface implementation.

Inheritance
XRInterface
Derived

Remarks

This class needs to be implemented to make an AR or VR platform available to Godot and these should be implemented as C++ modules or GDExtension modules. Part of the interface is exposed to GDScript 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 XRServer.

See Also

XR documentation index

Properties

ar_is_anchor_detection_enabled

On an AR interface, true if anchor detection is enabled.

var ar_is_anchor_detection_enabled : bool = false

Property Value

bool

Remarks

  • void set_anchor_detection_is_enabled(bool value)
  • bool get_anchor_detection_is_enabled

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.

var environment_blend_mode : int = 0

Property Value

int

Remarks

  • bool set_environment_blend_mode(int mode)
  • int get_environment_blend_mode

interface_is_primary

true if this is the primary interface.

var interface_is_primary : bool = false

Property Value

bool

Remarks

  • void set_primary(bool value)
  • bool is_primary

xr_play_area_mode

The play area mode for this interface.

var xr_play_area_mode : int = 0

Property Value

int

Remarks

  • bool set_play_area_mode(int mode)
  • int get_play_area_mode

Methods

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 CameraServer for this interface.

int get_camera_feed_id

get_capabilities

Qualifiers: const

Returns a combination of Capabilities flags providing information about the capabilities of this interface.

int get_capabilities

get_name

Qualifiers: const

Returns the name of this interface ("OpenXR", "OpenVR", "OpenHMD", "ARKit", etc.).

StringName get_name

get_play_area

Qualifiers: 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.

PackedVector3Array get_play_area

get_projection_for_view(int, float, float, float)

Returns the projection matrix for a view/eye.

Projection get_projection_for_view(int view, float aspect, float near, float far)

Parameters

view int
aspect float
near float
far float

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.

Vector2 get_render_target_size

get_supported_environment_blend_modes

Returns the an array of supported environment blend modes, see EnvironmentBlendMode.

Array get_supported_environment_blend_modes

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.

Dictionary get_system_info

get_tracking_status

Qualifiers: 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.

int get_tracking_status

get_transform_for_view(int, 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 global_transform of the current XROrigin3D.

Transform3D get_transform_for_view(int view, Transform3D cam_transform)

Parameters

view int
cam_transform Transform3D

get_view_count

Returns the number of views that need to be rendered for this device. 1 for Monoscopic, 2 for Stereoscopic.

int get_view_count

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 Godot, such as for mobile VR.

If you do this for a platform that handles its own output (such as OpenVR) Godot will show just one eye without distortion on screen. Alternatively, you can add a separate viewport node 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.

bool initialize

is_initialized

Qualifiers: const

Returns true if this interface has been initialized.

bool is_initialized

is_passthrough_enabled

Returns true if passthrough is enabled.

bool is_passthrough_enabled

is_passthrough_supported

Returns true if this interface supports passthrough.

bool is_passthrough_supported

set_environment_blend_mode(int)

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:

func _ready():
    var xr_interface = XRServer.find_interface("OpenXR")
    if xr_interface and xr_interface.is_initialized():
        var vp = 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


bool set_environment_blend_mode(int mode)

Parameters

mode int

set_play_area_mode(int)

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 XRServer.center_on_hmd (if switching to XRInterface.XR_PLAY_AREA_STAGE) or make the switch during a scene change.

bool set_play_area_mode(int mode)

Parameters

mode int

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.

bool start_passthrough

stop_passthrough

Stops passthrough.

void stop_passthrough

supports_play_area_mode(int)

Call this to find out if a given play area mode is supported by this interface.

bool supports_play_area_mode(int mode)

Parameters

mode int

trigger_haptic_pulse(String, StringName, float, float, float, 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.

void trigger_haptic_pulse(String action_name, StringName tracker_name, float frequency, float amplitude, float duration_sec, float delay_sec)

Parameters

action_name String
tracker_name StringName
frequency float
amplitude float
duration_sec float
delay_sec float

uninitialize

Turns the interface off.

void uninitialize

Events

play_area_changed(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.

signal play_area_changed(int mode)

Parameters

mode int