QVulkanWindow Class

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

[explicit] QVulkanWindow::QVulkanWindow(QWindow *parent = nullptr)

指定されたparent を使用して、新しいQVulkanWindowを構築します。

サーフェスタイプはQSurface::VulkanSurface に設定されます。

[virtual noexcept] QVulkanWindow::~QVulkanWindow()

デストラクタ。

QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()

システムでサポートされている物理デバイスのプロパティ一覧を返します。

QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()

OpenGLとVulkan間の座標系の違いを補正するために使用できるQMatrix4x4 を返します。

投影行列にこの行列を前乗算することで、アプリケーションはY軸が上向きであることを引き続き前提とでき、頂点のZ座標に対してそれ以上の補正を行うことなく、ビューポート内のminDepthとmaxDepthをそれぞれ0と1に設定できます。 これにより、OpenGLのカリングおよび前面面設定と一致するラスタライズ状態を前提として、OpenGLアプリケーションからのジオメトリをそのまま使用することができます。

VkFormat QVulkanWindow::colorFormat() const

スワップチェーンで使用されているカラーバッファ形式を返します。

setPreferredColorFormats()も参照してください 。

int QVulkanWindow::concurrentFrameCount() const

同時にアクティブになり得るフレームの数を返します。

    class Renderer {
        void startNextFrame();
        // ...

        VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
        QVulkanWindow *m_window = nullptr;
    };

    void Renderer::startNextFrame()
    {
        const int count = m_window->concurrentFrameCount();
        // for (int i = 0; i < count; ++i)
            // m_uniformBufInfo[i] = ...
        // ...
    }

関連項目：currentFrame()も参照してください 。

[virtual] QVulkanWindowRenderer *QVulkanWindow::createRenderer()

QVulkanWindowRenderer の新しいインスタンスを返します。

この仮想関数は、ウィンドウの存続期間中に、ウィンドウが初めて表示された後のある時点で一度呼び出されます。

デフォルトの実装は null を返すため、バッファのクリア以外にはレンダリングは行われません。

ウィンドウは、返されたレンダラーオブジェクトの所有権を取得します。

VkCommandBuffer QVulkanWindow::currentCommandBuffer() const

現在のスワップチェーンフレームのアクティブなコマンドバッファを返します。QVulkanWindowRenderer::startNextFrame() の実装では、このコマンドバッファにコマンドを追加することが想定されています。

int QVulkanWindow::currentFrame() const

[0,concurrentFrameCount() - 1] の範囲内の現在のフレームインデックスを返します。

レンダラーの実装では、フレーム N が、まだアクティブなフレーム N - 1、N - 2、...、N -concurrentFrameCount() + 1 で使用されているデータを上書きしないようにするため、ユニフォームデータやその他の動的リソースが複数のコピーで存在することを保証する必要があります。

動的配列のサイズに依存することを避けるため、アプリケーションは配列を宣言する際に `MAX_CONCURRENT_FRAME_COUNT ` を使用できます。これは、concurrentFrameCount() から返される値以上であることが保証されています。このような配列は、この関数から返される値によってインデックス付けできます。

    class Renderer {
        void startNextFrame();
        // ...

        VkDescriptorBufferInfo m_uniformBufInfo[QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT];
        QVulkanWindow *m_window = nullptr;
    };

    void Renderer::startNextFrame()
    {
        VkDescriptorBufferInfo &uniformBufInfo(m_uniformBufInfo[m_window->currentFrame()]);
        // ...
    }

関連項目: concurrentFrameCount()。

VkFramebuffer QVulkanWindow::currentFramebuffer() const

デフォルトのレンダリングパスを使用して、現在のスワップチェーン画像に対する VkFramebuffer を返します。

マルチサンプリングが使用されていない場合、このフレームバッファには 2 つのアタッチメント（color、depth-stencil）があり、sampleCountFlagBits() がVK_SAMPLE_COUNT_1_BIT より大きい場合は 3 つ（color resolve、depth-stencil、multisample color）になります。レンダラーは、例えばクリア値を指定する際などに、この点を考慮する必要があります。

defaultRenderPass()も参照してください 。

int QVulkanWindow::currentSwapChainImageIndex() const

[0,swapChainImageCount() - 1] の範囲内の、現在のスワップチェーン画像インデックスを返します。

VkRenderPass QVulkanWindow::defaultRenderPass() const

1つのサブパスを含む標準的なレンダリングパスを返します。

currentFramebuffer()も参照してください 。

VkFormat QVulkanWindow::depthStencilFormat() const

深度・ステンシルバッファで使用されているフォーマットを返します。

