Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

XRInterface¶

继承： RefCounted < Object

派生： MobileVRInterface, OpenXRInterface, WebXRInterface, XRInterfaceExtension

XR 接口实现的基类。

描述¶

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

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

教程¶

XR 文档索引

属性¶

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 ( int view, float aspect, float near, float far )
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 ( int view, Transform3D cam_transform )
int	get_view_count ( )
bool	initialize ( )
bool	is_initialized ( ) const
bool	is_passthrough_enabled ( )
bool	is_passthrough_supported ( )
bool	set_environment_blend_mode ( EnvironmentBlendMode mode )
bool	set_play_area_mode ( PlayAreaMode mode )
bool	start_passthrough ( )
void	stop_passthrough ( )
bool	supports_play_area_mode ( PlayAreaMode mode )
void	trigger_haptic_pulse ( String action_name, StringName tracker_name, float frequency, float amplitude, float duration_sec, float delay_sec )
void	uninitialize ( )

信号¶

play_area_changed ( int mode )

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

枚举¶

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 ( bool value )
bool get_anchor_detection_is_enabled ( )

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

EnvironmentBlendMode environment_blend_mode = 0

bool set_environment_blend_mode ( EnvironmentBlendMode mode )
EnvironmentBlendMode get_environment_blend_mode ( )

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

bool interface_is_primary = false

void set_primary ( bool value )
bool is_primary ( )

true 如果这是个主接口。

PlayAreaMode xr_play_area_mode = 0

bool set_play_area_mode ( PlayAreaMode mode )
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 ( int view, float aspect, float near, float far )

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

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 ( int view, Transform3D cam_transform )

返回视图/眼睛的变换。

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 ( )

如果已启用穿透，则为 true。

bool is_passthrough_supported ( )

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

bool set_environment_blend_mode ( EnvironmentBlendMode mode )

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

mode 是从下一帧开始的 EnvironmentBlendMode。

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

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 ( PlayAreaMode mode )

设置活动的游玩区域模式，如果该模式无法在这个接口中使用则返回 false。

bool start_passthrough ( )

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

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

void stop_passthrough ( )

停止穿透。

bool supports_play_area_mode ( PlayAreaMode mode )

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

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

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

action_name 是该脉冲的动作名称。

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

void uninitialize ( )

关闭接口。