QVulkanWindow Class

Dokumentation der Mitgliedsfunktionen

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

Konstruiert ein neues QVulkanWindow mit der angegebenen parent.

Der Oberflächentyp wird auf QSurface::VulkanSurface gesetzt.

[virtual noexcept] QVulkanWindow::~QVulkanWindow()

Zerstörer.

QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()

Gibt die Liste der Eigenschaften für die unterstützten physischen Geräte im System zurück.

QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()

Gibt eine QMatrix4x4 zurück, die zur Korrektur von Koordinatensystemunterschieden zwischen OpenGL und Vulkan verwendet werden kann.

Durch Vormultiplikation der Projektionsmatrix mit dieser Matrix können Anwendungen weiterhin davon ausgehen, dass Y nach oben zeigt, und können minDepth und maxDepth im Ansichtsfenster auf 0 bzw. 1 setzen, ohne weitere Korrekturen an den Vertex-Z-Positionen vornehmen zu müssen. Geometrien aus OpenGL-Anwendungen können dann so verwendet werden, wie sie sind, unter der Annahme, dass der Rasterungszustand mit den OpenGL-Culling- und Frontflächeneinstellungen übereinstimmt.

VkFormat QVulkanWindow::colorFormat() const

Gibt das von der Swapchain verwendete Farbpufferformat zurück.

Siehe auch setPreferredColorFormats().

int QVulkanWindow::concurrentFrameCount() const

Gibt die Anzahl der Frames zurück, die potenziell gleichzeitig aktiv sein können.

    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] = ...
        // ...
    }

Siehe auch currentFrame().

[virtual] QVulkanWindowRenderer *QVulkanWindow::createRenderer()

Gibt eine neue Instanz von QVulkanWindowRenderer zurück.

Diese virtuelle Funktion wird einmal während der Lebensdauer des Fensters aufgerufen, und zwar zu einem Zeitpunkt, nachdem es zum ersten Mal sichtbar gemacht wurde.

Die Standardimplementierung gibt null zurück, so dass außer dem Löschen der Puffer kein Rendering durchgeführt wird.

Das Fenster übernimmt das Eigentum an dem zurückgegebenen Renderer-Objekt.

VkCommandBuffer QVulkanWindow::currentCommandBuffer() const

Gibt den aktiven Befehlspuffer für das aktuelle Swap-Chain-Image zurück. Es wird erwartet, dass Implementierungen von QVulkanWindowRenderer::startNextFrame() Befehle zu diesem Befehlspuffer hinzufügen.

int QVulkanWindow::currentFrame() const

Gibt den aktuellen Frame-Index im Bereich [0, concurrentFrameCount() - 1] zurück.

Renderer-Implementierungen müssen sicherstellen, dass einheitliche Daten und andere dynamische Ressourcen in mehreren Kopien vorhanden sind, um zu verhindern, dass Frame N die Daten verändert, die von den noch aktiven Frames N - 1, N - 2, ... N - concurrentFrameCount() + 1.

Um sich nicht auf dynamische Array-Größen zu verlassen, können Anwendungen MAX_CONCURRENT_FRAME_COUNT verwenden, wenn sie Arrays deklarieren. Diese ist garantiert immer gleich oder größer als der von concurrentFrameCount() zurückgegebene Wert. Solche Arrays können dann durch den von dieser Funktion zurückgegebenen Wert indiziert werden.

    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()]);
        // ...
    }

Siehe auch concurrentFrameCount().

VkFramebuffer QVulkanWindow::currentFramebuffer() const

Gibt einen VkFramebuffer für das aktuelle Swapchain-Bild unter Verwendung des Standard-Renderpasses zurück.

Der Framebuffer hat zwei Anhänge (color, depth-stencil), wenn kein Multisampling verwendet wird, und drei (color resolve, depth-stencil, multisample color), wenn sampleCountFlagBits() größer als VK_SAMPLE_COUNT_1_BIT ist. Renderer müssen dies berücksichtigen, z. B. bei der Bereitstellung von clear-Werten.

Siehe auch defaultRenderPass().

int QVulkanWindow::currentSwapChainImageIndex() const

Gibt den aktuellen Swap-Chain-Bildindex im Bereich [0, swapChainImageCount() - 1] zurück.

VkRenderPass QVulkanWindow::defaultRenderPass() const

Gibt einen typischen Rendering-Pass mit einem Sub-Pass zurück.

Siehe auch currentFramebuffer().

VkFormat QVulkanWindow::depthStencilFormat() const

Gibt das von den Tiefenschablonenpuffern verwendete Format zurück.

VkImage QVulkanWindow::depthStencilImage() const

Gibt das Tiefenschablonenbild zurück.

VkImageView QVulkanWindow::depthStencilImageView() const

Gibt die Ansicht des Tiefenschablonenbildes zurück.

VkDevice QVulkanWindow::device() const

Gibt das aktive logische Gerät zurück.

uint32_t QVulkanWindow::deviceLocalMemoryIndex() const

