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 컴포지터가 수행하는 재투영(reprojection)의 품질이 향상될 수 있습니다. 예를 들어, 시스템이 목표 프레임 속도를 유지할 수 없어 프레임 내용을 예측해야 하는 경우, 재투영이 발생할 수 있습니다. 이는 사용자가 장면을 인식하는 방식을 개선 및 안정화하고, 발생할 수 있는 멀미를 줄이기 위함입니다. 그러나 애플리케이션과 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 기반 기기는 동적이며 시선 추적을 기반으로 한 포비에이션 렌더링을 수행하므로, 실제로는 이 속성의 값이 무시됩니다. 반면 Meta Quest 3와 같은 다른 기기는 고정 포비에이션만 지원하므로 이 속성이 적용됩니다.

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

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

isQuitOnSessionEndEnabled : bool

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

multiViewRenderingEnabled : bool [default: true]

이 속성은 XR 뷰에 대해 멀티뷰 렌더링이 활성화되어 있는지 여부를 알려주는 읽기 전용 속성입니다.

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

멀티뷰 렌더링을 활성화하는 것이 권장됩니다. 이를 통해 성능을 향상시키고 CPU 및 GPU 전력 소비를 줄일 수 있습니다. 최대 호환성을 보장하기 위해 기본값은 비활성화되어 있습니다. 개발자는 `multiViewRenderingEnabled`를 ` true `로 설정했을 때 애플리케이션이 예상대로 렌더링되는지 확인한 후, 해당 설정을 그대로 유지할 것을 권장합니다.

‘ multiViewRenderingSupported ’ 및 ‘Multiview Rendering’항목도 참조하십시오 .

multiViewRenderingSupported : bool

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

multiViewRenderingEnabled도 참조하십시오 .

passthroughEnabled : bool

유지

XR 뷰에 대해 패스스루가 활성화되어 있는지 여부를 저장합니다.

passthroughSupported : bool

다음 사항을 나타냅니다.

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

referenceSpace : enumeration [default: XrView.ReferenceSpaceLocal]

XR 뷰의 기준 공간을 가져오거나 설정합니다.

다음 중 하나일 수 있습니다:

ReferenceSpaceLocal 주로 콘텐츠가 바닥을 기준으로 위치하지 않는, 예를 들어 플로팅 메뉴와 같은 착석형 애플리케이션에 유용합니다. 사용자가 뷰를 재설정하면 콘텐츠가 이동합니다.

ReferenceSpaceStage 는 사용자가 플레이 영역 내에서 자유롭게 이동하는 룸 스케일 애플리케이션에 주로 유용합니다. 사용자가 뷰를 재설정하더라도 콘텐츠는 이동하지 않습니다.

ReferenceSpaceLocalFloor 이 옵션은 콘텐츠가 바닥을 기준으로 배치되는 고정형 애플리케이션(앉은 자세 또는 서 있는 자세)에 주로 유용합니다. 사용자가 뷰를 재설정하면 콘텐츠가 이동합니다.

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

renderStats : RenderStats

보관

XR 뷰의 렌더링 통계를 보관합니다.

runtimeInfo : QQuick3DXrRuntimeInfo

다음 정보를 제공합니다

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

xrOrigin : XrOrigin

활성 XR 원점을 저장합니다.

XR 원점은 씬 내에서 XR 좌표계의 원점으로 간주되는 점입니다. XR 원점은 씬 내에서 카메라나 컨트롤러와 같은 추적 대상의 위치를 지정하는 데 사용됩니다. 애플리케이션은 여러 개의 XrOrigins를 가질 수 있지만, 한 번에 활성 상태일 수 있는 것은 하나뿐입니다.

참조: XrOrigin.

Signal 문서

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 를 가진 모델을 검색하고, 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 방향으로 빔을 쏴, 씬 내 오브젝트와의 가장 가까운 교차점에 대한 정보 목록을 반환합니다. 이 목록은 방향 벡터를 따라 원점으로부터의 거리 순으로 미리 정렬되어 있으며, 가장 가까운 교차점이 먼저 나타나고 가장 먼 교차점이 마지막에 나타납니다.

예를 들어, 씬 내 임의의 오브젝트의 위치와 전방 벡터를 이 메서드에 전달하여 해당 오브젝트 앞에 어떤 오브젝트들이 있는지 확인할 수 있습니다. 이를 통해 씬 내 임의의 지점에서 피킹(picking)을 수행할 수 있습니다.

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

target 에 합성 터치 이벤트를 전송하여, ID가 pointId 인 터치 지점을 position 로 이동시키고, pressed 를 통해 해당 지점이 눌려 있는지 여부를 판단합니다. 또한, 이전에 다른 항목에서 pointId 가 활성화되어 있었다면, 이에 상응하는 터치 해제 이벤트도 함께 전송합니다.

object touchpointState(int pointId)

이 메서드는 ID가 ` pointId`인 터치 지점의 상태를 반환합니다. 상태는 속성 이름과 값을 매핑한 맵 형태로 표현됩니다: