Qt Quick 2Dコンテンツを含む3Dシーン
3Dワールド内の2Dアイテム
Qt Quick 3D を使用すると、3D 要素と 2D 要素を組み合わせたシーンを効率的に作成・レンダリングできます。
「3Dと2Dを組み合わせたシーン」とは、具体的にどのようなものなのでしょうか？
本質的に、2Dシーン内の3Dビューポートを表すView3D オブジェクトは、Rectangle、Image、TextなどのQt Quick アイテムと、View3D アイテムの周囲、下、または上に簡単に組み合わせることができます。 アイテム自体は、Qt Quick Item です。
次の例を考えてみましょう：
import QtQuick
import QtQuick3D
Rectangle {
gradient: Gradient {
GradientStop { position: 0; color: "steelblue" }
GradientStop { position: 1; color: "black" }
}
Text {
text: "Hello 2D World"
font.pointSize: 32
color: "red"
anchors.top: parent.top
anchors.horizontalCenter: parent.horizontalCenter
}
Item {
width: 400; height: 400
anchors.centerIn: parent
View3D {
anchors.fill: parent
environment: SceneEnvironment { backgroundMode: SceneEnvironment.Color; clearColor: "lightGray" }
PerspectiveCamera { z: 600 }
DirectionalLight { }
Model {
source: "#Cube"
materials: PrincipledMaterial { baseColor: "green"; metalness: 0.0; roughness: 0.0 }
eulerRotation: Qt.vector3d(30, 45, 0)
}
}
}
}
ここでは、3Dシーンは灰色の背景のある領域です。ウィンドウの残りの部分は、2DのQt Quick アイテムで構成されています。これらはView3D と重なることはありますが、3Dワールドの一部ではなく、3D座標系を使用しておらず、3Dシーンの変換にも参加しません。
では、2Dアイテムを3Dワールド内に配置し、すべての3D変換に真に反映させたい場合はどうすればよいでしょうか？例えば、Rectangle やText のアイテムを3Dワールド内に配置し、キューブの回転に追従して常にその上に表示されるようにすることは可能でしょうか？
以下のセクションでは、これを実現する方法について見ていきます。この例ではRectangle とText を使用していますが、Qt Quick Controls、Shape 、ShaderEffect 、ParticleSystem を含む、あらゆるQt Quick コンテンツをこの方法で使用できます。
注： 2D コンテンツを 3D オブジェクトに統合する方法は他にもあります 。 3D ノードに 2D アイテムを追加することで、3D ワールド内で 2D オブジェクトと 3D オブジェクトを自由に組み合わせることができますが、3D オブジェクトの表面に 2D コンテンツをレンダリングすることはできません。Qt Quick で生成されたコンテンツを使用して 3D メッシュにテクスチャを適用する場合は、代わりにthe sourceItem property またはTexture を使用してください。
| Qt Quick テクスチャマップとして使用されるコンテンツ | Qt Quick 3Dシーン内のアイテム |
|---|---|
|
|
3Dノードへの2Dアイテムの追加
これを可能にする鍵となるのは、Object3D がItem の子オブジェクトを受け入れ、それらを特別な方法で処理する機能です。Object3D は、Node 型の基底クラスです。つまり、Node や、Model のような型も、Item の子オブジェクトを受け入れます。
Qt 6.0 以降、3D ノードに 2D アイテムを追加しても、2D コンテンツが OpenGL テクスチャや Vulkan 画像などにレンダリングされることはなくなりました。その代わり、デフォルトでは、2D アイテムは 3D シーンの他の部分と同様に、同じレンダリングパス内でインラインでレンダリングされるようになりました。 2Dアイテムには、すべての3D変換が適用されます。これらの変換は、親ノードであるNode から継承されます。
import QtQuick
import QtQuick3D
Rectangle {
gradient: Gradient {
GradientStop { position: 0; color: "steelblue" }
GradientStop { position: 1; color: "black" }
}
Text {
text: "Hello 2D World"
font.pointSize: 32
color: "red"
anchors.top: parent.top
anchors.horizontalCenter: parent.horizontalCenter
}
Item {
width: 400; height: 400
anchors.centerIn: parent
View3D {
anchors.fill: parent
environment: SceneEnvironment { backgroundMode: SceneEnvironment.Color; clearColor: "lightGray" }
PerspectiveCamera { z: 600 }
DirectionalLight { }
Model {
Node {
y: 150
Rectangle {
anchors.horizontalCenter: parent.horizontalCenter
color: "white"
width: text3d.width
height: text3d.height
Text {
id: text3d
text: "Hello 3D World"
font.pointSize: 32
}
}
}
source: "#Cube"
materials: PrincipledMaterial { baseColor: "green"; metalness: 0.0; roughness: 0.0 }
eulerRotation: Qt.vector3d(30, 45, 0)
}
}
}
}
最初のスニペットと比較すると、Model ノードには子ノードが追加されており、そのトランスフォームによって、子ノードはキューブの位置よりやや上に配置されています。150 は、3D座標空間においてキューブの中心を基準としています。
Model {
Node {
y: 150次に、Rectangle アイテムがあります。これをNode の下に追加すると、内部的には3D世界と2D世界の境界が越えられますが、アプリケーション設計者にとっては透過的なままです。 目に見えないcontent item が自動的に生成され、これによりRectangleはparent を参照してアンカー設定を行うことができます。Nodeからの3D変換は、2Dサブツリー全体に適用されます。この例では、回転が立方体の回転と一致することを意味します。
Node {
y: 150
Rectangle {
anchors.horizontalCenter: parent.horizontalCenter2Dおよび3Dの座標系
2Dアイテムは引き続きQt Quick の座標系を使用します。Y軸は上から下へ伸びており、単位はピクセルに対応しています。一方、3Dノードは3D座標系を使用します。Y軸は上向きで、単位はセンチメートルに対応しており、Camera の透視投影の影響を受けます。
デフォルトでは、最上位アイテムの左上隅はノードの原点に配置されます。 つまり、2D サブツリーの最上位アイテムでは、多くの場合、アンカーを指定する必要があります。例えば、anchors.centerIn: parent や、この例のように、水平方向の中心を親ノードの水平方向の中心にアンカーすることで、2D コンテンツを 3D ノード上で水平方向に中央に配置します。
その他の考慮事項
- 2D アイテムは 3D オブジェクトと並行してレンダリングされますが、ライティングには参加せず、影を落とすこともありません。
- Clipping は期待どおりに動作しない可能性があるため、避けるべきです。2D アイテムの設計にクリッピングが不可欠な場合は、アプリケーションは明示的にテクスチャへのレンダリングにフォールバックする必要があります。これは、3D ノードの下にある最上位の
Itemにlayer.enabled: trueを追加することで実現できます。 - Qt 6.2 以降、入力は必要に応じて 2D アイテムに渡されます。ポインティングデバイスからの入力は、宣言されたアイテムの `childrenRect ` 内で発生する必要があります。
- 2Dアイテムツリーを3Dシーンに追加する処理自体は比較的軽量ですが、3Dシーン内に過剰な数（数百以上）の2Dサブツリーが存在することは避けるべきです。なぜなら、数が多すぎるとメモリやグラフィックスリソースの使用量が増加する可能性があるためです。 なお、これは3Dノードの下にある個別のItem サブツリーの数を指しており、それらのサブツリーに含まれる2Dアイテムの総数ではないことに注意してください。たとえば、上記のQMLスニペットには2Dサブツリーが1つしか含まれていません。
「Qt Quick 3D - Quick Items の例」および「QQuickItem::mapFromGlobal()」も参照してください 。
© 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.
