En esta página

QVulkanWindow Class

La clase `QVulkanWindow` es una subclase de conveniencia de ` QWindow ` que permite realizar el renderizado con Vulkan. Más información...

Encabezado: #include <QVulkanWindow>
CMake: find_package(Qt6 REQUIRED COMPONENTS Gui)
target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake: QT += gui
Heredado de: QWindow

Tipos públicos

(since 6.7) EnabledFeatures2Modifier
EnabledFeaturesModifier
enum Flag { PersistentResources }
flags Flags
QueueCreateInfoModifier

Funciones públicas

QVulkanWindow(QWindow *parent = nullptr)
virtual ~QVulkanWindow()
QList<VkPhysicalDeviceProperties> availablePhysicalDevices()
QMatrix4x4 clipCorrectionMatrix()
VkFormat colorFormat() const
int concurrentFrameCount() const
virtual QVulkanWindowRenderer *createRenderer()
VkCommandBuffer currentCommandBuffer() const
int currentFrame() const
VkFramebuffer currentFramebuffer() const
int currentSwapChainImageIndex() const
VkRenderPass defaultRenderPass() const
VkFormat depthStencilFormat() const
VkImage depthStencilImage() const
VkImageView depthStencilImageView() const
VkDevice device() const
uint32_t deviceLocalMemoryIndex() const
QVulkanWindow::Flags flags() const
void frameReady()
QImage grab()
VkCommandPool graphicsCommandPool() const
VkQueue graphicsQueue() const
uint32_t graphicsQueueFamilyIndex() const
uint32_t hostVisibleMemoryIndex() const
bool isValid() const
VkImage msaaColorImage(int idx) const
VkImageView msaaColorImageView(int idx) const
VkPhysicalDevice physicalDevice() const
const VkPhysicalDeviceProperties *physicalDeviceProperties() const
VkSampleCountFlagBits sampleCountFlagBits() const
void setDeviceExtensions(const QByteArrayList &extensions)
(since 6.7) void setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier)
(since 6.7) void setEnabledFeaturesModifier(QVulkanWindow::EnabledFeatures2Modifier modifier)
void setFlags(QVulkanWindow::Flags flags)
void setPhysicalDeviceIndex(int idx)
void setPreferredColorFormats(const QList<VkFormat> &formats)
void setQueueCreateInfoModifier(const QVulkanWindow::QueueCreateInfoModifier &modifier)
void setSampleCount(int sampleCount)
QVulkanInfoVector<QVulkanExtension> supportedDeviceExtensions()
QList<int> supportedSampleCounts()
bool supportsGrab() const
VkImage swapChainImage(int idx) const
int swapChainImageCount() const
QSize swapChainImageSize() const
VkImageView swapChainImageView(int idx) const

Señales

void frameGrabbed(const QImage &image)

Miembros públicos estáticos

Descripción detallada

QVulkanWindow es un « QWindow » compatible con Vulkan que gestiona un dispositivo Vulkan, una cola de gráficos, un conjunto de comandos y un búfer, una imagen de profundidad-estencil y una cadena de intercambio FIFO con doble búfer, al tiempo que garantiza un comportamiento correcto ante eventos como el cambio de tamaño, situaciones especiales como la falta de una cola de dispositivo que admita tanto gráficos como presentación, situaciones de pérdida del dispositivo y funcionalidades adicionales como la lectura del contenido renderizado. Conceptualmente, es el equivalente a « QOpenGLWindow » en el entorno de Vulkan.

Nota: QVulkanWindow no siempre elimina la necesidad de implementar una subclase totalmente personalizada de ` QWindow `, ya que no será necesariamente suficiente en casos de uso avanzados.

QVulkanWindow puede integrarse en interfaces de usuario basadas en ` QWidget` a través de ` QWidget::createWindowContainer()`. Sin embargo, este enfoque presenta una serie de limitaciones. Asegúrate de estudiar primero el documento « documentation ».

Una aplicación típica que utilice QVulkanWindow podría tener el siguiente aspecto:

class VulkanRenderer : public QVulkanWindowRenderer
{
public:
    VulkanRenderer(QVulkanWindow*w): m_window(w), m_devFuncs(nullptr) { }

    void initResources() override
    {
        m_devFuncs = m_window->vulkanInstance()->deviceFunctions(m_window->device());
       // ..
    }
    void initSwapChainResources() override { /* ... */ }
    void releaseSwapChainResources() override { /* ... */ }
    void releaseResources() override { /* ... */ }

   void startNextFrame() override
    {
        VkCommandBuffer cmdBuf = m_window->currentCommandBuffer();
        // ...
        m_devFuncs->vkCmdBeginRenderPass(commandBuffer, renderPassBegin, contents);
        // ...
        m_window->frameReady();
    }

private:
    QVulkanWindow*m_window;
    QVulkanDeviceFunctions*m_devFuncs;
};

