QSGMaterial Class

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

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

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

シーングラフは、状態変更を最小限に抑えるためにジオメトリノードの順序を変更することができます。比較関数はソート処理中に呼び出され、これにより、QSGMaterialShader::updateState() の各呼び出しにおける状態変更を最小限に抑えるようにマテリアルをソートすることができます。

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

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

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

この関数は、マテリアルタイプとrenderMode の各組み合わせに対して1回のみ呼び出され、内部でキャッシュされます。

ほとんどのマテリアルでは、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つのビューのみを処理するように準備されています。他のビュー数とは互換性がありません。シェーダーを条件付きで生成する際は、qsb ツールに対して `--view-count 2 ` を指定するか、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 に設定した場合の 2 回実行できるようになります。これにより、マテリアルは実行時に viewCount() に基づいて適切な .qsb ファイルを選択できるようになります。

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 ` を実行します。この際、拡張子が付加された `.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() を参照してください。Qt Quick シーングラフ・レンダラーは、QQuickRenderTarget::fromRhiRenderTarget() または、arraySize 引数が 1 より大きいfromVulkanImage() などの 3D API 固有の関数を介して指定された場合、マルチビューのレンダリングターゲットを認識できるようになっています。 これにより、レンダラーはビューカウントをグラフィックスパイプラインおよびマテリアルに伝播します。

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