XRInterface

继承： RefCounted < Object

派生： MobileVRInterface, OpenXRInterface, WebXRInterface, XRInterfaceExtension

XR 接口实现的基类。

描述

需要实现该类以使 Godot 可以使用 AR 或 VR 平台，并且这些应作为 C++ 模块或 GDExtension 模块实现。部分接口公开给 GDScript，因此可以检测、启用和配置 AR 或 VR 平台。

接口应该以这样一种方式编写，只要简单地启用它们就会提供一个工作设置。可以通过 XRServer 查询可用的接口。

教程

• XR 文档索引

属性

方法

信号

play_area_changed(mode: int) 🔗

当游玩区域改变时发出。这可能是玩家重置边界、进入新的游玩区域、更改游玩区域模式、重置其头戴式设备方向，或者世界比例改变的结果。

枚举

enum Capabilities: 🔗

Capabilities XR_NONE = 0

没有 XR 功能。

Capabilities XR_MONO = 1

此接口可以与正常的渲染输出一起工作（非基于 HMD 的 AR）。

Capabilities XR_STEREO = 2

该接口支持立体渲染。

Capabilities XR_QUAD = 4

该接口支持四边形渲染（Godot 尚不支持）。

Capabilities XR_VR = 8

该接口支持 VR。

Capabilities XR_AR = 16

该接口支持 AR（视频背景和真实世界跟踪）。

Capabilities XR_EXTERNAL = 32

该接口输出至外部设备。如果使用的是主视口，则屏幕上的输出是未经修改的左眼或右眼缓冲区（如果视口大小未更改至与 get_render_target_size 相同的纵横比，则会进行拉伸）。使用单独的视口节点能够将主视口让出来做别的事情。

enum TrackingStatus: 🔗

TrackingStatus XR_NORMAL_TRACKING = 0

追踪行为符合预期。

TrackingStatus XR_EXCESSIVE_MOTION = 1

过度运动会阻碍追踪（玩家的移动速度大于追踪的速度）。

TrackingStatus XR_INSUFFICIENT_FEATURES = 2

跟踪受到功能不足的阻碍，太暗（对于基于相机的跟踪），玩家被阻碍等。

TrackingStatus XR_UNKNOWN_TRACKING = 3

我们不知道跟踪的状态，或者这个接口未提供反馈。

TrackingStatus XR_NOT_TRACKING = 4

追踪功能失效（相机未插电或被遮挡、灯塔关闭，等等）。

enum PlayAreaMode: 🔗

PlayAreaMode XR_PLAY_AREA_UNKNOWN = 0

游玩区域模式未设置或不可用。

PlayAreaMode XR_PLAY_AREA_3DOF = 1

游玩区域仅支持方向跟踪，不支持位置跟踪，区域以玩家为中心。

PlayAreaMode XR_PLAY_AREA_SITTING = 2

玩家处于坐姿，提供有限的位置跟踪，玩家周围有固定的防护。

PlayAreaMode XR_PLAY_AREA_ROOMSCALE = 3

玩家可以自由移动，提供完整的位置跟踪。

PlayAreaMode XR_PLAY_AREA_STAGE = 4

与 XR_PLAY_AREA_ROOMSCALE 相同，但是原点固定在物理空间的中心。在这个模式下，可能会禁用通过 XRServer.center_on_hmd 进行的系统级别的中心重定位。

enum EnvironmentBlendMode: 🔗

EnvironmentBlendMode XR_ENV_BLEND_MODE_OPAQUE = 0

不透明混合模式。通常用于 VR 设备。

EnvironmentBlendMode XR_ENV_BLEND_MODE_ADDITIVE = 1

加法混合模式。通常用于带有穿透功能的 AR 或 VR 设备。

EnvironmentBlendMode XR_ENV_BLEND_MODE_ALPHA_BLEND = 2

Alpha 混合模式。通常用于带有穿透功能的 AR 或 VR 设备。Alpha 通道控制穿透的可见程度。Alpha 为 0.0 表示穿透可见、该像素处于加法模式。Alpha 为 1.0 表示穿透不可见，该像素处于不透明模式。

属性说明

bool ar_is_anchor_detection_enabled = false 🔗

• void set_anchor_detection_is_enabled(value: bool)

• bool get_anchor_detection_is_enabled()

在 AR 接口上，如果启用锚点检测，则为 true。

EnvironmentBlendMode environment_blend_mode = 0 🔗

• bool set_environment_blend_mode(mode: EnvironmentBlendMode)

• EnvironmentBlendMode get_environment_blend_mode()

指定 XR 应如何融入环境。这是特定于某些 AR 和直通设备的，其中相机图像由 XR 合成器混合。

bool interface_is_primary = false 🔗

• void set_primary(value: bool)

• bool is_primary()

true 如果这是个主接口。

PlayAreaMode xr_play_area_mode = 0 🔗

