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 단순 예제에서 가져온 것으로, 유형 사용 방법을 보여줍니다.

// 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
    }

속성 문서

depthSubmissionEnabled : bool [default: false]

뎁스 버퍼를 XR 컴포저에 제출할지 여부를 제어합니다.

기본적으로 XrView 의 3D 씬에서 사용되는 뎁스 버퍼는 XR 컴포지터에 노출되지 않습니다. 그러나 일부 플랫폼에서는 뎁스 제출이 암시적이며 애플리케이션에서 비활성화하거나 제어할 수 없습니다. 그 예로 VisionOS를 들 수 있습니다. 이 속성을 변경해도 해당 플랫폼에는 영향을 미치지 않습니다. 다른 플랫폼, 특히 OpenXR의 경우 지원 여부는 런타임에 사용되는 OpenXR 구현에 따라 달라집니다.

기본 스택에서 지원되지 않는 경우에는 아무런 영향을 미치지 않으므로 항상 depthSubmissionEnabled를 true 로 설정하는 것이 안전합니다. 디버그 출력을 검사하여 깊이 제출이 사용 중인지 확인할 수 있습니다. 뎁스 버퍼를 제출하면 XR 컴포지터가 수행할 수 있는 리젝션이 개선될 수 있습니다. 예를 들어 시스템이 목표 프레임 속도를 유지할 수 없어 프레임 콘텐츠를 예측하여 장면에 대한 사용자의 인식을 개선하고 안정화하여 멀미 가능성을 줄여야 하는 경우 리프로젝션이 발생할 수 있습니다. 그러나 애플리케이션과 Qt는 데이터 사용량을 제어할 수 없습니다. 또한 뎁스 데이터를 제출해도 실질적인 효과가 없으며 기본 XR 런타임 및 컴포저에서 무시될 수 있습니다.

실제로 뎁스 버퍼를 제출한다는 것은 Qt가 생성하고 관리하는 중간 텍스처/렌더 버퍼 대신 XR 런타임에서 제공하는 뎁스 텍스처로 렌더링한다는 것을 의미합니다. 뎁스 텍스처로 렌더링하면 성능에 영향을 미칠 수 있는 특정 하위 수준의 결과가 발생합니다:

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 기반 디바이스는 동적 시선 추적 포비에이션을 수행하므로 실제로 이 속성의 값은 무시됩니다. 메타 퀘스트 3와 같은 다른 디바이스는 고정 포비에이션만 지원하므로 이 속성은 관련이 있습니다.

값은 다음 중 하나가 될 수 있습니다:

상수설명
XrView.NoFoveation0, 포비에이션 없음.
XrView.LowFoveation1, 낮은 포비에이션.
XrView.MediumFoveation2, 중간 포비에이션.
XrView.HighFoveation3, 높은 포비테이션.

지원되는 경우 기본값은 HighFoveation 입니다. 따라서 실제로는 애플리케이션에서 이 값을 변경할 필요가 거의 없습니다.


isQuitOnSessionEndEnabled : bool

XR 세션이 종료될 때 애플리케이션을 종료할지 여부를 보유합니다.


multiViewRenderingEnabled : bool [default: true]

XR 뷰에 대해 멀티뷰 렌더링이 활성화되었는지 여부를 보고하는 읽기 전용 속성입니다.

이 속성은 런타임에 멀티뷰 렌더링이 실제로 사용 중인지 여부를 알려줍니다. 지원되지 않는 경우 값은 false 로 반전됩니다.

멀티뷰 렌더링을 활성화하는 것이 좋습니다. 성능을 향상시키고 CPU 및 GPU 전력 사용량을 줄일 수 있습니다. 호환성을 최대한 보장하기 위해 기본값은 비활성화되어 있습니다. 개발자는 멀티뷰 렌더링 활성화를 true 으로 설정한 상태에서 애플리케이션이 예상대로 렌더링되는지 확인한 후 이 설정을 그대로 두는 것이 좋습니다.

참고: 애플리케이션에서 제공하는 셰이더 코드와 관련된 특정 Qt Quick 및 빠른 3D 기능은 멀티뷰와 호환되도록 이 코드를 수정해야 할 수 있습니다. 예를 들면 사용자 지정 2D 및 3D 머티리얼과 포스트 프로세싱 효과 등이 있습니다. 멀티뷰 렌더링 문서에서 이에 대한 자세한 내용과 멀티뷰 렌더링을 비활성화하는 방법을 확인할 수 있습니다.

multiViewRenderingSupported 및 멀티뷰 렌더링도참조하세요 .


multiViewRenderingSupported : bool

이 읽기 전용 속성은 멀티뷰 렌더링의 사용 가능 여부를 보고합니다.

multiViewRenderingEnabled도 참조하세요 .


passthroughEnabled : bool

Holds

XR 보기에 대한 패스스루 활성화 여부를 보류합니다.


passthroughSupported : bool

표시

XR 뷰에 대해 패스스루가 지원되는지 여부를 나타냅니다.


referenceSpace : enumeration

XR 보기의 참조 공간을 가져오거나 설정합니다.

다음 중 하나가 될 수 있습니다:

상수값
XrView.ReferenceSpaceUnknown
XrView.ReferenceSpaceLocal
XrView.ReferenceSpaceStage
XrView.ReferenceSpaceLocalFloor

renderStats : RenderStats

홀드

XR 뷰에 대한 렌더링 통계를 유지합니다.


runtimeInfo : QQuick3DXrRuntimeInfo

Provides

XR 뷰의 XR 런타임에 대한 정보를 제공합니다.


xrOrigin : XrOrigin

활성 XR 원점을 보유합니다.

XR 원점은 씬에서 XR 좌표계의 원점으로 간주되는 지점입니다. XR 원점은 씬에서 카메라 및 컨트롤러와 같은 추적된 오브젝트의 위치를 지정하는 데 사용됩니다. 애플리케이션에는 여러 개의 XrOrigin이 있을 수 있지만 한 번에 하나만 활성화할 수 있습니다.

참고: 씬이 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.