class VulkanWindow : public QVulkanWindow
{
público:
    QVulkanWindowRenderer*createRenderer() override {
        return new VulkanRenderer(this);
    }
};

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QVulkanInstance inst;
    // habilita las capas de validación estándar, cuando estén disponibles
    inst.setLayers({ "VK_LAYER_KHRONOS_validation" });
    if (!inst.create())
        qFatal("Failed to create Vulkan instance: %d", inst.errorCode());

    VulkanWindow w;
    w.setVulkanInstance(&inst);
    w.showMaximized();

    return app.exec();
}

Como se puede ver en el ejemplo, los patrones principales en el uso de QVulkanWindow son:

  • La instancia ` QVulkanInstance ` se asocia mediante ` QWindow::setVulkanInstance()`. A continuación, se puede recuperar mediante ` QWindow::vulkanInstance()` desde cualquier lugar y en cualquier hilo.
  • Al igual que con ` QVulkanInstance`, las extensiones del dispositivo se pueden consultar mediante ` supportedDeviceExtensions()` antes de la inicialización propiamente dicha. La solicitud de habilitación de una extensión se realiza mediante ` setDeviceExtensions()`. Dichas llamadas deben realizarse antes de que la ventana sea visible, es decir, antes de llamar a ` show()` o funciones similares. Las solicitudes de extensiones no compatibles se ignoran de forma controlada.
  • El renderizador está implementado en una subclase de ` QVulkanWindowRenderer `, de la que se crea una instancia en la función de fábrica ` createRenderer()`.
  • Los comandos básicos de Vulkan se exponen a través del objeto ` QVulkanFunctions `, al que se puede acceder llamando a ` QVulkanInstance::functions()`. Las funciones a nivel de dispositivo están disponibles tras crear un `VkDevice` llamando a ` QVulkanInstance::deviceFunctions()`.
  • La construcción de las llamadas de dibujo para el siguiente fotograma tiene lugar en QVulkanWindowRenderer::startNextFrame(). Se espera que la implementación añada comandos al búfer de comandos devuelto por currentCommandBuffer(). El hecho de salir de la función no indica que los comandos estén listos para su envío. Por el contrario, se requiere una llamada explícita a frameReady(). Esto permite la generación asíncrona de comandos, posiblemente en múltiples subprocesos. Las implementaciones sencillas se limitarán a llamar a frameReady() al final de su QVulkanWindowRenderer::startNextFrame().
  • Los recursos básicos de Vulkan (dispositivo físico, cola de gráficos, un grupo de comandos, el búfer de comandos principal de la ventana, formatos de imagen, etc.) se exponen en QVulkanWindow a través de funciones getter ligeras. Algunas de ellas son solo por comodidad, y las aplicaciones siempre tienen libertad para consultar, crear y gestionar recursos adicionales directamente a través de la API de Vulkan.
  • El renderizador reside en el hilo gui/main, al igual que la propia ventana. Este hilo se limita entonces a la frecuencia de presentación, de forma similar a como se comportaría OpenGL con un intervalo de intercambio de 1. Sin embargo, la implementación del renderizador es libre de utilizar múltiples hilos de la forma que considere oportuna. Los accesores como vulkanInstance(), currentCommandBuffer(), etc., pueden invocarse desde cualquier hilo. El envío del búfer de comandos principal, la puesta en cola de la presentación y la construcción del siguiente fotograma no comienzan hasta que se invoca frameReady() en el hilo principal de la interfaz gráfica de usuario.
  • Cuando la ventana se hace visible, el contenido se actualiza automáticamente. Se pueden solicitar más actualizaciones llamando a ` QWindow::requestUpdate()`. Para renderizar de forma continua, llama a ` requestUpdate()` después de ` frameReady()`.

Para la resolución de problemas, activa la categoría de registro « qt.vulkan ». Los errores críticos se muestran automáticamente mediante « qWarning()».

Diferencias entre los sistemas de coordenadas de OpenGL y Vulkan

Hay dos diferencias importantes que hay que tener en cuenta: en primer lugar, en Vulkan el eje Y apunta hacia abajo en el espacio de recorte, mientras que OpenGL utiliza un eje Y que apunta hacia arriba. En segundo lugar, la matriz de proyección estándar de OpenGL asume valores de plano cercano y lejano de -1 y 1, mientras que Vulkan prefiere 0 y 1.

Para facilitar la migración de las aplicaciones desde código basado en OpenGL sin tener que invertir las coordenadas Y en los datos de vértices, y para permitir el uso de funciones de « QMatrix4x4 » como ` QMatrix4x4::perspective()` manteniendo al mismo tiempo los valores de `minDepth` y `maxDepth` de la ventana de visualización de Vulkan establecidos en 0 y 1, `QVulkanWindow` proporciona una matriz de corrección a la que se puede acceder llamando a ` clipCorrectionMatrix()`.

