QVulkanWindow Class

Dokumentation zu den Mitgliedsfunktionen

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

Erstellt ein neues `QVulkanWindow` mit dem angegebenen ` parent`.

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

[virtual noexcept] QVulkanWindow::~QVulkanWindow()

Destruktor.

QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()

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

QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()

Gibt eine „ QMatrix4x4 “ zurück, mit der Koordinatensystemunterschiede zwischen OpenGL und Vulkan ausgeglichen werden können.

Durch Vormultiplikation der Projektionsmatrix mit dieser Matrix können Anwendungen weiterhin davon ausgehen, dass Y nach oben zeigt, und minDepth sowie maxDepth im Ansichtsfenster auf 0 bzw. 1 setzen, ohne weitere Korrekturen an den Z-Positionen der Scheitelpunkte vornehmen zu müssen. Geometrie aus OpenGL-Anwendungen kann dann unverändert verwendet werden, vorausgesetzt, der Rasterisierungszustand stimmt mit den OpenGL-Einstellungen für Culling und Front Face überein.

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, sodass außer dem Leeren der Puffer keine Darstellung erfolgt.

Das Fenster übernimmt die Verantwortung für das zurückgegebene Renderer-Objekt.

VkCommandBuffer QVulkanWindow::currentCommandBuffer() const

Gibt den aktiven Befehlspuffer für den aktuellen Swap-Chain-Frame zurück. Von Implementierungen von ` QVulkanWindowRenderer::startNextFrame()` wird erwartet, dass sie diesem Befehlspuffer Befehle 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 verwendet werden.

Um nicht auf dynamische Array-Größen angewiesen zu sein, können Anwendungen bei der Deklaration von Arrays ` MAX_CONCURRENT_FRAME_COUNT ` verwenden. Es ist garantiert, dass dieser Wert immer gleich oder größer als der von ` concurrentFrameCount()` zurückgegebene Wert ist. Solche Arrays können dann anhand des von dieser Funktion zurückgegebenen Werts 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-Render-Passes zurück.

Der Framebuffer verfügt über zwei Attachments (Farbe, Tiefe-Stencil), wenn kein Multisampling verwendet wird, und über drei (Farbe-Auflösung, Tiefe-Stencil, Multisample-Farbe), wenn ` sampleCountFlagBits()` größer als ` VK_SAMPLE_COUNT_1_BIT` ist. Renderer müssen dies berücksichtigen, beispielsweise bei der Bereitstellung von Clear-Werten.

Siehe auch ` defaultRenderPass()`.

int QVulkanWindow::currentSwapChainImageIndex() const

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

VkRenderPass QVulkanWindow::defaultRenderPass() const

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

Siehe auch ` currentFramebuffer()`.

VkFormat QVulkanWindow::depthStencilFormat() const

Gibt das vom/von den Depth-Stencil-Puffern verwendete Format zurück.

VkImage QVulkanWindow::depthStencilImage() const

Gibt das Depth-Stencil-Bild zurück.

VkImageView QVulkanWindow::depthStencilImageView() const

Gibt die Ansicht des Depth-Stencil-Bildes zurück.

VkDevice QVulkanWindow::device() const

Gibt das aktive logische Gerät zurück.

uint32_t QVulkanWindow::deviceLocalMemoryIndex() const

Gibt einen für den allgemeinen Gebrauch geeigneten Index für einen gerätespezifischen Speichertyp zurück.

QVulkanWindow::Flags QVulkanWindow::flags() const

Gibt die angeforderten Flags zurück.

Siehe auch setFlags().

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

Dieses Signal wird ausgegeben, wenn der „ image “ betriebsbereit ist.

void QVulkanWindow::frameReady()

Diese Funktion muss als Reaktion auf jeden Aufruf der Implementierung von ` QVulkanWindowRenderer::startNextFrame()` genau einmal aufgerufen werden. Zum Zeitpunkt dieses Aufrufs müssen dem über ` currentCommandBuffer()` bereitgestellten Hauptbefehlspuffer 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 anzuzeigen, und führt anschließend ein blockierendes Auslesen des Bildinhalts durch.

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

Das zurückgegebene ` QImage ` hat immer das Format ` QImage::Format_RGBA8888`. Ist das ` colorFormat()`-Signal auf ` VK_FORMAT_B8G8R8A8_UNORM` gesetzt, werden der rote und der blaue Kanal automatisch vertauscht, da dieses Format üblicherweise als Standard für Swapchain-Farbpuffer verwendet wird. Bei jedem anderen Farbpufferformat führt diese Funktion keine Konvertierung durch.

VkCommandPool QVulkanWindow::graphicsCommandPool() const

Gibt den aktiven Grafikbefehlspool 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 allgemeinen Gebrauch geeigneten, vom Host sichtbaren Speicher-Typindex zurück.

