XrView QML Type

为 Xr 应用程序设置视图。更多...

此类型处于技术预览阶段，可能会有变动。

• 所有成员列表（包括继承的成员）

属性

• depthSubmissionEnabled : bool
• environment : SceneEnvironment
• fixedFoveation : enumeration
• isQuitOnSessionEndEnabled : bool
• multiViewRenderingEnabled : bool
• multiViewRenderingSupported : bool
• passthroughEnabled : bool
• passthroughSupported : bool
• referenceSpace : enumeration
• renderStats : RenderStats
• runtimeInfo : QQuick3DXrRuntimeInfo
• xrOrigin : XrOrigin

信号

• initializeFailed(const QString &errorString)
• sessionEnded()

方法

• pickResult closestPointPick(vector3d origin, float radius, Model model) (since 6.11)
• vector3d processTouch(vector3d position, int pointId)
• pickResult rayPick(vector3d origin, vector3d direction)
• pickResult rayPick(vector3d origin, vector3d direction, Model model) (since 6.11)
• List<pickResult> rayPickAll(vector3d origin, vector3d direction)
• void setTouchpoint(Item target, point position, int pointId, bool pressed)
• object touchpointState(int pointId)

详细说明

XrView 用于为 XR 应用程序设置视图。以下代码片段摘自Qt Quick 3D 中的“Xr Simple Example”，展示了如何使用该类型。

// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

import QtQuick
import QtQuick.Layouts
//! [XrView]
import QtQuick3D
import QtQuick3D.Xr