Multimuestreo

Aunque está desactivado por defecto, QVulkanWindow es totalmente compatible con el antialiasing por multimuestreo. Los búferes de color adicionales y la resolución en los búferes no multimuestreados de la cadena de intercambio se gestionan de forma automática.

Para consultar el número de muestras admitidas, llama a ` supportedSampleCounts()`. Cuando el conjunto devuelto contenga 4, 8, ..., al pasar uno de esos valores a ` setSampleCount()` se solicitará el renderizado multimuestreo.

Nota: a diferencia de ` QSurfaceFormat::setSamples()` , la lista de recuentos de muestras compatibles se facilita a las aplicaciones por adelantado y no hay un recambio automático a recuentos de muestras inferiores en ` setSampleCount()`. Si el valor solicitado no es compatible, se muestra una advertencia y no se utilizará el multimuestreo.

Recuperación de imágenes

Cuando supportsGrab() devuelve «true», QVulkanWindow puede realizar lecturas del búfer de color en un QImage. grab() es una operación lenta e ineficiente, por lo que debe evitarse su uso frecuente. No obstante, resulta útil, ya que permite a las aplicaciones realizar capturas de pantalla, o a herramientas y pruebas procesar y verificar el resultado del renderizado de la GPU.

Compatibilidad con sRGB

Aunque a muchas aplicaciones les bastará con el comportamiento predeterminado de `QVulkanWindow` en lo que respecta a los formatos de imagen de la cadena de intercambio, ` setPreferredColorFormats()` permite solicitar un formato predefinido. Esto resulta especialmente útil cuando se trabaja en el espacio de color sRGB. Al pasar un formato como ` VK_FORMAT_B8G8R8A8_SRGB `, se selecciona un formato sRGB, siempre que esté disponible.

Capas de validación

Durante el desarrollo de aplicaciones, puede resultar extremadamente útil tener habilitadas las capas de validación de Vulkan. Tal y como se muestra en el código de ejemplo anterior, llamar a QVulkanInstance::setLayers() sobre QVulkanInstance antes de QVulkanInstance::create() habilita la validación, siempre que la pila de controladores de Vulkan del sistema contenga las capas necesarias.

Nota: Ten en cuenta las diferencias específicas de cada plataforma. En las plataformas de escritorio, suele bastar con instalar el SDK de Vulkan. Sin embargo, Android, por ejemplo, requiere la implementación de bibliotecas compartidas adicionales junto con la aplicación, y también exige una lista diferente de nombres de capas de validación. Consulta las páginas de desarrollo de Vulkan para Android para obtener más información.

Nota: QVulkanWindow no expone las capas del dispositivo, ya que esta funcionalidad ha quedado obsoleta desde la versión 1.0.13 de la API de Vulkan.

Capas, características del dispositivo y extensiones

Para habilitar las capas de instancia, llama a ` QVulkanInstance::setLayers()` antes de crear el objeto ` QVulkanInstance`. Para consultar qué capas de instancia están disponibles, llama a ` QVulkanInstance::supportedLayers()`.

Para habilitar las extensiones de dispositivo, llama a ` setDeviceExtensions()` en una fase temprana de la configuración de `QVulkanWindow`. Para consultar qué extensiones de dispositivo están disponibles, llama a ` supportedDeviceExtensions()`.

La especificación de una capa o extensión no compatible se gestiona de forma elegante: esto no provocará un error en la creación de la instancia o del dispositivo, sino que la solicitud de la capa o extensión simplemente se ignorará.

En cuanto a las características del dispositivo, QVulkanWindow habilita todas las características de Vulkan 1.0 que vkGetPhysicalDeviceFeatures() indica que son compatibles. Como excepción a esta regla, robustBufferAccess nunca se habilita. Utiliza el mecanismo de devolución de llamada que se describe a continuación si deseas habilitar esa característica.

Esto no siempre es deseable y puede resultar insuficiente con Vulkan 1.1 y versiones posteriores. Por lo tanto, también es posible ejercer un control total sobre las VkPhysicalDeviceFeatures utilizadas para la creación del dispositivo registrando una función de devolución de llamada con setEnabledFeaturesModifier(). Una vez configurada, se invoca la función de devolución de llamada, lo que le permite modificar las VkPhysicalDeviceFeatures o las VkPhysicalDeviceFeatures2.

Consideraciones de seguridad