Gibt einen Index des lokalen Speichertyps des Geräts zurück, der für den allgemeinen Gebrauch geeignet ist.

QVulkanWindow::Flags QVulkanWindow::flags() const

Gibt die angeforderten Flags zurück.

Siehe auch setFlags().

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

Dieses Signal wird ausgesendet, wenn die image bereit ist.

void QVulkanWindow::frameReady()

Diese Funktion muss genau einmal als Reaktion auf jeden Aufruf der Implementierung QVulkanWindowRenderer::startNextFrame() aufgerufen werden. Zum Zeitpunkt dieses Aufrufs müssen dem Hauptbefehlspuffer, der über currentCommandBuffer() zugänglich ist, alle erforderlichen Rendering-Befehle hinzugefügt worden sein, da diese Funktion die Übermittlung der Befehle und die Einreihung des aktuellen Befehls in die Warteschlange auslöst.

Siehe auch QVulkanWindowRenderer::startNextFrame().

QImage QVulkanWindow::grab()

Erstellt und rendert das nächste Bild, ohne es zu präsentieren, und führt dann ein blockierendes Zurücklesen des Bildinhalts durch.

Gibt das Bild zurück, wenn die startNextFrame()-Implementierung des Renderers frameReady() direkt zurückruft. Andernfalls wird ein unvollständiges Bild zurückgegeben, das zwar die richtige Größe, aber noch nicht den Inhalt hat. Der Inhalt wird im letzteren Fall über das Signal frameGrabbed() geliefert.

Das zurückgegebene QImage hat immer das Format QImage::Format_RGBA8888. Wenn colorFormat() VK_FORMAT_B8G8R8A8_UNORM ist, werden die roten und blauen Kanäle automatisch vertauscht, da dieses Format üblicherweise als Standard für Swapchain-Farbpuffer verwendet wird. Bei allen anderen Farbpufferformaten wird von dieser Funktion keine Konvertierung durchgeführt.

VkCommandPool QVulkanWindow::graphicsCommandPool() const

Gibt den aktiven Grafik-Befehlspool zurück.

VkQueue QVulkanWindow::graphicsQueue() const

Gibt die aktive Grafikwarteschlange zurück.

uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const

Gibt den Familienindex der aktiven Grafikwarteschlange zurück.

uint32_t QVulkanWindow::hostVisibleMemoryIndex() const

Gibt einen für den Host sichtbaren Speichertyp-Index zurück, der für den allgemeinen Gebrauch geeignet ist.

Der zurückgegebene Speichertyp ist sowohl für den Host sichtbar als auch kohärent. Darüber hinaus wird er, wenn möglich, im Cache gespeichert.

bool QVulkanWindow::isValid() const

Gibt true zurück, wenn dieses Fenster erfolgreich alle Vulkan-Ressourcen, einschließlich der Swapchain, initialisiert hat.

VkImage QVulkanWindow::msaaColorImage(int idx) const

Gibt das angegebene Multisample-Farbbild zurück, oder VK_NULL_HANDLE, wenn Multisampling nicht verwendet wird.

idx muss im Bereich [0, swapChainImageCount() - 1] liegen.

VkImageView QVulkanWindow::msaaColorImageView(int idx) const

Gibt die angegebene Multisample-Farbbildansicht zurück, oder VK_NULL_HANDLE, wenn Multisampling nicht verwendet wird.

idx muss im Bereich [0, swapChainImageCount() - 1] liegen.

VkPhysicalDevice QVulkanWindow::physicalDevice() const

Gibt das aktive physische Gerät zurück.

const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const

Gibt einen Zeiger auf die Eigenschaften des aktiven physischen Geräts zurück.

VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const

Gibt die aktuelle Anzahl der Proben als Wert VkSampleCountFlagBits zurück.

Wenn Sie das Standard-Rendering-Ziel anvisieren, muss das Feld rasterizationSamples von VkPipelineMultisampleStateCreateInfo auf diesen Wert gesetzt werden.

Siehe auch setSampleCount() und supportedSampleCounts().

void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)

Legt die Liste der zu aktivierenden Geräte extensions fest.

Nicht unterstützte Erweiterungen werden ignoriert.

Die Swapchain-Erweiterung wird immer automatisch hinzugefügt, es ist nicht nötig, sie in diese Liste aufzunehmen.

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

Legt die Modifikationsfunktion modifier für die aktivierten Gerätefunktionen fest.

Diese Funktion wurde in Qt 6.7 eingeführt.

Siehe auch EnabledFeaturesModifier.

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

Legt die Funktion zur Änderung der aktivierten Geräteeigenschaften fest modifier.

Dies ist eine überladene Funktion.

Diese Funktion wurde in Qt 6.7 eingeführt.

Siehe auch EnabledFeatures2Modifier.

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

Konfiguriert das Verhalten auf der Grundlage der angegebenen flags.

Siehe auch flags().

void QVulkanWindow::setPhysicalDeviceIndex(int idx)

