QQuick3DGeometry Class

カスタムジオメトリを定義するための基底クラス。詳細...

Header: #include <QQuick3DGeometry>
In QML: Geometry
Inherits: QQuick3DObject

パブリック関数

void addAttribute(QQuick3DGeometry::Attribute::Semantic semantic, int offset, QQuick3DGeometry::Attribute::ComponentType componentType)
void addAttribute(const QQuick3DGeometry::Attribute &attribute)
void addSubset(int offset, int count, const QVector3D &boundsMin, const QVector3D &boundsMax, const QString &name = {})
(since 6.6) void addTargetAttribute(quint32 targetId, QQuick3DGeometry::Attribute::Semantic semantic, int offset, int stride = 0)
(since 6.6) void addTargetAttribute(const QQuick3DGeometry::TargetAttribute &attribute)
QQuick3DGeometry::Attribute attribute(int index) const
int attributeCount() const
QVector3D boundsMax() const
QVector3D boundsMin() const
void clear()
QByteArray indexData() const
QQuick3DGeometry::PrimitiveType primitiveType() const
void setBounds(const QVector3D &min, const QVector3D &max)
void setIndexData(const QByteArray &data)
void setIndexData(int offset, const QByteArray &data)
void setPrimitiveType(QQuick3DGeometry::PrimitiveType type)
void setStride(int stride)
(since 6.6) void setTargetData(const QByteArray &data)
(since 6.6) void setTargetData(int offset, const QByteArray &data)
void setVertexData(const QByteArray &data)
void setVertexData(int offset, const QByteArray &data)
int stride() const
QVector3D subsetBoundsMax(int subset) const
QVector3D subsetBoundsMin(int subset) const
int subsetCount() const
int subsetCount(int subset) const
QString subsetName(int subset) const
int subsetOffset(int subset) const
(since 6.6) QQuick3DGeometry::TargetAttribute targetAttribute(int index) const
(since 6.6) int targetAttributeCount() const
(since 6.6) QByteArray targetData() const
QByteArray vertexData() const

詳細説明

QQuick3DGeometry は、Qt Quick 3Dシーンの Model のカスタムジオメトリを指定するために使用できます。

厳密には必須ではありませんが、典型的な使用方法は、このクラスを継承することです。このサブクラスは、型システムに登録することで QML に公開されます。モデルのgeometry プロパティは、登録された型のインスタンスを参照するように設定することができます。

このようなクラスの高レベルの構造は、通常以下のようなものです:

class CustomGeometry : public QQuick3DGeometry
{
public:
    CustomGeometry() { rebuildGeometry(); }

    void setSomething() {
       // Change relevant internal data.
       // ...

       // Then rebuild the vertex and index data and pass it to QQuick3DGeometry.
       rebuildGeometry();

       // Finally, trigger an update. This is relevant in case nothing else
       // is changing in the scene; this way we make sure a new frame will
       // be rendered.
       update();
    }

private:
    void rebuildGeometry()
    {
        QByteArray vertices;
        QByteArray indices;
        ...
        setPrimitiveType(Lines);
        setVertexBuffer(vertices);
        setIndexBuffer(indices);
        setStride(3 * sizeof(float)); // e.g. when having 3 components per vertex
        setBounds(...); // minimum and maximum extents, for picking
        addAttribute(PositionSemantic, 0, F32Type);
        ...
    }
};

このクラスをQMLの型として登録し、Model

Qt 5 では、型の登録はqmlRegisterType で行いました:

qmlRegisterType<CustomGeometry>("Example", 1, 0, "CustomGeometry");

Qt 6 では、ビルドシステムによる自動登録がデフォルトになっています。qmlRegisterType を呼び出す代わりに、.pro ファイルを含むことができます:

CONFIG += qmltypes
QML_IMPORT_NAME = Example
QML_IMPORT_MAJOR_VERSION = 1

CMakeでは、自動登録がデフォルトの動作なので、基本的なQMLモジュールのセットアップ以上の特別な設定は必要ありません:

qt_add_qml_module(application
    URI Example
    VERSION 1.0
)

クラスの実装はQML_NAMED_ELEMENT を追加します:

class CustomGeometry : public QQuick3DGeometry
{
    Q_OBJECT
    QML_NAMED_ELEMENT(CustomGeometry)
    ...
};

QML コードはカスタムタイプを使用することができます:

import Example 1.0

Model {
    id: customModel
    geometry: CustomGeometry {
    }
}

カスタムジオメトリには、最低限、以下の項目を指定する必要があります:

  • 頂点データ
  • 頂点データ、頂点ストライド、
  • プリミティブタイプ、
  • PositionSemantic 属性。

これらはメッシュをレンダリングするのに十分です。インデックス描画の場合は、インデックスバッファデータとIndexSemantic属性を指定する必要があります。ピッキング(入力)をサポートするために、クラスはsetBounds() を使ってバウンディングボリュームを指定する必要があります。適切なライティングのためには、NormalSemanticを持つアトリビュートが必要です。マテリアルがテクスチャリングを使用する場合、UV 座標の少なくとも 1 つのセットを提供し、TexCoord0Semantic または TexCoord1Semantic 属性に記述する必要があります。マテリアルによっては、タンジェントやバイノルマルも必要になる場合があります。

具体的で最小限の例として、次のクラスは単一の三角形のジオメトリを提供します:

class ExampleGeometry : public QQuick3DGeometry
{
    Q_OBJECT
    QML_NAMED_ELEMENT(ExampleGeometry)

public:
    ExampleGeometry();

private:
    void updateData();
};

ExampleGeometry::ExampleGeometry()
{
    updateData();
}

void ExampleGeometry::updateData()
{
    QByteArray v;
    v.resize(3 * 3 * sizeof(float));
    float *p = reinterpret_cast<float *>(v.data());

    // a triangle, front face = counter-clockwise
    *p++ = -1.0f; *p++ = -1.0f; *p++ = 0.0f;
    *p++ = 1.0f; *p++ = -1.0f; *p++ = 0.0f;
    *p++ = 0.0f; *p++ = 1.0f; *p++ = 0.0f;

    setVertexData(v);
    setStride(3 * sizeof(float));

    setPrimitiveType(QQuick3DGeometry::PrimitiveType::Triangles);

    addAttribute(QQuick3DGeometry::Attribute::PositionSemantic,
                 0,
                 QQuick3DGeometry::Attribute::F32Type);
}

シーンの照明によっては、Modelからこのジオメトリを参照した結果が表示されます:

注意: 頂点データはOpenGLの規約に従う必要があります。つまり、正規化されたデバイス座標系でY軸が上を向いており、前面が反時計回りに巻いているという前提でデータを提供する必要があります。

Model およびGeometryも参照して ください。

メンバ関数ドキュメント

void QQuick3DGeometry::addAttribute(QQuick3DGeometry::Attribute::Semantic semantic, int offset, QQuick3DGeometry::Attribute::ComponentType componentType)

頂点属性の説明を追加します。各属性は、semantic (属性の使用方法と構成要素の数を指定)、offset (頂点への始点から頂点内の属性位置まで)、componentType (属性のデータ型とサイズを指定)を持ちます。

セマンティックは以下のいずれかになります:

定数説明
PositionSemantic属性は位置です。3成分:xyz
NormalSemantic属性は法線ベクトル。3成分:x,y,z
TexCoord0Semantic属性はテクスチャ座標です。2成分:uと v
TexCoord1Semantic属性はテクスチャ座標です。2 成分:uv
TangentSemantic属性はタンジェントベクトルです。3成分:xyz
BinormalSemantic属性は2法線ベクトルです。3成分:xyz
JointSemantic属性はスキニングのためのジョイントインデックスベクトルです。4成分: ジョイントインデックス1-4
WeightSemantic属性はスキニングのための重みベクトルです。4 成分: ジョイント重み 1-4
ColorSemantic属性は頂点色ベクトルです。4成分:rgba
TargetPositionSemantic属性は最初のモーフターゲットの位置です。3成分:xyz
TargetNormalSemantic属性は最初のモーフターゲットの法線ベクトルです。3成分:xyz
TargetTangentSemantic属性は最初のモーフターゲットの接線ベクトルです。3成分:xyz
TargetBinormalSemantic属性は、最初のモーフターゲットの2法線ベクトルです。3成分:xyz