Se espera que todos los datos utilizados por `QVulkanWindow` sean de confianza. Esto incluye los nombres de las extensiones de dispositivo pasados a ` setDeviceExtensions()`, los parámetros de creación de dispositivos escritos por las funciones de devolución de llamada registradas a través de ` setEnabledFeaturesModifier()` y ` setQueueCreateInfoModifier()`, y todo el contenido de renderizado y los parámetros de los comandos de Vulkan generados por la implementación de ` QVulkanWindowRenderer `. La propia implementación de Vulkan es una dependencia de la plataforma de confianza y dentro del proceso; consulte QVulkanInstance para obtener más detalles.

Advertencia: Se recomienda a los desarrolladoresde aplicaciones que sopesen cuidadosamente las posibles implicaciones antes de permitir la incorporación de contenido proporcionado por el usuario que no forme parte de la aplicación y que no esté bajo el control de los desarrolladores.

Véase también QVulkanInstance y QWindow.

Documentación sobre tipos de miembros

[since 6.7] QVulkanWindow::EnabledFeatures2Modifier

Función que se invoca durante la inicialización de los gráficos para modificar el objeto `VkPhysicalDeviceFeatures2`, que se incorpora al objeto `VkDeviceCreateInfo`.

Por defecto, ` QVulkanWindow ` habilita todas las características básicas de Vulkan 1.0 que el dispositivo físico indica que admite, con ciertas excepciones. En concreto, ` robustBufferAccess ` siempre está deshabilitado para evitar pérdidas inesperadas de rendimiento.

Sin embargo, esto no siempre es suficiente cuando se trabaja con características y extensiones de Vulkan 1.1, 1.2 o 1.3. De ahí este mecanismo de devolución de llamada. Si solo es relevante Vulkan 1.0 en tiempo de ejecución, utiliza en su lugar ` setEnabledFeaturesModifier()`.

La referencia VkPhysicalDeviceFeatures2 se pasa a la función de callback con sType establecido, pero el resto a cero. Depende de la función cambiar los miembros a «true» o configurar cadenas de pNext según considere oportuno.

Nota: Al configurar cadenas de « pNext », asegúrate de que los objetos a los que se hace referencia tengan una vida útil lo suficientemente larga, por ejemplo, almacenándolos como variables de miembro en la subclase de « QVulkanWindow ».

Esta definición de tipo se introdujo en Qt 6.7.

Véase también ` setEnabledFeaturesModifier()`.

QVulkanWindow::EnabledFeaturesModifier

Función que se invoca durante la inicialización de los gráficos para modificar el objeto `VkPhysicalDeviceFeatures` que se pasa al crear un objeto de dispositivo Vulkan.

Por defecto, ` QVulkanWindow ` habilita todas las características básicas de Vulkan 1.0 que el dispositivo físico indica que son compatibles, con ciertas excepciones. En concreto, ` robustBufferAccess ` siempre está deshabilitado para evitar pérdidas inesperadas de rendimiento.

La referencia a VkPhysicalDeviceFeatures que se pasa se pone a cero en el momento en que se invoca la función. Depende de la función modificar los miembros como considere oportuno.

Nota: Para controlar las características de Vulkan 1.1, 1.2 o 1.3, utilice en su lugar EnabledFeatures2Modifier.

Véase también ` setEnabledFeaturesModifier()`.

enum QVulkanWindow::Flag
flags QVulkanWindow::Flags

Esta enumeración describe los parámetros que se pueden pasar a la función ` setFlags()`.

ConstanteValorDescripción
QVulkanWindow::PersistentResources0x01Garantiza que no se liberen recursos gráficos cuando la ventana quede oculta. El comportamiento por defecto es liberar todo y reinicializar más tarde, cuando vuelva a estar visible.

El tipo Flags es una definición de tipo (typedef) para QFlags<Flag>. Almacena una combinación OR de valores de Flag.

QVulkanWindow::QueueCreateInfoModifier

Función que se invoca durante la inicialización de los gráficos para añadir colas adicionales que deben crearse.

Se establece si el renderizador necesita colas adicionales además de la cola gráfica predeterminada (por ejemplo, una cola de transferencia). Las propiedades de la familia de colas proporcionadas se pueden utilizar para seleccionar los índices de las colas adicionales. Posteriormente, el renderizador puede solicitar la cola concreta en initResources().

Nota: Al solicitar colas gráficas adicionales, el propio Qt siempre solicita una cola gráfica. Tendrás que buscar en queueCreateInfo la entrada adecuada y manipularla para obtener la cola adicional.

Véase también ` setQueueCreateInfoModifier()`.

Documentación de funciones miembro

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

Crea una nueva QVulkanWindow con el tipo de superficie « parent » especificado.

El tipo de superficie se establece en « QSurface::VulkanSurface ».

[virtual noexcept] QVulkanWindow::~QVulkanWindow()

Destructor.

QList<VkPhysicalDeviceProperties> QVulkanWindow::availablePhysicalDevices()

