QRhiVulkanInitParams Struct

詳細な説明

Vulkan ベースのQRhi には、少なくとも有効な `QVulkanInstance` が必要です。これが利用可能であり、初期化されていることを確認するのはユーザーの責任です。これは通常、次のように main() 内で実行されます。

int main(int argc, char **argv)
{
    ...

    QVulkanInstance inst;
    inst.setLayers({ "VK_LAYER_KHRONOS_validation" }); // for debugging only, not for release builds
    inst.setExtensions(QRhiVulkanInitParams::preferredInstanceExtensions());
    if (!inst.create())
        qFatal("Vulkan not available");

    ...
}

この例では、Vulkan 検証レイヤーが利用可能な場合にそれを有効にし、また、実行時に Vulkan 実装でサポートされている限り、QRhi が推奨として報告するインスタンスレベルの拡張機能（VK_KHR_get_physical_device_properties2 など）も有効にします。

前者はオプションであり、開発段階において有用です。QVulkanInstance は、メッセージや警告をqDebug に便利にリダイレクトします。ただし、本番ビルドではこれを有効にしないようにしてください。後者は強く推奨されており、特定の機能（例：QRhi::CustomInstanceStepRate ）を動作させるために重要です。

これが完了すると、インスタンスと、サーフェスタイプがQSurface::VulkanSurface に設定されたQWindow を引数として渡すことで、Vulkan ベースのQRhi を作成できます：

QRhiVulkanInitParams params;
params.inst = vulkanInstance;
params.window = window;
rhi = QRhi::create(QRhi::Vulkan, &params);

ウィンドウはオプションであり、省略することも可能です。ただし、その場合はグラフィックキューを選択する際に、プレゼンテーションがサポートされていることを保証する手段がなくなるため、この方法は推奨されません。

Vulkanデバイス上で追加の拡張機能を有効にするには、deviceExtensions 内にそれらを列挙します。これは、ネイティブのVulkanレンダリングコードと統合する際に重要になる場合があります。

QVulkanInstance を初期化する前に、静的関数preferredInstanceExtensions() を呼び出して、バックエンドが希望するインスタンス拡張機能のリストを照会することが想定されています。返されたリストは、サポートされていない拡張機能が自動的に除外されるため、そのままQVulkanInstance::setExtensions() に安全に渡すことができます。 これを行わない場合、システムのVulkan実装が関連する機能をサポートしているにもかかわらず、QRhi::CustomInstanceStepRate などの特定の機能がサポートされていないと報告される可能性があります。

すべての機能を利用するには、QVulkanInstance でAPI 1.1が利用可能な場合、それを有効にする必要があります。つまり、QVulkanInstance::supportedApiVersion()が少なくともVulkan 1.1がサポートされていると報告した場合は、常に1.1以上の値を指定してQVulkanInstance::setApiVersion()を呼び出す必要があります。 これを行わない場合、システムのVulkan実装がVulkan 1.1以降をサポートしていても、QRhi::RenderTo3DTextureSlice などの特定の機能がサポートされていないと報告される可能性があります。

既存のVulkanデバイスとの連携

他のグラフィックスエンジンと相互運用する場合、同じ Vulkan デバイスを使用する `QRhi ` インスタンスを取得する必要がある場合があります。これは、`QRhiVulkanNativeHandles ` へのポインタを `QRhi::create()` に渡すことで実現できます。

physical フィールドには常に null 以外の値を設定する必要があります。物理デバイスを指定するだけで、VkDevice およびキューの作成の残りをQRhi に任せる場合は、構造体の他のメンバを埋める必要はありません。たとえば、OpenXR を使用する場合がこれに該当します。

既存のVkDevice を採用する場合も、deviceフィールドはNULL以外の値に設定する必要があります。さらに、グラフィックスキューのファミリーインデックスも必須です。キューインデックスはオプションですが、デフォルトの0で十分な場合が多いため、通常は指定しなくて構いません。

オプションとして、既存のコマンドプールオブジェクトを指定することも可能です。また、vmemAllocatorを使用することで、2つのQRhi インスタンス間で同じVulkanメモリアロケータを共有することも可能です。

QRhi は、いかなる外部オブジェクトの所有権も取得しません。

アプリケーションでは、静的関数 `preferredExtensionsForImportedDevice()` を呼び出して必要なデバイス拡張機能のリストを取得し、`VkDevice` 上でそれらを有効にすることを推奨します。そうしないと、QRhi の特定の機能が利用できない場合があります。