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.

Checking the stable version of the documentation...

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

关闭接口。