Devuelve la lista de propiedades de los dispositivos físicos compatibles con el sistema.

Nota: Esta función se puede invocar antes de hacer visible la ventana.

QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()

Devuelve una matriz de transformación de coordenadas ( QMatrix4x4 ) que se puede utilizar para corregir las diferencias entre los sistemas de coordenadas de OpenGL y Vulkan.

Al multiplicar previamente la matriz de proyección por esta matriz, las aplicaciones pueden seguir asumiendo que Y apunta hacia arriba y pueden establecer minDepth y maxDepth en la ventana gráfica en 0 y 1, respectivamente, sin tener que realizar ninguna corrección adicional en las posiciones Z de los vértices. La geometría de las aplicaciones OpenGL se puede utilizar tal cual, siempre que se utilice un estado de rasterización que coincida con la configuración de culling y de caras frontales de OpenGL.

VkFormat QVulkanWindow::colorFormat() const

Devuelve el formato del búfer de color utilizado por la cadena de intercambio.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

Véase también ` setPreferredColorFormats()`.

int QVulkanWindow::concurrentFrameCount() const

Devuelve el número de fotogramas que pueden estar activos simultáneamente.

Nota: El valor es constante durante toda la vida útil del objeto ` QVulkanWindow`.

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

Véase también currentFrame().

[virtual] QVulkanWindowRenderer *QVulkanWindow::createRenderer()

Devuelve una nueva instancia de ` QVulkanWindowRenderer`.

Esta función virtual se invoca una vez durante el ciclo de vida de la ventana, en algún momento después de hacerla visible por primera vez.

La implementación por defecto devuelve null, por lo que no se realizará ningún renderizado, salvo el borrado de los búferes.

La ventana asume la propiedad del objeto renderizador devuelto.

VkCommandBuffer QVulkanWindow::currentCommandBuffer() const

Devuelve el búfer de comandos activo para el fotograma actual de la cadena de intercambio. Se espera que las implementaciones de ` QVulkanWindowRenderer::startNextFrame()` añadan comandos a este búfer de comandos.

Nota: Esta función solo debe invocarse desde dentro de `startNextFrame()` y, en caso de generación asíncrona de comandos, hasta la llamada a ` frameReady()`.

int QVulkanWindow::currentFrame() const

Devuelve el índice del fotograma actual en el intervalo [0, concurrentFrameCount() - 1].

Las implementaciones del renderizador deberán garantizar que los datos uniformes y otros recursos dinámicos existan en múltiples copias, con el fin de evitar que el fotograma N altere los datos utilizados por los fotogramas aún activos N - 1, N - 2, … N - concurrentFrameCount() + 1.

Para evitar depender de tamaños de matriz dinámicos, las aplicaciones pueden utilizar MAX_CONCURRENT_FRAME_COUNT al declarar matrices. Se garantiza que este valor será siempre igual o mayor que el valor devuelto por concurrentFrameCount(). Dichas matrices pueden entonces indexarse mediante el valor devuelto por esta función.

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

Nota: Esta función solo debe llamarse desde dentro de `startNextFrame()` y, en caso de generación asíncrona de comandos, hasta la llamada a ` frameReady()`.

Véase también ` concurrentFrameCount()`.

VkFramebuffer QVulkanWindow::currentFramebuffer() const

Devuelve un VkFramebuffer para la imagen de la cadena de intercambio actual utilizando la pasada de renderizado predeterminada.

El framebuffer tiene dos adjuntos (color, profundidad-estencil) cuando no se utiliza el multimuestreo, y tres (resolución de color, profundidad-estencil, color multimuestreado) cuando sampleCountFlagBits() es mayor que VK_SAMPLE_COUNT_1_BIT. Los renderizadores deben tener esto en cuenta, por ejemplo, al proporcionar valores de borrado.

Nota: Las aplicaciones no están obligadas a utilizar este búfer de fotogramas en caso de que proporcionen su propia pasada de renderizado en lugar de utilizar la devuelta por defaultRenderPass().

Nota: Esta función solo debe invocarse desde dentro de `startNextFrame()` y, en caso de generación asíncrona de comandos, hasta la llamada a ` frameReady()`.

Véase también defaultRenderPass().

int QVulkanWindow::currentSwapChainImageIndex() const

Devuelve el índice actual de la imagen de la cadena de intercambio en el intervalo [0, swapChainImageCount() - 1].

Nota: Esta función solo debe invocarse desde dentro de startNextFrame() y, en caso de generación asíncrona de comandos, hasta la llamada a frameReady().

VkRenderPass QVulkanWindow::defaultRenderPass() const

Devuelve un paso de renderizado típico con un subpaso.