VkImage QVulkanWindow::depthStencilImage() const

深度・ステンシル画像を返します。

VkImageView QVulkanWindow::depthStencilImageView() const

深度・ステンシル画像ビューを返します。

VkDevice QVulkanWindow::device() const

アクティブな論理デバイスを返します。

uint32_t QVulkanWindow::deviceLocalMemoryIndex() const

汎用的に使用できるデバイスのローカルメモリ型インデックスを返します。

QVulkanWindow::Flags QVulkanWindow::flags() const

指定されたフラグを返します。

setFlags()も参照してください 。

[signal] void QVulkanWindow::frameGrabbed(const QImage &image)

この信号は、image が準備完了状態になったときに送信されます。

void QVulkanWindow::frameReady()

この関数は、QVulkanWindowRenderer::startNextFrame() の実装が呼び出されるたびに、厳密に 1 回だけ呼び出される必要があります。この呼び出しの時点では、currentCommandBuffer() を通じて公開されているメインコマンドバッファに、必要なすべてのレンダリングコマンドが追加されている必要があります。これは、この関数がコマンドの送信と現在のコマンドのキューへの追加をトリガーするためです。

QVulkanWindowRenderer::startNextFrame()も参照してください 。

QImage QVulkanWindow::grab()

次のフレームを構築してレンダリングしますが、画面には表示せず、その後、画像コンテンツのブロッキング読み取りを行います。

レンダラーのstartNextFrame()の実装がframeReady()を直接呼び戻す場合、画像を返します。それ以外の場合は、正しいサイズを持つものの、まだコンテンツが含まれていない不完全な画像を返します。後者の場合、コンテンツはframeGrabbed()シグナルを介して配信されます。

返されるQImage は、常にQImage::Format_RGBA8888 のフォーマットを持ちます。colorFormat()がVK_FORMAT_B8G8R8A8_UNORM の場合、このフォーマットはスワップチェーンのカラーバッファのデフォルトとして一般的に使用されるため、赤チャンネルと青チャンネルは自動的に入れ替えられます。その他のカラーバッファフォーマットの場合、この関数による変換は行われません。

VkCommandPool QVulkanWindow::graphicsCommandPool() const

アクティブなグラフィックスコマンドプールを返します。

VkQueue QVulkanWindow::graphicsQueue() const

アクティブなグラフィックキューを返します。

uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const

アクティブなグラフィックス・キューのファミリー・インデックスを返します。

uint32_t QVulkanWindow::hostVisibleMemoryIndex() const

汎用的に使用できる、ホストから可視なメモリ型インデックスを返します。

返されるメモリ型は、ホスト可視かつコヒーレントである。さらに、可能であればキャッシュされる。

bool QVulkanWindow::isValid() const

このウィンドウが、スワップチェーンを含むすべてのVulkanリソースの初期化に成功した場合、trueを返します。

VkImage QVulkanWindow::msaaColorImage(int idx) const

指定されたマルチサンプルカラー画像を返します。マルチサンプリングが使用されていない場合は、VK_NULL_HANDLE を返します。

idx は [0,swapChainImageCount() - 1] の範囲内である必要があります。

VkImageView QVulkanWindow::msaaColorImageView(int idx) const

指定されたマルチサンプルカラー画像ビューを返します。マルチサンプリングが使用されていない場合は、VK_NULL_HANDLE を返します。

idx は [0,swapChainImageCount() - 1] の範囲内である必要があります。

VkPhysicalDevice QVulkanWindow::physicalDevice() const

アクティブな物理デバイスを返します。

const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const

アクティブな物理デバイスのプロパティへのポインタを返します。

VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const

現在のサンプル数をVkSampleCountFlagBits 値として返します。

デフォルトのレンダリングターゲットを指定する場合、VkPipelineMultisampleStateCreateInfo のrasterizationSamples フィールドをこの値に設定する必要があります。

setSampleCount() およびsupportedSampleCounts()も参照してください 。

void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)

有効にするデバイスextensions のリストを設定します。

サポートされていない拡張機能は無視されます。

swapchain 拡張機能は常に自動的に追加されるため、このリストに含める必要はありません。

[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier)

有効なデバイスの機能変更関数 `modifier` を設定します。

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

「EnabledFeaturesModifier」も参照してください 。