Fordert die Verwendung des physischen Geräts mit dem Index idx an. Der Index entspricht der Liste, die von availablePhysicalDevices() zurückgegeben wird.

Standardmäßig wird das erste physische Gerät verwendet.

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

Legt das bevorzugte formats der Swapchain fest.

Standardmäßig ist kein von der Anwendung bevorzugtes Format eingestellt. In diesem Fall wird das bevorzugte Format der Oberfläche verwendet oder, falls dies nicht der Fall ist, VK_FORMAT_B8G8R8A8_UNORM.

Die Liste in formats ist geordnet. Wenn das erste Format nicht unterstützt wird, wird das zweite berücksichtigt, usw. Wenn keine Formate in der Liste unterstützt werden, ist das Verhalten das gleiche wie im Standardfall.

Um das aktuelle Format nach der Initialisierung abzufragen, rufen Sie colorFormat() auf.

Siehe auch colorFormat().

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

Legt die Funktion zur Änderung der Warteschlangeninfo fest modifier.

Siehe auch QueueCreateInfoModifier.

void QVulkanWindow::setSampleCount(int sampleCount)

Fordert Multisample-Antialiasing mit dem angegebenen sampleCount an. Die gültigen Werte sind 1, 2, 4, 8, ... bis zum maximalen Wert, der vom physikalischen Gerät unterstützt wird.

Wenn die Anzahl der Samples größer als 1 ist, erstellt QVulkanWindow einen Multisample-Farbpuffer, anstatt einfach die Bilder der Swapchain zu verwenden. Das Rendering im Multisample-Puffer wird am Ende eines jeden Frames in die Nicht-Multisample-Puffer aufgelöst.

Um die Liste der unterstützten Abtastwerte zu prüfen, rufen Sie supportedSampleCounts() auf.

Rufen Sie beim Einrichten der Rendering-Pipeline sampleCountFlagBits() auf, um die aktive Sampleanzahl als VkSampleCountFlagBits Wert abzufragen.

Siehe auch supportedSampleCounts() und sampleCountFlagBits().

QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()

Gibt die Liste der Erweiterungen zurück, die von logischen Geräten unterstützt werden, die aus dem mit setPhysicalDeviceIndex() ausgewählten physischen Gerät erstellt wurden.

QList<int> QVulkanWindow::supportedSampleCounts()

Gibt die Menge der unterstützten Abtastwerte bei Verwendung des von setPhysicalDeviceIndex() ausgewählten physischen Geräts in Form einer sortierten Liste zurück.

Standardmäßig verwendet QVulkanWindow einen Abtastwert von 1. Durch Aufruf von setSampleCount() mit einem anderen Wert (2, 4, 8, ...) aus der von dieser Funktion zurückgegebenen Menge kann Multisample-Anti-Aliasing angefordert werden.

Siehe auch setSampleCount().

bool QVulkanWindow::supportsGrab() const

Gibt true zurück, wenn die Swapchain die Verwendung als Transferquelle unterstützt, d. h. grab() ist funktionsfähig.

VkImage QVulkanWindow::swapChainImage(int idx) const

Gibt das angegebene Bild der Tauschkette zurück.

idx muss im Bereich [0, swapChainImageCount() - 1] liegen.

int QVulkanWindow::swapChainImageCount() const

Gibt die Anzahl der Bilder in der Auslagerungskette zurück.

QSize QVulkanWindow::swapChainImageSize() const

Gibt die Bildgröße der Swapchain zurück.

Diese stimmt normalerweise mit der Größe des Fensters überein, kann aber auch abweichen, wenn vkGetPhysicalDeviceSurfaceCapabilitiesKHR eine feste Größe meldet.

Darüber hinaus wurde auf einigen Plattformen beobachtet, dass die von Vulkan gemeldete Oberflächengröße bei aktivierter hoher DPI-Skalierung abweicht, was bedeutet, dass der von QWindow gemeldete Wert size() multipliziert mit devicePixelRatio() um 1 Pixel kleiner oder größer ist als der von hier zurückgegebene Wert, vermutlich aufgrund von Rundungsunterschieden. Der Rendering-Code sollte sich dessen bewusst sein, und jede damit zusammenhängende Rendering-Logik muss auf dem von hier zurückgegebenen Wert basieren, niemals auf der von QWindow gemeldeten Größe. Unabhängig davon, welche Pixelgröße theoretisch korrekt ist, darf sich das Vulkan-Rendering immer nur auf die von der Vulkan-API gemeldete Oberflächengröße stützen. Andernfalls kann es zu Validierungsfehlern kommen, z. B. beim Setzen des Ansichtsfensters, weil die von der Anwendung bereitgestellten Werte aus Sicht von Vulkan nicht mehr zulässig sind.

VkImageView QVulkanWindow::swapChainImageView(int idx) const

Gibt die angegebene Bildansicht der Tauschkette zurück.

idx muss im Bereich [0, swapChainImageCount() - 1] liegen.