XrView {
    id: xrView
    XrErrorDialog { id: err }
    onInitializeFailed: (errorString) => err.run("XRView", errorString)
    referenceSpace: XrView.ReferenceSpaceLocalFloor
//! [XrView]

    environment: SceneEnvironment {
        clearColor: "black"
        backgroundMode: SceneEnvironment.Color
    }

平台说明

Meta Quest 设备

要将应用发布到enable passthrough ，您需要在应用的AndroidManifest.xml 文件中添加以下权限：

<uses-feature android:name="com.oculus.feature.PASSTHROUGH" android:required="false"/>

属性文档

depthSubmissionEnabled : bool [default: false]

控制是否启用将深度缓冲区提交给 XR 合成器的功能。

默认情况下，XrView 中3D场景使用的深度缓冲区不会暴露给XR合成器。但在某些平台上，深度缓冲区的提交是隐式的，应用程序无法禁用或控制该行为。VisionOS就是其中一个例子。在这些平台上，更改此属性不会产生任何效果。 在其他平台（特别是 OpenXR）上，该功能的支持情况取决于运行时使用的 OpenXR 实现。

将 depthSubmissionEnabled 设置为true 总是安全的。仅当底层栈不支持时，该设置才不会产生效果。为确保万无一失，您可以检查调试输出以确认是否正在使用深度提交。提交深度缓冲区可能会改善 XR 合成器执行的重新投影效果。 例如，当系统无法维持目标帧率时，可能会进行重投影：此时系统不得不通过预测帧内容来改善并稳定用户对场景的感知，从而减轻可能出现的晕动症。 然而，应用程序和 Qt 无法控制数据的使用方式。也可能出现提交深度数据毫无实际效果，并被底层 XR 运行时和合成器忽略的情况。

实际上，提交深度缓冲区意味着将渲染结果写入由 XR 运行时提供的深度纹理，而非由 Qt 创建和管理的 intermediate texture/渲染缓冲区。将渲染结果写入深度纹理会产生某些底层影响，可能对性能造成影响：

在使用多重采样抗锯齿（multisample antialiasing ，MSAA）时，启用深度提交意味着渲染到多采样深度纹理中，并将其采样解析为 XR 运行时提供的非多采样深度纹理。如果不进行深度提交，则无需执行该解析步骤。 此外，某些 3D API 不支持解析多采样深度-模板数据（详情请参阅QRhi::ResolveDepthStencil 标志）。如果没有此支持，尝试在启用 MSAA 的同时启用深度提交将被优雅地忽略。

即使未使用 MSAA，启用深度提交也会触发通过具有此控制功能的 3D API 写出深度数据。 Qt 通常会将深度/模板数据的存储操作标记为非必需，这在分块式 GPU 架构上可能对性能产生积极影响。但深度提交不采用这种做法，因为从 Qt 的角度来看，深度数据必须始终被写出。

environment : SceneEnvironment

包含

用于存储 XR 视图的SceneEnvironment 。

fixedFoveation : enumeration [default: XrView.HighFoveation]

控制XrView 的固定视网膜渲染级别。

视网膜中心渲染通过降低人眼难以察觉差异区域的图像质量（分辨率）来减轻 GPU 负载。在固定视网膜中心渲染模式下，视觉保真度降低的区域是固定的且不会变化。在某些平台上，并不存在固定视网膜中心渲染的概念，也无法对其进行控制。 例如，基于 VisionOS 的设备采用动态、基于眼动追踪的视网膜中心渲染；因此，该属性的值在实际中会被忽略。其他设备（如 Meta Quest 3）仅支持固定视网膜中心渲染，因此该属性才具有实际意义。

该值可以是以下之一：

在支持的情况下，默认值为HighFoveation 。因此，在实际应用中通常无需更改此值。

isQuitOnSessionEndEnabled : bool

用于指定在 XR 会话结束时应用程序是否应退出。

multiViewRenderingEnabled : bool [default: true]

这是一个只读属性，用于指示 XR 视图是否启用了多视图渲染。

该属性可告知您多视图渲染在运行时是否实际被使用。如果不支持，该值将恢复为false 。

建议启用多视图渲染。它可以提高性能并降低 CPU 和 GPU 的功耗。为确保最大兼容性，该属性默认处于禁用状态。建议开发人员在将 multiViewRenderingEnabled 设置为true 时，先验证应用程序是否按预期渲染，然后将其保持为该设置。

另请参阅《 multiViewRenderingSupported 》 和《多视图渲染》。

multiViewRenderingSupported : bool

此只读属性报告多视图渲染的可用性。

另请参阅 multiViewRenderingEnabled 。

passthroughEnabled : bool

Holds

表示 XR 视图是否启用了直通功能。

passthroughSupported : bool

表示

表示该 XR 视图是否支持直通功能。

referenceSpace : enumeration [default: XrView.ReferenceSpaceLocal]

获取或设置 XR 视图的参考空间。

其取值可以是以下之一：

ReferenceSpaceLocal 该选项主要适用于内容未相对于地面定位的坐姿应用，例如悬浮菜单。当用户重置视图时，内容会随之移动。

ReferenceSpaceStage 主要适用于房间级应用，用户可在游戏区域内自由移动。当用户重置视图时，内容不会移动。

ReferenceSpaceLocalFloor 主要适用于内容相对于地面定位的固定式应用（坐姿或站姿）。当用户重置视图时，内容会随之移动。

y: xrView.referenceSpace === XrView.ReferenceSpaceLocalFloor ? 130 : 0

renderStats : RenderStats

Holds

保存了 XR 视图的渲染统计数据。

runtimeInfo : QQuick3DXrRuntimeInfo

提供

提供有关 XR 视图中 XR 运行时的信息。

xrOrigin : XrOrigin

保存当前活动的 XR 原点。

XR原点是场景中被视为XR坐标系原点的点。XR原点用于在场景中定位被追踪的对象，例如摄像机和控制器。一个应用程序可以拥有多个XrOrigins，但同一时间只能有一个处于活动状态。

另请参阅 XrOrigin 。

信号文档

initializeFailed(const QString &errorString)

当初始化失败时触发此事件，且存在一个描述该失败原因的新errorString 对象。

sessionEnded()

在会话结束时触发。

方法文档

[since 6.11] pickResult closestPointPick(vector3d origin, float radius, Model model)

该方法将查找model 表面上距离origin 最近的点，且距离不超过radius 。如果model 为null ，则将查找radius 范围内最近的对象。

如果不存在此类对象，则返回null 。

该方法在 Qt 6.11 中引入。

vector3d processTouch(vector3d position, int pointId)

该方法将搜索位于position 附近的XrItem ，或具有sourceItem texture 的Model，并在position 映射到表面上的某个点时，发送一个触摸点ID为pointId 的虚拟触摸事件。

返回值是position 与表面上被触摸点之间的偏移量。这可用于防止手部模型穿过XrItem 。

另请参阅 XrHandModel 。

pickResult rayPick(vector3d origin, vector3d direction)

该方法将从坐标origin 、方向direction 向场景内发射一条光线，并返回该光线与场景中最近的物体相交的相关信息。

例如，传入场景中任意对象的位置和法向量，即可判断哪个对象位于该物品前方。这使得从场景中的任意点进行拾取操作成为可能。

[since 6.11] pickResult rayPick(vector3d origin, vector3d direction, Model model)

该方法将从坐标origin 和方向direction 向场景中“发射”一条光线，并返回该光线与指定model 之间的交点信息。

该方法于 Qt 6.11 中引入。

List<pickResult> rayPickAll(vector3d origin, vector3d direction)

该方法将从坐标origin 、方向向量direction 出发，向场景中发射一条光线，并返回一个列表，其中包含该光线与场景中物体最近交点的相关信息。该列表已按沿方向向量与原点之间的距离进行预排序，最近的交点排在最前面，最远的排在最后。

例如，可以通过传入场景中任意对象的位置和前进向量来调用此方法，从而查看该对象前方有哪些物体。这使得从场景中的任意点进行选中操作成为可能。

void setTouchpoint(Item target, point position, int pointId, bool pressed)

向target 发送一个合成触摸事件，将ID为pointId 的触摸点移动到position ，其中pressed 用于确定该点是否被按下。此外，如果之前在另一个项目上pointId 处于活动状态，则还会发送相应的触摸释放事件。

object touchpointState(int pointId)

该方法返回 ID 为pointId 的触点状态。该状态由一个将属性名称映射到值的映射表示：