さらに、semantic は、IndexSemantic 。この場合、アトリビュートは頂点バッファのエントリを表すのではなく、インデックスバッファのインデックスデータを記述します。頂点ごとにインデックスは常に1つだけなので、offset はインデックスバッファとしては意味をなさないので、ゼロのままにしておくべきです。

コンポーネントタイプは以下のいずれかになります:

定数説明
U16Typeインデックスコンポーネントの型は符号なし16ビット整数です。IndexSemantic でのみサポートされる。
U32Type属性(またはインデックス・コンポーネント)は符号なし 32 ビット整数です。
I32Type属性は符号付き32ビット整数です。古いOpenGLのバージョン(2.1やOpenGL ES 2.0など)では、このデータ型がサポートされていない可能性があることに注意してください。
F32Type属性は単精度floatです。

注意: ジョイントインデックスデータは通常、I32TypeF32Type は、OpenGL ES 2.0のような整数頂点入力属性をサポートしないAPIでも機能するようにするためにサポートされています。

注: インデックスデータ(IndexSemantic)については、U16Type と U32Type のみがサポートされます。

Note: TargetXXXSemantics は非推奨となります。addTargetAttribute はモーフターゲットに使用できます。現在、これらのセマンティクスは後方互換性のためだけにサポートされています。これらのセマンティクスがaddTargetAttributesetTargetData と混在して使用された場合、その結果は保証されません。

void QQuick3DGeometry::addAttribute(const QQuick3DGeometry::Attribute &attribute)

これはオーバーロードされた関数です。

頂点属性の説明を追加します。各属性は、その属性の使用法と構成要素の数を指定するセマンティック、頂点内部での属性の位置への頂点からのオフセット、属性のデータ型とサイズを指定するcomponentTypeを持ちます。

void QQuick3DGeometry::addSubset(int offset, int count, const QVector3D &boundsMin, const QVector3D &boundsMax, const QString &name = {})

ジオメトリに新しいサブセットを追加します。サブセットを使用すると、ジオメトリの一部を異なるマテリアルでレンダリングできます。マテリアルはmodel で指定します。

ジオメトリがインデックス バッファを持つ場合、offsetcount はサブセット内のプリミティブ オフセットとインデックスのカウントです。ジオメトリが頂点バッファのみを持つ場合、オフセットは頂点オフセット、カウントはサブセット内の頂点数です。

境界boundsMin およびboundsMax は、ジオメトリの境界と同様にサブセットを囲む必要があります。また、サブセットはname を持つことができます。

[since 6.6] void QQuick3DGeometry::addTargetAttribute(quint32 targetId, QQuick3DGeometry::Attribute::Semantic semantic, int offset, int stride = 0)

morph 対象属性の説明を追加します。各アトリビュートは、そのアトリビュートが属するtargetId 、アトリビュートの用途と構成要素の数を指定するsemantic 、頂点から頂点内のアトリビュート位置までのoffset 、要素間のバイトサイズであるstride

注: targetIdは0から番号を飛ばすことなく増加させ、すべてのターゲットは同じ属性を持つべきである。

注: semanticは頂点属性と同じですが、IndexSemantic、JointSementic、WeightSemanticはターゲット属性では使用できません。

注: すべてのターゲット属性の componentTypes は F32Type でなければなりません。

注意 : stride が与えられていないか、0 以下の場合、属性は密にパックされていると見なされます。

この関数は Qt 6.6 で導入されました。

addAttributeも参照してください

[since 6.6] void QQuick3DGeometry::addTargetAttribute(const QQuick3DGeometry::TargetAttribute &attribute)

これはオーバーロードされた関数です。

