QSGMaterial Class

メンバ関数のドキュメント

[virtual] int QSGMaterial::compare(const QSGMaterial *other) const

このマテリアルをother と比較し、等しい場合は 0 を返し、このマテリアルがother よりも先にソートされる場合は -1、other よりも先にソートされる場合は 1 を返します。

シーングラフはジオメトリノードを並べ替えることで、状態の変化を最小限に抑えることができる。compare 関数は、QSGMaterialShader::updateState() を呼び出すたびにマテリアルをソートして状態変化を最小化できるように、ソート処理中に呼び出されます。

このポインタとother は同じtype() であることが保証されます。

[pure virtual] QSGMaterialShader *QSGMaterial::createShader(QSGRendererInterface::RenderMode renderMode) const

この関数は、QSGMaterial の特定の実装に対してジオメトリをレンダリングするために使用されるQSGMaterialShader 実装の新しいインスタンスを返します。

この関数は、マテリアルタイプとrenderMode の組み合わせごとに一度だけ呼び出され、内部でキャッシュされます。

ほとんどのマテリアルではrenderMode は無視できます。いくつかのマテリアルは特定のレンダリングモードに対してカスタム処理が必要な場合があります。例えば、RenderMode3Dが使用されているときに、マテリアルがパースペクティブ変換を考慮する必要がある方法でアンチエイリアシングを実装している場合などです。

QSGMaterial::Flags QSGMaterial::flags() const

素材のフラグを返します。

void QSGMaterial::setFlag(QSGMaterial::Flags flags, bool on = true)

on が true の場合、この素材にフラグflags を設定します。そうでない場合、属性はクリアされます。

[pure virtual] QSGMaterialType *QSGMaterial::type() const

この関数はシーングラフによって呼び出され、createShader()によってインスタンス化されたQSGMaterialShader に固有の識別子を問い合わせる。

多くのマテリアルの場合、典型的なアプローチは、静的な、つまりグローバルに利用可能な、QSGMaterialType インスタンスへのポインタを返すことです。QSGMaterialType は不透明なオブジェクトです。その目的は、一意な材料識別子を生成するための、型安全で単純な方法としての役割を果たすことだけです。

QSGMaterialType *type() const override
{
    static QSGMaterialType type;
    return &type;
}

[since 6.8] int QSGMaterial::viewCount() const

戻り値 マテリアルがマルチビューレンダリングで使用される場合のビュー数。

通常、戻り値は1 である。ビューカウントが 2 より大きい場合は、マルチビューレンダーパスを意味します。マルチビューをサポートするマテリアルは、createShader() 内、またはQSGMaterialShader コンストラクタ内で viewCount() を照会し、適切なシェーダが選択されるようにします。バーテックスシェーダは、マルチビューモードでは複数の行列があるため、gl_ViewIndex を使用してモデルビュー-投影行列配列にインデックスを付けることが期待されます。(各ビューに1つずつ）。

例として、次のような単純な頂点シェーダを見てみましょう：

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
    mat4 matrix[2];
    float opacity;
};

void main()
{
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
    color = vertexColor * opacity;
}

このシェーダは、2 つのビュー、および 2 つのビューだけを扱うように準備 されています。他のビュー数には対応していません。シェーダのコンディショニングを行う場合、--view-count 2 でqsb ツールを起動するか、CMake インテグレーションを使用する場合は、qt_add_shaders() コマンドでVIEW_COUNT 2 を指定する必要があります。

開発者は、自動的に注入されるプリプロセッサー変数QSHADER_VIEW_COUNT を使用して、異なるビュー数の取り扱いを簡素化することが推奨されます。例えば、同じソース・ファイルで、ビュー数が2の非マルチビューとマルチビューの両方をサポートする必要がある場合、次のようにすることができます：

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
#if QSHADER_VIEW_COUNT >= 2
    mat4 matrix[QSHADER_VIEW_COUNT];
#else
    mat4 matrix;
#endif
    float opacity;
};

void main()
{
#if QSHADER_VIEW_COUNT >= 2
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
#else
    gl_Position = matrix * vertexCoord;
#endif
    color = vertexColor * opacity;
}

同じソースファイルをqsb またはqt_add_shaders() で2回実行することができます。1回目はビュー数を指定せずに、もう1回目はビュー数を2に設定して実行します。

CMakeを使用すると、次のようになります。この例では、対応するQSGMaterialShader は、viewCount()の値に基づいて:/shaders/example.vert.qsb と:/shaders/multiview/example.vert.qsb のどちらかを選択することになります。(フラグメントシェーダも同様です。）

qt_add_shaders(application "application_shaders"
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

qt_add_shaders(application "application_multiview_shaders"
    GLSL
        330,300es
    HLSL
        61
    MSL
        12
    VIEW_COUNT
        2
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
    OUTPUTS
        shaders/multiview/example.vert
        shaders/multiview/example.frag
)

便宜上、qt_add_shaders() にはMULTIVIEW オプションもあります。これはまずqsb ツールを通常通り実行し、次にVIEW_COUNT を2 にオーバーライドし、GLSL 、HLSL 、MSL を適切なデフォルトに設定し、qsb を再度実行します。材料実装は、viewCount 引数を取るQSGMaterialShader::setShaderFileName() オーバーロードを使用することができ、自動的に正しい .qsb ファイルを選択します。

従って、手動で管理する出力ファイルを指定する必要がないことを除けば、以下は上記の呼び出し例とほぼ同じです。自動的に選択されたシェーディング言語バージョンでは十分でない場合があることに注意してください。

qt_add_shaders(application "application_multiview_shaders"
    MULTIVIEW
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

Qt のマルチビュー・サポートに関する下位レベルの詳細については、QRhi::MultiView 、QRhiColorAttachment::setMultiViewCount()、QRhiGraphicsPipeline::setMultiViewCount() を参照してください。QQuickRenderTarget::fromRhiRenderTarget() や、fromVulkanImage() のような 3D API 固有の関数で、arraySize の引数が 1 より大きい場合に指定されます。Qt Quick シーングラフレンダラは、マルチビューレンダリングターゲットを認識するように準備されています。レンダラーは、ビューカウントをグラフィックスパイプラインとマテリアルに伝搬します。

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