View3D QML Type

3D 씬을 렌더링할 뷰포트를 제공합니다. 더 보기...

• 상속된 멤버를 포함한 모든 멤버 목록

속성

• camera : QtQuick3D::Camera
• effectiveTextureSize : size (since 6.7)
• environment : QtQuick3D::SceneEnvironment
• explicitTextureHeight : int (since 6.7)
• explicitTextureWidth : int (since 6.7)
• extensions : List<QtQuick3D::Object3D>
• importScene : QtQuick3D::Node
• renderFormat : enumeration (since 6.4)
• renderMode : enumeration
• renderOverrides : enumeration
• renderStats : QtQuick3D::RenderStats
• scene : QtQuick3D::Node

방법

• pickResult closestPointPick(vector3d origin, float radius, Model model) (since 6.11)
• vector3d mapFrom3DScene(vector3d scenePos)
• vector3d mapTo3DScene(vector3d viewPos)
• pickResult pick(float x, float y)
• pickResult pick(float x, float y, Model model) (since 6.8)
• List<pickResult> pickAll(float x, float y) (since 6.2)
• list<Object3D> pickInRect(point start, point end) (since 6.11)
• List<pickResult> pickSubset(float x, float y, list<Model> models) (since 6.8)
• pickResult rayPick(vector3d origin, vector3d direction) (since 6.2)
• pickResult rayPick(vector3d origin, vector3d direction, Model model) (since 6.11)
• List<pickResult> rayPickAll(vector3d origin, vector3d direction) (since 6.2)
• void setTouchpoint(Item target, point position, int pointId, bool pressed) (since 6.8)

상세 설명

View3D는 3D 씬을 렌더링할 수 있는 2D 표면을 제공합니다. 이 표면은 Qt Quick Item 이며, Qt Quick 씬 내에 배치할 수 있습니다.

View3D에 시각화될 3D 장면을 정의하는 방법에는 두 가지가 있습니다. Node-based 항목들의 계층 구조를 View3D의 자식 요소로 직접 정의하면, 이것이 View3D의 암시적 장면이 됩니다.

또한 importScene 속성을 사용하여 시각화하려는 씬의 루트 Node 을 설정함으로써 기존 씬을 참조할 수도 있습니다. 이 Node 은 View3D의 상위 노드일 필요는 없으며, 동일한 씬을 불러오는 여러 View3D를 가질 수 있습니다.

이는 View3D 예제에서 확인할 수 있습니다.

View3D에 자식 Nodes 이 있고 importScene 속성이 동시에 설정된 경우, 두 장면은 마치 동일한 장면 내의 형제 하위 트리인 것처럼 렌더링됩니다.

씬이 렌더링되는 방식을 제어하려면 environment 속성을 설정할 수 있습니다. SceneEnvironment 유형에는 배경색, 톤 매핑, 앤티앨리어싱 등 조정할 수 있는 여러 시각적 속성이 있습니다. QtQuick3D.Helpers 모듈의 ExtendedSceneEnvironment 는 SceneEnvironment 를 확장하여 일반적인 후처리 효과를 추가하는 등 더 많은 기능을 제공합니다.

또한, View3D에서 무언가를 렌더링하려면 씬에 Camera 가 필요합니다. 씬에 Camera 가 단 하나만 있다면, 이 카메라가 자동으로 선택됩니다. 그렇지 않은 경우, camera 속성을 사용하여 카메라를 선택할 수 있습니다. Camera 는 씬의 어느 부분이 보이는지, 그리고 이들이 2D 표면에 어떻게 투영될지를 결정합니다.

기본적으로 3D 장면은 먼저 오프스크린 버퍼에 렌더링된 후, 렌더링이 완료되면 나머지 Qt Quick 장면과 합성됩니다. 이는 최대 수준의 호환성을 제공하지만, 일부 그래픽 하드웨어에서는 성능에 영향을 미칠 수 있습니다. 이러한 경우, renderMode 속성을 사용하여 View3D가 창에 렌더링되는 방식을 변경할 수 있습니다.

기본값인 Offscreen renderMode 을 사용하는 View3D는 암시적으로 texture provider 이기도 합니다. 즉, 모든 항목이 동일한 window 내에 존재하는 한, ShaderEffect 또는 Texture.sourceItem 에서 View3D를 직접 참조할 수 있습니다. 다른 Item 와 마찬가지로, View3D나 그 상위 객체 중 하나를 텍스처 기반 item layer 로 전환하는 것도 가능합니다.

Qt Quick 3D 의 View3D 예제도참조하십시오 .

속성 문서