morphのターゲット属性の説明を追加します。各属性は、属性の所属する targetId、属性の使用法と構成要素の数を指定する semantic、頂点から頂点内の属性位置までのオフセット、要素間のバイトサイズである stride を持ちます。

この関数は Qt 6.6 で導入されました。

QQuick3DGeometry::Attribute QQuick3DGeometry::attribute(int index) const

属性定義番号を返すindex

属性定義には 0 からattributeCount() - 1

int QQuick3DGeometry::attributeCount() const

このジオメトリに定義されている属性の数を返します。

attributeも参照してください

QVector3D QQuick3DGeometry::boundsMax() const

外接ボ リ ュームの最大座標を返 し ます。

setBoundsも参照してください

QVector3D QQuick3DGeometry::boundsMin() const

外接ボ リ ュームの最小座標を返 し ます。

setBoundsも参照してください

void QQuick3DGeometry::clear()

ジオメトリを初期状態にリセットし、それまで設定されていた頂点やインデックスのデータ、アトリビュートをクリアします。

QByteArray QQuick3DGeometry::indexData() const

インデックス・バッファのデータを返します。

setIndexData()も参照

QQuick3DGeometry::PrimitiveType QQuick3DGeometry::primitiveType() const

レンダリング時に使用するプリミティブ型を返します。デフォルトはTriangles です。

setPrimitiveTypeも参照してください

void QQuick3DGeometry::setBounds(const QVector3D &min, const QVector3D &max)

ジオメトリの外接体積を、点minmax で定義される立方体に設定します。これはpicking に使用されます。

void QQuick3DGeometry::setIndexData(const QByteArray &data)

インデックス・バッファをdata に設定します。 インデックス付き描画を使用するには、属性にIndexSemantic

indexData() およびaddAttributeも参照してください

void QQuick3DGeometry::setIndexData(int offset, const QByteArray &data)

これはオーバーロードされた関数である。

インデックス・バッファのサブセットを更新します。offset はオフセットをバイト単位で指定し、data はサイズとデータを指定します。

この関数はバッファのサイズを変更しません。offset + data.size() がバッファの現在のサイズより大きい場合、オーバーシュートしたデータは無視されます。

注意: 頂点、インデックス、およびモーフターゲットデータの部分更新関数は、そのような変更が内部的にどのように実装されるかについて保証するものではありません。基礎となる実装によっては、部分的な変更であってもグラフィックスリソース全体を更新することになる可能性があります。

void QQuick3DGeometry::setPrimitiveType(QQuick3DGeometry::PrimitiveType type)

レンダリングに使用するプリミティブタイプをtype に設定します。

定数説明
Pointsプリミティブは点です。
LineStripプリミティブはストリップのラインです。
Linesプリミティブはリスト内の線です。
TriangleStripプリミティブは、ストリップ内の三角形です。
TriangleFanプリミティブは扇形の三角形。基礎となるグラフィックスAPIによっては、三角形の扇形が実行時にサポートされない場合があることに注意してください。
Trianglesプリミティブはリスト内の三角形である。

初期値はTriangles

注: 三角形ファン(TriangleFan)は、基礎となるグラフィックスAPIによっては、実行時にサポートされない場合があることに注意してください。たとえば、Direct 3Dではこのトポロジーはまったく機能しません。

注記 :Pointsの点サイズと、LinesおよびLineStripの線幅は、material によって制御されます。ただし、基礎となるグラフィックスAPIによっては、1以外のサイズが実行時にサポートされない場合があることに注意してください。

primitiveType()も参照してください

void QQuick3DGeometry::setStride(int stride)

頂点バッファのストライドをstride に設定します。これは、バッファ内の連続する 2 つの頂点間の距離です。

たとえば、PositionSemanticIndexSemanticColorSemantic を使用するジオメトリの、ぎっしり詰まったインターリーブ頂点バッファのストライドは、28 になります (合計 7 つの浮動小数点数: 位置に 3 つ、色に 4 つ、頂点バッファに入らないインデックスに 1 つ)。