Nota: Las aplicaciones no están obligadas a utilizar este paso de renderizado. Sin embargo, en ese caso son responsables de garantizar que la cadena de intercambio actual y las imágenes de profundidad y estarcido se transfieran de VK_IMAGE_LAYOUT_UNDEFINED a VK_IMAGE_LAYOUT_PRESENT_SRC_KHR y VK_IMAGE_LAYOUT_DEPTH_STENCIL_ATTACHMENT_OPTIMAL, ya sea a través del paso de renderizado personalizado de la aplicación o por otros medios.

Nota: La lectura y escritura deestencil no está habilitada en esta pasada de renderizado.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

Véase también currentFramebuffer().

VkFormat QVulkanWindow::depthStencilFormat() const

Devuelve el formato utilizado por los búferes de profundidad y estencil.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

VkImage QVulkanWindow::depthStencilImage() const

Devuelve la imagen de profundidad-estencil.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

VkImageView QVulkanWindow::depthStencilImageView() const

Devuelve la vista de la imagen de profundidad-estencil.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

VkDevice QVulkanWindow::device() const

Devuelve el dispositivo lógico activo.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

uint32_t QVulkanWindow::deviceLocalMemoryIndex() const

Devuelve un índice de tipo de memoria local del dispositivo adecuado para uso general.

Nota: La llamada a esta función solo es válida desde la invocación de QVulkanWindowRenderer::initResources() hasta QVulkanWindowRenderer::releaseResources().

Nota: Nose garantiza que este tipo de memoria sea siempre adecuado. La solución correcta, válida para todas las implementaciones —especialmente para las imágenes locales del dispositivo—, consiste en seleccionar manualmente un tipo de memoria tras comprobar la máscara devuelta por vkGetImageMemoryRequirements.

QVulkanWindow::Flags QVulkanWindow::flags() const

Devuelve los indicadores solicitados.

Véase también setFlags().

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

Esta señal se emite cuando el « image » está listo.

void QVulkanWindow::frameReady()

Esta función debe llamarse exactamente una vez en respuesta a cada invocación de la implementación de ` QVulkanWindowRenderer::startNextFrame()`. En el momento de esta llamada, el búfer de comandos principal, al que se accede mediante ` currentCommandBuffer()`, debe contener todos los comandos de renderizado necesarios, ya que esta función activará el envío de los comandos y la puesta en cola del comando actual.

Nota: Esta función solo debe llamarse desde el hilo principal de la interfaz gráfica de usuario (gui/main), que es donde se invocan las funciones de ` QVulkanWindowRenderer` y donde reside la instancia de ` QVulkanWindow `.

Véase también QVulkanWindowRenderer::startNextFrame().

QImage QVulkanWindow::grab()

Crea y renderiza el siguiente fotograma sin mostrarlo y, a continuación, realiza una lectura bloqueante del contenido de la imagen.

Devuelve la imagen si la implementación de ` startNextFrame()` del renderizador llama directamente a ` frameReady()`. De lo contrario, devuelve una imagen incompleta, que tiene el tamaño correcto pero aún no tiene contenido. En este último caso, el contenido se entregará a través de la señal ` frameGrabbed()`.

La función ` QImage ` devuelta siempre tiene el formato ` QImage::Format_RGBA8888`. Si la señal ` colorFormat()` es ` VK_FORMAT_B8G8R8A8_UNORM`, los canales rojo y azul se intercambian automáticamente, ya que este formato se utiliza habitualmente como opción predeterminada para los búferes de color de la cadena de intercambio. Con cualquier otro formato de búfer de color, esta función no realiza ninguna conversión.

Nota: Esta función no debe invocarse mientras se está procesando un fotograma (es decir, cuando la aplicación aún no ha devuelto la llamada a frameReady()).

Nota: Esta función puede resultar costosa debido a la lectura adicional que bloquea el proceso.

Nota: Actualmente,esta función requiere que la cadena de intercambio admita su uso como fuente de transferencia (VK_IMAGE_USAGE_TRANSFER_SRC_BIT); de lo contrario, dará error.

VkCommandPool QVulkanWindow::graphicsCommandPool() const

Devuelve el grupo de comandos gráficos activo.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

VkQueue QVulkanWindow::graphicsQueue() const

Devuelve la cola de gráficos activa.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

uint32_t QVulkanWindow::graphicsQueueFamilyIndex() const