• bool set_play_area_mode(mode: PlayAreaMode)

• PlayAreaMode get_play_area_mode()

该接口的游玩区域模式。

方法说明

int get_camera_feed_id() 🔗

如果该 AR 接口要求将相机画面作为背景显示，那么该方法就会返回该接口 CameraServer 的画面 ID。

int get_capabilities() const 🔗

返回 Capabilities 标签的组合，提供关于这个接口功能的信息。

StringName get_name() const 🔗

返回该接口的名称（"OpenXR"、"OpenVR"、"OpenHMD"、"ARKit" 等）。

PackedVector3Array get_play_area() const 🔗

返回一个向量数组，表示映射到 XROrigin3D 点周围的虚拟空间的物理游玩区域。这些点形成一个凸多边形，可被用于对游玩区域做出反应或可视化。如果该功能不受支持或信息尚不可用，则返回一个空数组。

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

返回视图/眼睛的投影矩阵。

Vector2 get_render_target_size() 🔗

返回在VR平台应用镜头失真等内容之前渲染的中间结果的分辨率。

Array get_supported_environment_blend_modes() 🔗

返回支持的环境混合模式数组，见 EnvironmentBlendMode。

Dictionary get_system_info() 🔗

返回包含额外系统信息的 Dictionary。接口应该返回 XRRuntimeName 和 XRRuntimeVersion，表示所使用的 XR 运行时信息。还可以额外提供关于特定接口的条目。

注意：这个信息可能只在成功调用 initialize 后可用。

TrackingStatus get_tracking_status() const 🔗

如果支持，返回我们的跟踪状态。这将使你能够向用户反馈，是否存在位置跟踪的问题。

Transform3D get_transform_for_view(view: int, cam_transform: Transform3D) 🔗

返回视图/眼睛的变换。

view 是视图/眼睛的索引。

cam_transform 是将设备坐标映射至场景坐标的变换，通常是当前 XROrigin3D 的 Node3D.global_transform。

int get_view_count() 🔗

返回该设备渲染所需的视图数量。1 代表单目平面视图，2 代表双目立体视图。

bool initialize() 🔗

调用它来初始化这个接口。被初始化的第一个接口被识别为主接口，它将用于渲染输出。

初始化想要使用的接口后，需要启用视口的 AR/VR 模式，并且渲染应该开始。

注意：对于任何使用 Godot 主输出的设备，例如移动 VR，必须在主视口上启用 XR 模式。

如果为处理自己输出的平台（例如 OpenVR）执行该操作，则 Godot 将只显示一只眼睛而不会在屏幕上失真。或者，可以将单独的视口节点添加到场景并在该视口上启用 AR/VR。它将被用于输出到 HMD，让你可以在主窗口中自由地做任何你喜欢的事情，例如使用单独的相机作为旁观者相机或渲染完全不同的东西。

虽然当前未使用，但可以激活其他接口。如果想跟踪来自其他平台的控制器，可能会希望这样做。但是，此时只有一个接口可以渲染到 HMD。

bool is_initialized() const 🔗

如果这个接口已初始化，则返回 true。

bool is_passthrough_enabled() 🔗

已弃用： Check if environment_blend_mode is XR_ENV_BLEND_MODE_ALPHA_BLEND, instead.

如果已启用穿透，则返回 true。

bool is_passthrough_supported() 🔗

已弃用： Check that XR_ENV_BLEND_MODE_ALPHA_BLEND is supported using get_supported_environment_blend_modes, instead.

如果该接口支持穿透，则返回 true。

bool set_environment_blend_mode(mode: EnvironmentBlendMode) 🔗

设置活动的环境混合模式。

mode 是从下一帧开始的环境混合模式。

注意：并非所有运行时都支持全部的环境混合模式，因此在启动时检查这一点很重要。例如：

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

bool set_play_area_mode(mode: PlayAreaMode) 🔗

设置活动的游玩区域模式，如果该模式不能与该接口一起使用，将返回 false。

注意：在接口初始化后更改该设置可能会让玩家感到不舒服，因此建议使用 XRServer.center_on_hmd 在 HMD 上重新居中（如果切换到 XR_PLAY_AREA_STAGE）或在场景改变时进行切换。

bool start_passthrough() 🔗

已弃用： Set the environment_blend_mode to XR_ENV_BLEND_MODE_ALPHA_BLEND, instead.

启动穿透，如果无法启动则会返回 false。

注意：XR 所使用的视口必须有透明背景，否则穿透可能无法正确渲染。

void stop_passthrough() 🔗

已弃用： Set the environment_blend_mode to XR_ENV_BLEND_MODE_OPAQUE, instead.

停止穿透。

bool supports_play_area_mode(mode: PlayAreaMode) 🔗

请调用这个方法来查询此接口是否支持给定的游玩区域模式。

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.

void uninitialize() 🔗

关闭接口。