camera : QtQuick3D::Camera

이 속성은 씬을 렌더링하는 데 사용할 Camera 를 지정합니다. 이 속성이 설정되지 않은 경우, 씬에서 활성화된 첫 번째 카메라가 사용됩니다.

참조: PerspectiveCamera, OrthographicCamera, FrustumCamera, CustomCamera.

effectiveTextureSize : size [since 6.7]

이 속성은 기본 색상(및 깊이/스텐실) 버퍼의 크기를 픽셀 단위로 반환합니다. 이 속성은 GUI(메인) 스레드, QML 바인딩 또는 JavaScript에서 사용하도록 제공됩니다.

이 속성은 읽기 전용입니다.

이 속성은 Qt 6.7에서 도입되었습니다.

explicitTextureWidth, explicitTextureHeight 및 DebugView도 참조하십시오 .

environment : QtQuick3D::SceneEnvironment

이 속성은 씬을 렌더링하는 데 사용되는 SceneEnvironment 를 지정합니다.

SceneEnvironment항목도 참조하십시오 .

explicitTextureHeight : int [since 6.7]

아이템에 연결된 텍스처의 높이(픽셀 단위). 이 항목의 크기에 영향을 받지 않는 고정된 텍스처 크기를 원할 때 관련이 있습니다. 이 크기는 항목의 지오메트리(크기 및 장면 내 배치)에 영향을 미치지 않으므로, 텍스처의 내용이 항목 영역에 맞춰 확대되거나 축소(또는 늘어나기도 함)되어 표시됩니다.