Devuelve el índice de familia de la cola de gráficos activa.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`. Las implementaciones de `QVulkanWindowRenderer::updateQueueCreateInfo()` también pueden llamar a esta función.

uint32_t QVulkanWindow::hostVisibleMemoryIndex() const

Devuelve un índice de tipo de memoria visible para el host adecuado para uso general.

El tipo de memoria devuelto será visible para el host y coherente. Además, se almacenará en caché, si es posible.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

bool QVulkanWindow::isValid() const

Devuelve «true» si esta ventana ha inicializado correctamente todos los recursos de Vulkan, incluida la cadena de intercambio.

Nota: La inicialización se produce en el primer evento «expose» después de que la ventana se haya hecho visible.

VkImage QVulkanWindow::msaaColorImage(int idx) const

Devuelve la imagen en color con muestreo múltiple especificada, o VK_NULL_HANDLE si no se está utilizando el muestreo múltiple.

idx Debe estar comprendido en el intervalo [0, swapChainImageCount() - 1].

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

VkImageView QVulkanWindow::msaaColorImageView(int idx) const

Devuelve la vista de la imagen en color con multimuestreo especificada, o ` VK_NULL_HANDLE ` si no se está utilizando el multimuestreo.

idx Debe estar en el intervalo [0, swapChainImageCount() - 1].

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

VkPhysicalDevice QVulkanWindow::physicalDevice() const

Devuelve el dispositivo físico activo.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::preInitResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

const VkPhysicalDeviceProperties *QVulkanWindow::physicalDeviceProperties() const

Devuelve un puntero a las propiedades del dispositivo físico activo.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::preInitResources()` hasta ` QVulkanWindowRenderer::releaseResources()`.

VkSampleCountFlagBits QVulkanWindow::sampleCountFlagBits() const

Devuelve el recuento de muestras actual como un valor de tipo « VkSampleCountFlagBits ».

Cuando se utiliza el destino de renderizado predeterminado, el campo « rasterizationSamples » de « VkPipelineMultisampleStateCreateInfo » debe establecerse en este valor.

Véase también setSampleCount() y supportedSampleCounts().

void QVulkanWindow::setDeviceExtensions(const QByteArrayList &extensions)

Establece la lista de dispositivos extensions que se van a habilitar.

Las extensiones no compatibles se ignoran.

La extensión swapchain siempre se añadirá automáticamente, por lo que no es necesario incluirla en esta lista.

Nota: Esta función debe llamarse antes de que la ventana se haga visible o, como muy tarde, en QVulkanWindowRenderer::preInitResources(), y no tiene ningún efecto si se llama después.

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

Establece la función de modificación de las características del dispositivo activadas modifier.

Nota: Para controlar las características de Vulkan 1.1, 1.2 o 1.3, utiliza en su lugar la sobrecarga que toma un objeto ` EnabledFeatures2Modifier `.

Nota: modifier se pasa a la función de devolución de llamada con todos los miembros establecidos en false. Depende de la función cambiar los miembros como considere oportuno.

Esta función se introdujo en Qt 6.7.

Véase también EnabledFeaturesModifier.

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

Establece la función de modificación de las características del dispositivo activadas « modifier ».

Se trata de una función sobrecargada.

Esta función se introdujo en Qt 6.7.

Véase también EnabledFeatures2Modifier.

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

Configura el comportamiento en función de la función « flags » proporcionada.

Nota: Esta función debe invocarse antes de que la ventana se haga visible o, como muy tarde, en QVulkanWindowRenderer::preInitResources(), y no tiene ningún efecto si se invoca después.

Véase también flags().

void QVulkanWindow::setPhysicalDeviceIndex(int idx)

Solicita el uso del dispositivo físico con el índice idx. El índice se corresponde con la lista devuelta por availablePhysicalDevices().

Por defecto, se utiliza el primer dispositivo físico.

Nota: Esta función debe llamarse antes de que la ventana se haga visible o, a más tardar, en QVulkanWindowRenderer::preInitResources(), y no tiene ningún efecto si se llama después.

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

Establece el formato « formats » preferido de la cadena de intercambio.

Por defecto, no se establece ningún formato preferido por la aplicación. En este caso, se utilizará el formato preferido de la superficie o, en su defecto, VK_FORMAT_B8G8R8A8_UNORM.

La lista de formats está ordenada. Si no se admite el primer formato, se considerará el segundo, y así sucesivamente. Cuando no se admite ninguno de los formatos de la lista, el comportamiento es el mismo que en el caso predeterminado.

Para consultar el formato real tras la inicialización, llama a colorFormat().

Nota: Esta función debe llamarse antes de que la ventana se haga visible o, a más tardar, en QVulkanWindowRenderer::preInitResources(), y no tiene ningún efecto si se llama después.

Nota: La reimplementación de ` QVulkanWindowRenderer::preInitResources()` permite examinar dinámicamente la lista de formatos compatibles, si así se desea. En ese caso, la superficie se puede recuperar mediante `QVulkanInstace::surfaceForWindow()`, mientras que esta función se puede seguir llamando de forma segura para influir en las etapas posteriores de la inicialización.

Véase también colorFormat().

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

Establece la función de modificación de la información de creación de colas modifier.