Der zurückgegebene Speichertyp ist sowohl für den Host sichtbar als auch kohärent. Außerdem wird er, sofern möglich, zwischengespeichert.

bool QVulkanWindow::isValid() const

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

VkImage QVulkanWindow::msaaColorImage(int idx) const

Gibt das angegebene Multisample-Farbbild zurück oder „ VK_NULL_HANDLE “, wenn kein Multisampling 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 kein Multisampling 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 Samples als Wert vom Typ „ VkSampleCountFlagBits “ zurück.

Bei Verwendung des Standard-Renderziels 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 en fest.

Nicht unterstützte Erweiterungen werden ignoriert.

Die Swapchain-Erweiterung wird immer automatisch hinzugefügt; sie muss nicht in diese Liste aufgenommen werden.

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

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

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ätefunktionen fest: modifier.

Diese Funktion wurde in Qt 6.7 eingeführt.

Siehe auch EnabledFeatures2Modifier.

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

Konfiguriert das Verhalten basierend auf dem übergebenen ` 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 Format „ formats “ der Swapchain fest.

Standardmäßig ist kein anwendungsspezifisches Format festgelegt. In diesem Fall wird das bevorzugte Format der Oberfläche verwendet oder, falls dieses nicht vorhanden ist, „ VK_FORMAT_B8G8R8A8_UNORM “.

Die Liste in ` formats ` ist sortiert. Wird das erste Format nicht unterstützt, wird das zweite berücksichtigt und so weiter. Wenn kein Format aus der Liste unterstützt wird, verhält sich die Funktion wie im Standardfall.

Um das tatsächliche 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 Informationen zur Erstellung von Warteschlangen fest: modifier.

Siehe auch QueueCreateInfoModifier.

void QVulkanWindow::setSampleCount(int sampleCount)

Fordert Multisample-Antialiasing mit dem angegebenen Wert „ sampleCount “ an. Gültige Werte sind 1, 2, 4, 8, … bis hin zum vom physischen Gerät unterstützten Maximalwert.

Wenn die Abtastanzahl größer als 1 ist, erstellt ` QVulkanWindow ` einen Multisample-Farbpuffer, anstatt lediglich die Bilder der Swapchain anzusteuern. Die Darstellung im Multisample-Puffer wird am Ende jedes Frames in die Nicht-Multisample-Puffer aufgelöst.

Um die Liste der unterstützten Sample-Anzahlen einzusehen, rufen Sie ` supportedSampleCounts()` auf.

Rufen Sie beim Einrichten der Rendering-Pipeline sampleCountFlagBits() auf, um die aktive Sample-Anzahl 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 Sample-Zahlen bei Verwendung des durch ` setPhysicalDeviceIndex()` ausgewählten physischen Geräts als sortierte Liste zurück.

Standardmäßig verwendet „ QVulkanWindow “ eine Abtastanzahl von 1. Durch Aufruf von „ setSampleCount()“ mit einem anderen Wert (2, 4, 8, …) aus der von dieser Funktion zurückgegebenen Menge kann eine Mehrfachabtastung zur Kantenglättung angefordert werden.

Siehe auch ` setSampleCount()`.

bool QVulkanWindow::supportsGrab() const

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

VkImage QVulkanWindow::swapChainImage(int idx) const

Gibt das angegebene Swap-Chain-Image zurück.

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

int QVulkanWindow::swapChainImageCount() const

Gibt die Anzahl der Bilder in der Swap-Chain zurück.

QSize QVulkanWindow::swapChainImageSize() const

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

Diese entspricht in der Regel der Größe des Fensters, kann jedoch auch abweichen, falls vkGetPhysicalDeviceSurfaceCapabilitiesKHR eine feste Größe meldet.

Zudem wurde auf einigen Plattformen beobachtet, dass die von Vulkan gemeldete Oberflächengröße bei aktiver hoher DPI-Skalierung abweicht, d. h., das Ergebnis von ` QWindow. size()` multipliziert mit ` devicePixelRatio()` war im Vergleich zum hier zurückgegebenen Wert um 1 Pixel kleiner oder größer, vermutlich aufgrund von Rundungsunterschieden. Der Rendering-Code sollte dies berücksichtigen, und jede damit verbundene Rendering-Logik muss auf dem 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 ausschließlich auf die von der Vulkan-API gemeldete Oberflächengröße stützen. Andernfalls können Validierungsfehler auftreten, z. B. beim Festlegen des Viewports, da die von der Anwendung bereitgestellten Werte aus Sicht von Vulkan außerhalb des zulässigen Bereichs liegen können.

VkImageView QVulkanWindow::swapChainImageView(int idx) const

Gibt die angegebene Swap-Chain-Image-Ansicht zurück.

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