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

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


bool interface_is_primary = false

  • void set_primary ( bool value )

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

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

  1. func _ready():
  2. var xr_interface: XRInterface = XRServer.find_interface("OpenXR")
  3. if xr_interface and xr_interface.is_initialized():
  4. var vp: Viewport = get_viewport()
  5. vp.use_xr = true
  6. var acceptable_modes = [ XRInterface.XR_ENV_BLEND_MODE_OPAQUE, XRInterface.XR_ENV_BLEND_MODE_ADDITIVE ]
  7. var modes = xr_interface.get_supported_environment_blend_modes()
  8. for mode in acceptable_modes:
  9. if mode in modes:
  10. xr_interface.set_environment_blend_mode(mode)
  11. 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 ( )

关闭接口。

Previous Next


© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.