Base class for an XR interface implementation.
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.
get_capabilities ( ) const
get_name ( ) const
get_play_area ( ) const
get_tracking_status ( ) const
get_view_count ( )
initialize ( )
is_initialized ( ) const
stop_passthrough ( )
uninitialize ( )
play_area_changed ( int mode )
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.
Capabilities XR_NONE =
No XR capabilities.
Capabilities XR_MONO =
This interface can work with normal rendering output (non-HMD based AR).
Capabilities XR_STEREO =
This interface supports stereoscopic rendering.
Capabilities XR_QUAD =
This interface supports quad rendering (not yet supported by Godot).
Capabilities XR_VR =
this interface supports VR.
Capabilities XR_AR =
This interface supports AR (video background and real world tracking).
Capabilities XR_EXTERNAL =
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 of get_render_target_size). Using a separate viewport node frees up the main viewport for other purposes.
TrackingStatus XR_NORMAL_TRACKING =
Tracking is behaving as expected.
TrackingStatus XR_EXCESSIVE_MOTION =
Tracking is hindered by excessive motion (the player is moving faster than tracking can keep up).
TrackingStatus XR_INSUFFICIENT_FEATURES =
Tracking is hindered by insufficient features, it's too dark (for camera-based tracking), player is blocked, etc.
TrackingStatus XR_UNKNOWN_TRACKING =
We don't know the status of the tracking or this interface does not provide feedback.
TrackingStatus XR_NOT_TRACKING =
Tracking is not functional (camera not plugged in or obscured, lighthouses turned off, etc.).
PlayAreaMode XR_PLAY_AREA_UNKNOWN =
Play area mode not set or not available.
PlayAreaMode XR_PLAY_AREA_3DOF =
Play area only supports orientation tracking, no positional tracking, area will center around player.
PlayAreaMode XR_PLAY_AREA_SITTING =
Player is in seated position, limited positional tracking, fixed guardian around player.
PlayAreaMode XR_PLAY_AREA_ROOMSCALE =
Player is free to move around, full positional tracking.
PlayAreaMode XR_PLAY_AREA_STAGE =
Same as roomscale but origin point is fixed to the center of the physical space, XRServer.center_on_hmd disabled.
bool ar_is_anchor_detection_enabled =
On an AR interface,
true if anchor detection is enabled.
bool interface_is_primary =
true if this is the primary interface.
PlayAreaMode xr_play_area_mode =
The play area mode for this interface.
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 CameraServer for this interface.
int get_capabilities ( ) const
Returns a combination of Capabilities flags providing information about the capabilities of this interface.
StringName get_name ( ) const
Returns the name of this interface (OpenXR, OpenVR, OpenHMD, ARKit, etc).
PackedVector3Array get_play_area ( ) const
Returns an array of vectors that denotes 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.
Returns the projection matrix for a view/eye.
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.
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.
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.
int get_view_count ( )
Returns the number of views that need to be rendered for this device. 1 for Monoscopic, 2 for Stereoscopic.
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 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 is_initialized ( ) const
true if this interface has been initialized.
bool is_passthrough_enabled ( )
true if passthrough is enabled.
bool is_passthrough_supported ( )
true if this interface supports passthrough.
Sets the active play area mode, will return
false if the mode can't be used with this interface.
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.
void stop_passthrough ( )
Call this to find out if a given play area mode is supported by this interface.
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.
void uninitialize ( )
Turns the interface off.