Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

XRInterface

继承: RefCounted < Object

派生: MobileVRInterface, OpenXRInterface, WebXRInterface, XRInterfaceExtension

XR 接口实现的基类。

描述

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

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

教程

属性

bool

ar_is_anchor_detection_enabled

false

EnvironmentBlendMode

environment_blend_mode

0

bool

interface_is_primary

false

PlayAreaMode

xr_play_area_mode

0

方法

int

get_camera_feed_id()

int

get_capabilities() const

StringName

get_name() const

PackedVector3Array

get_play_area() const

Projection

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

Vector2

get_render_target_size()

Array

get_supported_environment_blend_modes()

Dictionary

get_system_info()

TrackingStatus

get_tracking_status() const

Transform3D

get_transform_for_view(view: int, cam_transform: Transform3D)

int

get_view_count()

bool

initialize()

bool

is_initialized() const

bool

is_passthrough_enabled()

bool

is_passthrough_supported()

bool

set_environment_blend_mode(mode: EnvironmentBlendMode)

bool

set_play_area_mode(mode: PlayAreaMode)

bool

start_passthrough()

void

stop_passthrough()

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)

void

uninitialize()


信号

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 🔗

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


bool interface_is_primary = false 🔗

  • void set_primary(value: bool)

  • bool is_primary()

true 如果这是个主接口。


PlayAreaMode xr_play_area_mode = 0 🔗

该接口的游玩区域模式。


方法说明

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。接口应该返回 XRRuntimeNameXRRuntimeVersion,表示所使用的 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) 🔗

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: 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) 🔗

在与该接口相关联的设备上触发一次触觉脉冲。

action_name 是该脉冲的动作名称。

tracker_name 是可选的,可用于将脉冲引导至特定设备,前提是该设备被绑定到此触觉。


void uninitialize() 🔗

关闭接口。