Véase también QueueCreateInfoModifier.

void QVulkanWindow::setSampleCount(int sampleCount)

Solicita un suavizado multimuestra con el valor dado de « sampleCount ». Los valores válidos son 1, 2, 4, 8, … hasta el valor máximo admitido por el dispositivo físico.

Cuando el número de muestras es superior a 1, QVulkanWindow creará un búfer de color multimuestra en lugar de limitarse a utilizar las imágenes de la cadena de intercambio. La representación en el búfer multimuestra se resolverá en los búferes no multimuestra al final de cada fotograma.

Para consultar la lista de recuentos de muestras admitidos, llama a ` supportedSampleCounts()`.

Al configurar el proceso de renderizado, llama a sampleCountFlagBits() para consultar el número de muestras activo como un valor « VkSampleCountFlagBits ».

Nota: Esta función debe llamarse antes de que la ventana se haga visible o, a más tardar, en QVulkanWindowRenderer::preInitResources(), y no tiene ningún efecto si se llama después.

Véase también supportedSampleCounts() y sampleCountFlagBits().

QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()

Devuelve la lista de las extensiones compatibles con los dispositivos lógicos creados a partir del dispositivo físico seleccionado mediante la función ` setPhysicalDeviceIndex()`.

Nota: Esta función se puede llamar antes de hacer visible la ventana.

QList<int> QVulkanWindow::supportedSampleCounts()

Devuelve el conjunto de recuentos de muestras admitidos al utilizar el dispositivo físico seleccionado mediante ` setPhysicalDeviceIndex()`, en forma de lista ordenada.

Por defecto, QVulkanWindow utiliza un número de muestras igual a 1. Al llamar a setSampleCount() con un valor diferente (2, 4, 8, ...) del conjunto devuelto por esta función, se puede solicitar el suavizado de múltiples muestras.

Nota: Esta función se puede llamar antes de hacer visible la ventana.

Véase también setSampleCount().

bool QVulkanWindow::supportsGrab() const

Devuelve «true» si la cadena de intercambio admite su uso como origen de transferencia, lo que significa que la función ` grab()` es operativa.

Nota: La llamada a esta función solo es válida desde la invocación de QVulkanWindowRenderer::initSwapChainResources() hasta QVulkanWindowRenderer::releaseSwapChainResources().

VkImage QVulkanWindow::swapChainImage(int idx) const

Devuelve la imagen de la cadena de intercambio especificada.

idx Debe estar comprendido en el intervalo [0, swapChainImageCount() - 1].

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

int QVulkanWindow::swapChainImageCount() const

Devuelve el número de imágenes de la cadena de intercambio.

Nota: Es necesarioacceder a esta función cuando se proporciona un paso de renderizado y un búfer de fotogramas personalizados. El búfer de fotogramas es específico de la imagen actual de la cadena de intercambio y, por lo tanto, la aplicación debe proporcionar varios búferes de fotogramas.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

QSize QVulkanWindow::swapChainImageSize() const

Devuelve el tamaño de la imagen de la cadena de intercambio.

Normalmente coincide con el tamaño de la ventana, pero también puede diferir en caso de que vkGetPhysicalDeviceSurfaceCapabilitiesKHR informe de un tamaño fijo.

Además, se ha observado en algunas plataformas que el tamaño de la superficie indicado por Vulkan es diferente cuando el escalado de alto DPI está activo, lo que significa que el valor devuelto por QWindow- size() multiplicado por devicePixelRatio() era 1 píxel menor o mayor en comparación con el valor devuelto aquí, presumiblemente debido a diferencias en el redondeo. El código de renderizado debe tener esto en cuenta, y cualquier lógica de renderizado relacionada debe basarse en el valor devuelto desde aquí, nunca en el tamaño indicado por QWindow. Independientemente de cuál sea el tamaño de píxel correcto en teoría, el renderizado de Vulkan solo debe basarse en el tamaño de superficie indicado por la API de Vulkan. De lo contrario, pueden producirse errores de validación, por ejemplo, al configurar la ventana de visualización, ya que los valores proporcionados por la aplicación pueden quedar fuera de los límites desde la perspectiva de Vulkan.

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

VkImageView QVulkanWindow::swapChainImageView(int idx) const

Devuelve la vista de imagen de la cadena de intercambio especificada.

idx Debe estar comprendido en el intervalo [0, swapChainImageCount() - 1].

Nota: La llamada a esta función solo es válida desde la invocación de ` QVulkanWindowRenderer::initSwapChainResources()` hasta ` QVulkanWindowRenderer::releaseSwapChainResources()`.

Documentación de las variables miembro

const int QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT

Esta variable contiene un valor constante que siempre es igual o superior al valor máximo de concurrentFrameCount().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.