注: QQuick3DGeometry は、インターリーブされたアトリビュート・レイアウトを持つ頂点データを想定しており、それに対してのみ動作します。

stride() およびaddAttributeも参照してください

[since 6.6] void QQuick3DGeometry::setTargetData(const QByteArray &data)

モーフターゲットバッファdata を設定します。バッファはすべてのモーフターゲットデータを保持する必要があります。

この関数は Qt 6.6 で導入されました。

targetData() およびaddTargetAttributeも参照してください

[since 6.6] void QQuick3DGeometry::setTargetData(int offset, const QByteArray &data)

これはオーバーロードされた関数です。

モーフターゲットバッファのサブセットを更新します。offset はオフセットをバイト単位で指定し、data はサイズとデータを指定します。

この関数はバッファのサイズを変更しません。offset + data.size() がバッファの現在のサイズより大きい場合、オーバーシュートしたデータは無視されます。

注意: 頂点、インデックス、およびモーフターゲットデータの部分更新関数は、そのような変更が内部的にどのように実装されるかについて保証するものではありません。基本的な実装によっては、部分的な変更であってもグラフィックスリソース全体を更新することになるかもしれません。

この関数は Qt 6.6 で導入されました。

void QQuick3DGeometry::setVertexData(const QByteArray &data)

頂点バッファdata を設定します。このバッファは、アトリビュート定義で記述されているように、配列にパックされたすべての頂点データを保持する必要があります。これには、インデックスバッファに属するIndexSemantic のアトリビュートは含まれないことに注意してください。

vertexData(),addAttribute,setStride,setIndexDataも参照してください

void QQuick3DGeometry::setVertexData(int offset, const QByteArray &data)

これはオーバーロードされた関数です。

頂点バッファのサブセットを更新します。offset はオフセットをバイト単位で指定し、data はサイズとデータを指定します。

この関数はバッファのサイズを変更しません。offset + data.size() がバッファの現在のサイズより大きい場合、オーバーシュートしたデータは無視されます。

注意: 頂点、インデックス、モーフターゲットデータの部分更新関数は、そのような変更が内部的にどのように実装されるかを保証するものではありません。基本的な実装によっては、部分的な変更であってもグラフィックスリソース全体を更新することになる場合があります。

int QQuick3DGeometry::stride() const

頂点バッファのバイト列を返します。

setStrideも参照してください

QVector3D QQuick3DGeometry::subsetBoundsMax(int subset) const

subset の最大境界の数を返します。

subsetBoundsMinも参照のこと

QVector3D QQuick3DGeometry::subsetBoundsMin(int subset) const

subset の最小値の数を返します。

subsetBoundsMaxも参照

int QQuick3DGeometry::subsetCount() const

サブセットの数を返します。

int QQuick3DGeometry::subsetCount(int subset) const

サブセット・プリミティブ数を返します。

subsetOffsetも参照してください

QString QQuick3DGeometry::subsetName(int subset) const

subset の名前を返す。

int QQuick3DGeometry::subsetOffset(int subset) const

頂点バッファまたはインデックスバッファへのsubset オフセットを返します。

subsetCountも参照してください

[since 6.6] QQuick3DGeometry::TargetAttribute QQuick3DGeometry::targetAttribute(int index) const

morph 対象の属性定義番号を返します。index

属性定義には 0 からattributeCount() - 1

この関数は Qt 6.6 で導入されました。

[since 6.6] int QQuick3DGeometry::targetAttributeCount() const

このジオメトリに定義されているモーフターゲット属性の数を返します。

この関数は Qt 6.6 で導入されました。

targetAttributeも参照してください

[since 6.6] QByteArray QQuick3DGeometry::targetData() const

setTargetData によって設定されたターゲット・バッファ・データを返します。

この関数は Qt 6.6 で導入されました。

setTargetData()も参照してください

QByteArray QQuick3DGeometry::vertexData() const

setVertexData によって設定された頂点バッファデータを返します。

setVertexData()も参照してください

© 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.