Qt Quick 3D - Quick Items 예시
Quick 3D 장면에서 ‘ Qt Quick ’ 아이템을 사용하는 방법을 보여줍니다.
이 예제는 Quick 3D 장면에서Qt Quick 2D 항목을 사용하는 방법을 보여줍니다.
Quick 3D 장면 내의 Quick Items
Qt Quick 2D Item과 그 모든 하위 항목을 Quick 3D 씬에 추가할 수 있습니다. 3D 씬에서 Qt Quick 유형을 사용할 때 주의해야 할 사항이 몇 가지 있습니다:
- Item Node 가 내에 있을 때, 해당 객체의 왼쪽 상단 모서리는 노드(Node)의 원점(origin)에 위치하게 됩니다. 즉, 의 원점이 의 중심점이 되도록 하려면 를 지정해야 하는 경우가 많습니다. Node Item
anchors.centerIn: parent - 3D 변환은 상위 노드( Node)로부터 상속됩니다. 동일한 변환의 영향을 받아야 하는
Item가 두 개 이상인 경우, 이러한 항목들은 Node 아래의 공통 상위 노드( Item )로 그룹화할 수 있습니다. - Qt 6.0에서는 항목이
MouseArea등을 통해 터치/마우스 이벤트를 수신하지 않으므로, 비상호작용형이어야 합니다. - Quick 항목은 빛과 그림자의 영향을 받지 않습니다.
- Clipping 사용하지 말고 의존하지 말아야 합니다.
이전 Qt 버전이나 다른 2D-in-3D 임베딩 방식과 달리, Qt Quick 항목을 Qt Quick 3D 노드에 부모로 설정한다고 해서 텍스처를 생성하고, 2D 콘텐츠를 그 텍스처에 렌더링한 다음, 텍스처가 적용된 사각형을 그리는 것은 아닙니다. 오히려 Qt 6.0은 3D 장면과 동일한 렌더링 패스 내에서 2D 콘텐츠를 렌더링하는 것을 지원합니다. 이는 실제로 성능이 크게 향상될 수 있습니다. 이는 예를 들어, layer.enabled 가 true로 설정되어 있거나, ShaderEffectSource 인 경우와 같이, 항목이 설계상 추가 렌더링 대상을 사용하여 렌더링되는 경우에는 적용되지 않습니다.
테스트 씬
이 예제의 핵심은 ` View3D ` 요소의 씬 콘텐츠입니다.
먼저 카메라에서 가장 멀리 떨어진 레이어를 추가합니다. 이 레이어에는 Rectangle, Text 및 Image 요소가 포함되어 있습니다. 레이어 내 요소들이 올바르게 배치되도록 하기 위해, 이 요소들은 공통 상위 요소인 Item 아래에 그룹화되어 있습니다. 모든 콘텐츠는 이 루트 항목 내에서 클리핑되므로 크기를 적절히 조정해야 합니다.
Node {
position: Qt.vector3d(0, 100, -120)
Item {
width: 400
height: 400
anchors.centerIn: parent
Rectangle {
anchors.fill: parent
opacity: 0.4
color: "#202020"
radius: 10
border.width: 2
border.color: "#f0f0f0"
}
Text {
anchors.top: parent.top
anchors.topMargin: 10
anchors.horizontalCenter: parent.horizontalCenter
font.pixelSize: 20
color: "#e0e0e0"
style: Text.Raised
text: qsTr("Background Item")
}
Image {
anchors.centerIn: parent
source: "Built_with_Qt_RGB_logo_vertical"
}
}
}다음으로 Node 와 그 내부의 항목들은 카메라에 조금 더 가까이 배치됩니다. 여기에는 x 위치와 회전 모두에 애니메이션이 적용된 세 개의 Rectangle 항목이 포함되어 있습니다. 애니메이션은 상위 요소인 Node 에서 수행되는 반면, Quick Item 의 콘텐츠는 정적 상태로 유지된다는 점에 유의하십시오. 성능 측면에서 볼 때, 이는 더 복잡한 항목을 다룰 때 효과적인 접근 방식입니다.
Node {
position: Qt.vector3d(0, 150, 100)
SequentialAnimation on x {
loops: Animation.Infinite
NumberAnimation {
to: -200
duration: 1500
easing.type: Easing.InOutQuad
}
NumberAnimation {
to: 200
duration: 1500
easing.type: Easing.InOutQuad
}
}
NumberAnimation on eulerRotation.z {
loops: Animation.Infinite
from: 0
to: 360
duration: 4000
easing.type: Easing.InOutBack
}
Item {
width: 400
height: 400
anchors.centerIn: parent
// This allows rendering into offscreen surface and caching it.
layer.enabled: true
Rectangle {
x: 150
y: 100
width: 100
height: 100
radius: 50
color: "#80808020"
border.color: "black"
border.width: 2
}
Rectangle {
x: 90
y: 200
width: 100
height: 100
radius: 50
color: "#80808020"
border.color: "black"
border.width: 2
}
Rectangle {
x: 210
y: 200
width: 100
height: 100
radius: 50
color: "#80808020"
border.color: "black"
border.width: 2
}
}
}이 예제의 세 번째 항목 레이어에는 불투명도 애니메이션이 적용된 단일 ‘ Text ’ 항목이 포함되어 있습니다. ‘Text’ 항목은 상위 ‘ Node ’ 내에서 자동으로 중앙 정렬됩니다.
Node {
position: Qt.vector3d(0, 80, 250)
Text {
anchors.centerIn: parent
width: 300
wrapMode: Text.WordWrap
horizontalAlignment: Text.AlignJustify
font.pixelSize: 14
color: "#e0e0e0"
style: Text.Raised
text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod " +
"tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim " +
"veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea " +
"commodo consequat."
SequentialAnimation on opacity {
loops: Animation.Infinite
NumberAnimation {
to: 0
duration: 1500
easing.type: Easing.InOutQuad
}
NumberAnimation {
to: 1
duration: 1500
easing.type: Easing.InOutQuad
}
}
}
}위의 Quick Item 레이어들의 z-순서를 시각화하기 위해, 3D 철거용 철구 모델도 설정해 보겠습니다. 이 모델은 상단의 Node 을 중심으로 회전하는 애니메이션을 수행하여, 구체가 다른 레이어들을 통과하도록 이동합니다.
Node {
position: Qt.vector3d(0, 800, 0)
SequentialAnimation on eulerRotation.x {
loops: Animation.Infinite
NumberAnimation {
to: 20
duration: 3500
easing.type: Easing.InOutQuad
}
NumberAnimation {
to: -20
duration: 3500
easing.type: Easing.InOutQuad
}
}
Model {
source: "#Cylinder"
y: -300
scale: Qt.vector3d(0.1, 6.1, 0.1)
materials: PrincipledMaterial {
baseColor: Qt.rgba(0.9, 0.9, 0.9, 1.0)
}
}
Model {
source: "#Sphere"
y: -700
scale: Qt.vector3d(2, 2, 2)
materials: PrincipledMaterial {
baseColor: Qt.rgba(0.4, 0.4, 0.4, 1.0)
}
}
}Qt Quick 3D 의 ‘2D 콘텐츠가 포함된 씬’도 참조하세요 .
© 2026 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.