[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(QVulkanWindow::EnabledFeatures2Modifier modifier)

有効なデバイスの機能変更関数 `modifier` を設定します。

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

EnabledFeatures2Modifierも参照してください 。

void QVulkanWindow::setFlags(QVulkanWindow::Flags flags)

指定されたflags に基づいて動作を設定します。

flags()も参照してください 。

void QVulkanWindow::setPhysicalDeviceIndex(int idx)

インデックスがidx の物理デバイスの使用を要求します。このインデックスは、availablePhysicalDevices() から返されるリストに対応しています。

デフォルトでは、最初の物理デバイスが使用されます。

void QVulkanWindow::setPreferredColorFormats(const QList<VkFormat> &formats)

スワップチェーンの優先形式（formats ）を設定します。

デフォルトでは、アプリケーションが優先するフォーマットは設定されていません。この場合、サーフェスの優先フォーマットが使用されます。優先フォーマットが存在しない場合は、VK_FORMAT_B8G8R8A8_UNORM が使用されます。

formats 内のリストは順序付きです。最初のフォーマットがサポートされていない場合は、2番目のフォーマットが検討され、以下同様に処理されます。リスト内のどのフォーマットもサポートされていない場合、その動作はデフォルトの場合と同じになります。

初期化後に実際のフォーマットを照会するには、colorFormat() を呼び出します。

colorFormat()も参照してください 。

void QVulkanWindow::setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier)

キュー作成情報の変更関数 `modifier` を設定します。

「QueueCreateInfoModifier」も参照してください 。

void QVulkanWindow::setSampleCount(int sampleCount)

指定されたsampleCount を使用して、マルチサンプルアンチエイリアシングを要求します。有効な値は、1、2、4、8、……と続き、物理デバイスがサポートする最大値までです。

サンプル数が 1 より大きい場合、QVulkanWindow は、単にスワップチェーンの画像をターゲットにするのではなく、マルチサンプルカラーバッファを作成します。マルチサンプルバッファ内でのレンダリングは、各フレームの終了時に非マルチサンプルバッファに変換されます。

サポートされているサンプル数のリストを確認するには、supportedSampleCounts() を呼び出します。

レンダリングパイプラインを設定する際は、sampleCountFlagBits() を呼び出して、アクティブなサンプル数を `VkSampleCountFlagBits ` 値として取得してください。

supportedSampleCounts() およびsampleCountFlagBits()も参照してください 。

QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()

setPhysicalDeviceIndex() で選択された物理デバイスから作成された論理デバイスがサポートする拡張機能のリストを返します。

QList<int> QVulkanWindow::supportedSampleCounts()

setPhysicalDeviceIndex() で選択された物理デバイスを使用する際にサポートされているサンプルカウントの集合を、ソート済みのリストとして返します。

デフォルトでは、QVulkanWindow はサンプル数を1に設定します。この関数が返すセットとは異なる値（2、4、8、...）を指定してsetSampleCount()を呼び出すことで、マルチサンプルアンチエイリアシングを要求できます。

setSampleCount()も参照してください 。

bool QVulkanWindow::supportsGrab() const

スワップチェーンが転送元としての使用に対応している場合（つまり、grab() が機能する場合）、true を返します。

VkImage QVulkanWindow::swapChainImage(int idx) const

指定されたスワップチェーンイメージを返します。

idx 値は [0,swapChainImageCount() - 1] の範囲内である必要があります。

int QVulkanWindow::swapChainImageCount() const

スワップチェーン内の画像数を返します。

QSize QVulkanWindow::swapChainImageSize() const

スワップチェーンの画像サイズを返します。

これは通常、ウィンドウのサイズと一致しますが、vkGetPhysicalDeviceSurfaceCapabilitiesKHR が固定サイズを報告している場合には異なる場合があります。

さらに、一部のプラットフォームでは、高DPIスケーリングが有効になっている場合、Vulkanが報告するサーフェスサイズが異なることが確認されています。つまり、QWindow が報告するsize()にdevicePixelRatio()を乗じた値は、丸め処理の違いによるものと思われるが、ここから返される値と比較して1ピクセル少ないか多いことになります。 レンダリングコードはこの点に留意する必要があり、関連するレンダリングロジックはすべて、ここで返される値に基づいており、決してQWindow で報告されるサイズに基づいてはなりません。理論上どちらのピクセルサイズが正しいかに関わらず、Vulkan レンダリングでは常に Vulkan API が報告するサーフェスサイズのみに依存しなければなりません。 そうしないと、例えばビューポートの設定時などに、Vulkanの観点からアプリケーションが提供する値が範囲外となるため、検証エラーが発生する可能性があります。

VkImageView QVulkanWindow::swapChainImageView(int idx) const

指定されたスワップチェーンイメージビューを返します。

idx 値は [0,swapChainImageCount() - 1] の範囲内でなければなりません。