Back to Qt.io
Contact Us Blog Download Qt

XrView QML Type

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

Import Statement: import QtQuick3D.Xr
Since: Qt 6.8
Inherits:

Node

Status: Technical Preview

属性

信号

方法

详细说明

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
import QtQuick3D.Helpers
//! [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 中三维场景使用的深度缓冲区不会暴露给 XR 合成器。不过，在某些平台上，深度提交是隐式的，应用程序无法禁用或控制。VisionOS 就是一个例子。更改此属性对这些平台没有影响。在其他平台上，尤其是 OpenXR，对深度提交的支持取决于运行时使用的 OpenXR 实现。

将 depthSubmissionEnabled 设置为true 始终是安全的。只是在底层堆栈不支持的情况下，它将不起作用。为确保万无一失，您可以检查调试输出，查看是否使用了深度提交。提交深度缓冲区可以改善 XR 合成器可能执行的重投影。例如，当系统无法保持目标帧频，因而不得不通过预测帧内容来改善和稳定用户对场景的感知并减少可能出现的晕动症时，就会发生重投影。然而，应用程序和 Qt 无法控制数据的使用。提交深度数据也可能没有任何实际效果，会被底层 XR 运行时和合成器忽略。

实际上，提交深度缓冲区意味着渲染到 XR 运行时提供的深度纹理，而不是 Qt 创建和管理的中间纹理/渲染缓冲区。渲染到深度纹理会产生某些低级后果，从而影响性能：

使用multisample antialiasing (MSAA)时，启用深度提交意味着要渲染到多采样深度纹理中，并将采样解析到 XR 运行时提供的非多采样深度纹理中。如果没有深度提交，就不需要解析步骤。此外，某些 3D 应用程序接口不支持解析多采样深度模板数据（详见QRhi::ResolveDepthStencil 标志）。如果没有这种支持，结合 MSAA 启用深度提交的尝试会被优雅地忽略。

即使不使用 MSAA，启用深度提交也会触发使用可控制深度提交的 3D API 写出深度数据。Qt Positioning 通常会指出深度/模版数据的存储操作是不必要的，这会对平铺 GPU 架构的性能产生积极影响。在提交深度数据时不会这样做，因为从 Qt 的角度来看，深度数据必须始终写出。

注： 我们建议开发人员测试启用深度提交的应用程序，评估其优缺点，并根据测试结果有意识地选择是否启用深度提交。


environment : SceneEnvironment

保持

保持 XR 视图的SceneEnvironment 。


fixedFoveation : enumeration [default: XrView.HighFoveation]

控制XrView 的固定焦点渲染级别。

固定焦点渲染通过降低眼睛不易察觉差异的区域的图像质量（分辨率）来减少 GPU 负载。使用固定焦点渲染时，视觉保真度降低的区域是固定不变的。在某些平台上，没有固定焦点渲染的概念，也无法对其进行控制。例如，基于 VisionOS 的设备会执行动态眼动追踪，因此在实际应用中会忽略该属性的值。而其他设备，如 Meta Quest 3，只支持固定焦点渲染，因此该属性就显得非常重要。

该值可以是

常量说明
XrView.NoFoveation0，无视野。
XrView.LowFoveation1，低视野。
XrView.MediumFoveation2，中度视野缺损。
XrView.HighFoveation3，高视野。

在支持的情况下，默认值为HighFoveation 。因此，在实际应用中很少需要更改该值。


isQuitOnSessionEndEnabled : bool

XR 会话结束时应用程序是否退出。


multiViewRenderingEnabled : bool [default: true]

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

该属性会告诉你多视图渲染是否在运行时实际使用。不支持多视图渲染时，该值将返回false 。

建议启用多视图呈现。它可以提高性能并降低 CPU 和 GPU 的功耗。默认为禁用，以确保最大兼容性。我们鼓励开发人员在将 multiViewRenderingEnabled 设置为true 时验证其应用程序的渲染效果是否符合预期，然后将其保留。

注意： 某些Qt Quick 和 Quick 3D 功能涉及到应用程序提供的着色器代码，可能需要修改这些代码才能兼容多视图。例如自定义 2D 和 3D 材质以及后处理效果。多视图渲染文档提供了更多相关信息以及如何禁用多视图渲染。

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


multiViewRenderingSupported : bool

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

另请参阅 multiViewRenderingEnabled 。


passthroughEnabled : bool

保持

显示 XR 视图是否启用了直通。


passthroughSupported : bool

表示

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


referenceSpace : enumeration [default: XrView.ReferenceSpaceLocal]

获取或设置 XR 视图的引用空间。

它可以是

常量说明
XrView.ReferenceSpaceUnknown
XrView.ReferenceSpaceLocal原点位于默认视图位置（通常由 "重置视图 "操作定义）。
XrView.ReferenceSpaceStage原点位于用户定义区域中心的地面高度。
XrView.ReferenceSpaceLocalFloor原点位于地面高度，低于默认视图位置。

ReferenceSpaceLocal 主要适用于内容不相对于地面定位的坐姿应用程序，例如浮动菜单。当用户重新设置视图时，内容会移动。

ReferenceSpaceStage 主要适用于房间规模的应用，用户可在播放区域内自由移动。当用户重新设置视图时，内容不会移动。

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


renderStats : RenderStats

保持

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


runtimeInfo : QQuick3DXrRuntimeInfo

提供

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


xrOrigin : XrOrigin

保持活动 XR 原点。

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

注： 必须设置该属性才能以 XR 呈现场景。

另请参阅 XrOrigin 。


信号文档

initializeFailed(const QString &errorString)

当初始化失败时发射，并且有一个新的errorString 描述失败情况。

注： 相应的处理程序是onInitializeFailed 。


sessionEnded()

会话结束时发出。

注： 相应的处理程序是onSessionEnded 。


方法文档

vector3d processTouch(vector3d position, int pointId)

本方法将搜索position 附近的XrItem ，如果position 映射到表面上的一个点，则发送一个触摸点 ID 为pointId 的虚拟触摸事件。

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

另请参阅 XrHandModel 。


pickResult rayPick(vector3d origin, vector3d direction)

该方法将从origin 开始，在direction 向场景中发射一条射线，并返回与场景中物体最近的交点信息。

例如，通过传递场景中任何对象的位置和前向矢量，可以查看某个对象的前方是什么对象。这样就可以从场景中的任意点进行拾取。


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

该方法将从origin 开始，在direction 向场景中发射一条射线，并返回一个与场景中物体最近交点的信息列表。该列表按照从原点到方向矢量的距离进行排序，最近的交点出现在最前面，最远的交点出现在最后面。

例如，可以使用场景中任何物体的位置和前向矢量来调用该列表，以查看某个物体前面有哪些物体。这样就可以从场景中的任意点进行拾取。


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

向target 发送合成触摸事件，将 ID 为pointId 的触摸点移动到position ，由pressed 判断该点是否被按下。如果pointId 之前在其他项目上处于活动状态，则还会发送相应的触摸释放事件。


object touchpointState(int pointId)

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

键类型描述
grabbedbool该点是否被项目抓取？如果是false ，所有其他值都是undefined 。
targetXrItem抓取触摸点的项目。
pressedbool触摸点是否被按下？
cursorPospoint触摸点的 2D 位置在target
touchDistancereal平面到触摸点的距离。如果pressed 为true ，则为0 。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.