기본값은 0 입니다. 값이 0이면 텍스처 크기가 아이템의 크기를 따릅니다. (texture size in pixels = item's logical size * device pixel ratio).

이 속성은 Qt 6.7에서 도입되었습니다.

explicitTextureWidth, effectiveTextureSize 및 DebugView항목도 참조하십시오 .

explicitTextureWidth : int [since 6.7]

아이템에 적용된 텍스처의 너비(픽셀 단위). 이 항목의 크기에 상관없이 고정된 텍스처 크기를 원할 때 관련이 있습니다. 이 크기는 항목의 지오메트리(크기 및 씬 내 배치)에는 영향을 미치지 않으므로, 텍스처의 내용이 항목 영역에 맞춰 확대되거나 축소(혹은 왜곡될 수도 있음)되어 표시됩니다.

기본값은 0 입니다. 값이 0이면 텍스처 크기가 아이템의 크기를 따릅니다. (texture size in pixels = item's logical size * device pixel ratio).

이 속성은 Qt 6.7에서 도입되었습니다.

explicitTextureHeight, effectiveTextureSize 및 DebugView도 참조하십시오 .

extensions : List<QtQuick3D::Object3D>

이 속성에는 이 View3D 와 함께 사용해야 하는 사용자 확장 기능 목록이 포함되어 있습니다.

RenderExtension도 참조하십시오 .

importScene : QtQuick3D::Node

이 속성은 뷰포트에 렌더링할 장면의 참조 노드를 정의합니다. 이 노드는 반드시 ` View3D`의 자식 노드일 필요는 없습니다. 참조된 이 노드는 ` View3D`에 자식 노드가 있는 경우, 해당 자식 노드들과 형제 노드가 됩니다.

또한 Node-based 항목들의 계층 구조를 View3D 의 자식으로 직접 정의할 수 있으며, 이 경우 해당 구조가 View3D 의 암시적 장면이 됩니다.

View3D 의 현재 장면을 반환하려면 scene 속성을 사용하십시오.

Node도 참조하십시오 .

renderFormat : enumeration [since 6.4]

이 속성은 백킹 텍스처의 형식을 결정합니다. 이 속성은 View3D 가 텍스처로 렌더링할 때만 적용되며, 예를 들어 renderMode 가 View3D.Offscreen 인 경우와 같습니다.

기본값은 ShaderEffectSource.RGBA8 입니다.

실행 시 기본 그래픽 드라이버에서 해당 형식을 지원하지 않는 경우, RGBA8이 사용됩니다.

• ShaderEffectSource.RGBA8
• ShaderEffectSource.RGBA16F
• ShaderEffectSource.RGBA32F

이 속성은 Qt 6.4에서 도입되었습니다.

QtQuick::ShaderEffectSource::format 및 QtQuick::Item::layer.format도 참조하십시오 .

renderMode : enumeration

이 속성은 ‘ View3D ’가 ‘ Qt Quick ’ 장면의 다른 부분들과 어떻게 결합될지를 결정합니다.

기본적으로 씬은 중간 단계로 오프스크린 버퍼에 렌더링됩니다. 그런 다음 이 오프스크린 버퍼는 다른 Qt Quick Item 와 마찬가지로 창(또는 렌더 타깃)에 렌더링됩니다.

대부분의 사용자는 렌더 모드를 변경할 필요가 없으므로 이 속성은 무시해도 무방합니다. 하지만 일부 그래픽 하드웨어에서는 오프스크린 버퍼 사용이 성능 병목 현상을 일으킬 수 있습니다. 이러한 경우 다른 모드를 시도해 보는 것이 좋습니다.

기본값은 View3D.Offscreen 입니다.

renderOverrides : enumeration

Qt Quick 3D 의 렌더링 방식을 제어합니다.

renderStats : QtQuick3D::RenderStats [read-only]

이 속성은 fps, frameTime, renderTime, syncTime, maxFrameTime 등과 같이 프레임 렌더링에 관한 통계 정보를 제공합니다.

scene : QtQuick3D::Node [read-only]

View3D 의 씬에 대한 루트 Node 를 반환합니다.

View3D 에 시각화될 3D 씬을 정의하려면:

• ' View3D '의 자식으로 ' Node-based ' 항목들의 계층 구조를 직접 정의하면, 이것이 ' View3D'의 암시적 장면이 됩니다.
• importScene 속성을 사용하여 기존 씬을 참조하고, 이를 시각화하려는 씬의 루트 Node 로 설정합니다. 이 Node 는 View3D 의 상위 노드일 필요는 없으며, 동일한 씬을 불러오는 View3D를 여러 개 가질 수 있습니다.

importScene도 참조하십시오 .

메서드 문서

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

이 메서드는 model 표면 중 origin 에 가장 가까운 점( radius 이내)을 찾습니다. model 가 null 인 경우, radius 내에서 가장 가까운 객체를 찾습니다.

해당 객체가 존재하지 않으면 null 가 반환됩니다.

이 메서드는 Qt 6.11에서 도입되었습니다.

vector3d mapFrom3DScene(vector3d scenePos)

scenePos 를 씬 공간(3D)에서 뷰 공간(2D)으로 변환합니다.

반환되는 x 및 y 값은 뷰 좌표계에서 표시되며, 좌상단 모서리는 [0, 0]이고 우하단 모서리는 [width, height]입니다. 반환되는 z 값은 프러스텀(frustum)의 근접 클립 평면(clipNear)에서 scenePos 까지의 거리를 씬 좌표계로 나타낸 값입니다. 이 거리가 음수인 경우, scenePos 가 활성 카메라 뒤에 있음을 의미합니다. scenePos 를 씬 내의 위치로 매핑할 수 없는 경우, [0, 0, 0] 위치가 반환됩니다.

이 함수를 사용하려면 camera 가 뷰에 할당되어 있어야 합니다.

mapTo3DScene() 및 Camera.mapToViewport()도 참조하십시오 .

vector3d mapTo3DScene(vector3d viewPos)

viewPos 를 뷰 공간(2D)에서 씬 공간(3D)으로 변환합니다.

viewPos 의 x 및 y 값은 뷰 좌표계로 표기되어야 하며, 왼쪽 상단 모서리는 [0, 0]이고 오른쪽 하단 모서리는 [width, height]입니다. z 값은 씬 좌표계에서 프러스텀의 근접 클립 평면(clipNear)으로부터의 거리로 해석됩니다.

viewPos 를 씬 내의 위치로 성공적으로 매핑할 수 없는 경우, [0, 0, 0] 위치가 반환됩니다.

이 함수를 사용하려면 뷰에 camera 가 할당되어 있어야 합니다.

mapFrom3DScene() 및 Camera.mapFromViewport()도 참조하십시오 .

pickResult pick(float x, float y)

이 메서드는 뷰 좌표 x 및 y 에서 씬 안으로 광선을 “발사”하고, 씬 내 오브젝트와의 가장 가까운 교차점에 대한 정보를 반환합니다.

예를 들어, 마우스 좌표를 사용하여 이 함수를 호출하면 마우스 커서 아래에 있는 오브젝트를 찾을 수 있습니다.

렌더링 시 머티리얼 cull mode 이 제외하는 삼각형도 선택되지 않으므로, 광선을 따라 실제로 보이는 지오메트리만 보고됩니다.

pickAll(), pickSubset() 및 pickInRect()도 참조하십시오 .

[since 6.8] pickResult pick(float x, float y, Model model)

이 메서드는 뷰 좌표 x 와 y 에서 씬 안으로 광선을 “발사”하고, 광선과 지정된 model 간의 교차점에 대한 정보를 반환합니다.

예를 들어, 마우스 좌표를 전달하여 마우스 커서 아래에 있는 객체를 찾는 데 이 메서드를 호출할 수 있습니다.

이 메서드는 Qt 6.8에서 도입되었습니다.

pickAll(), pickSubset() 및 pickInRect()도 참조하십시오 .

[since 6.2] List<pickResult> pickAll(float x, float y)

이 메서드는 뷰 좌표 x 및 y 에서 씬 안으로 광선을 “발사”하고, 씬 내 오브젝트와의 교차점에 대한 정보 목록을 반환합니다. 반환된 목록은 카메라와의 거리 순으로 정렬되며, 가장 가까운 교차점이 먼저 나타나고 가장 먼 교차점이 마지막에 나타납니다.

예를 들어, 마우스 좌표를 전달하여 이 메서드를 호출하면 마우스 커서 아래에 있는 객체를 찾을 수 있습니다.

이 메서드는 Qt 6.2에서 도입되었습니다.

pick(), pickSubset() 및 pickInRect()도 참조하십시오 .

[since 6.11] list<Object3D> pickInRect(point start, point end)

이 메서드는 뷰 좌표계에서 start 및 end 좌표로 정의된 직사각형 영역 내의 모든 오브젝트를 선택합니다.

지정된 직사각형 내에 있는 객체 목록을 반환합니다. 이 메서드는 사용자가 직사각형을 드래그하여 여러 객체를 선택하는 마키 선택에 사용할 수 있습니다.

이 메서드는 Qt 6.11에서 도입되었습니다.

pick(), pickAll(), pickSubset()도 참조하십시오 .

[since 6.8] List<pickResult> pickSubset(float x, float y, list<Model> models)

이 메서드는 뷰 좌표 x 와 y 에서 씬 안으로 광선을 “발사”하고, 전달된 모델 목록 models 과의 교차점에 대한 정보를 반환합니다. 이 메서드는 전달된 모델 목록에 대해서만 교차 여부를 확인합니다. 반환되는 목록은 카메라와의 거리 순으로 정렬되며, 가장 가까운 교차점이 먼저 나타나고 가장 먼 교차점이 마지막에 나타납니다.

예를 들어, 마우스 좌표를 전달하여 마우스 커서 아래에 있는 오브젝트를 찾을 때 이 메서드를 호출할 수 있습니다.

property list<Model>과 동적 JavaScript 모델 배열 모두에서 작동합니다.

이 메서드는 Qt 6.8에서 도입되었습니다.

pick(), pickAll() 및 pickInRect()도 참조하십시오 .

[since 6.2] pickResult rayPick(vector3d origin, vector3d direction)

이 메서드는 origin 에서 시작하여 direction 방향으로 빔을 씬 안으로 “발사”하고, 씬 내 오브젝트와의 가장 가까운 교차점에 대한 정보를 반환합니다.

예를 들어, 씬 내의 임의 오브젝트의 위치와 전방 벡터를 전달하여 이 메서드를 호출하면, 특정 아이템 앞에 어떤 오브젝트가 있는지 확인할 수 있습니다. 이를 통해 씬 내의 어느 지점에서든 피킹을 수행할 수 있습니다.

렌더링 시 머티리얼의 cull mode 에 의해 제외된 삼각형도 피킹 대상에서 제외되므로, 광선을 따라 실제로 보이는 지오메트리만 보고됩니다.

이 메서드는 Qt 6.2에서 도입되었습니다.

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

이 메서드는 origin 에서 시작하여 direction 방향으로 빔을 씬 안으로 “발사”하고, 빔과 지정된 model 간의 교차점에 대한 정보를 반환합니다.

이 메서드는 Qt 6.11에서 도입되었습니다.

[since 6.2] List<pickResult> rayPickAll(vector3d origin, vector3d direction)

이 메서드는 origin 에서 시작하여 direction 방향으로 빔을 씬 안으로 “발사”하고, 씬 내 오브젝트와의 가장 가까운 교차점에 대한 정보 목록을 반환합니다. 이 목록은 방향 벡터를 따라 원점으로부터의 거리 순으로 미리 정렬되어 있으며, 가장 가까운 교차점이 먼저 나타나고 가장 먼 교차점이 마지막에 나타납니다.

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

이 메서드는 Qt 6.2에서 도입되었습니다.

[since 6.8] void setTouchpoint(Item target, point position, int pointId, bool pressed)

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

이 메서드는 Qt 6.8에서 도입되었습니다.