QVulkanWindow Class
La clase QVulkanWindow es una subclase de conveniencia de QWindow para realizar el renderizado Vulkan. Más...
| Cabecera: | #include <QVulkanWindow> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Hereda: | 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
| const int | MAX_CONCURRENT_FRAME_COUNT |
Descripción detallada
QVulkanWindow es un Vulkan-capable QWindow que maneja un dispositivo Vulkan, una cola de graficos, un pool de comandos y buffer, una imagen depth-stencil y un swapchain FIFO de doble buffer, mientras se encarga del comportamiento correcto cuando se trata de eventos como redimensionar, situaciones especiales como no tener una cola de dispositivo que soporte tanto graficos como presentacion, escenarios de perdida de dispositivo, y funcionalidad adicional como leer el contenido renderizado de vuelta. Conceptualmente es la contrapartida de QOpenGLWindow en el mundo Vulkan.
Nota: QVulkanWindow no siempre elimina la necesidad de implementar una subclase completamente personalizada de QWindow ya que no necesariamente será suficiente en casos de uso avanzados.
QVulkanWindow puede ser embebido en interfaces de usuario basadas en QWidget a través de QWidget::createWindowContainer(). Sin embargo, este enfoque tiene una serie de limitaciones. Asegúrate de estudiar primero documentation.
Una aplicación típica usando QVulkanWindow puede parecerse a lo siguiente:
clase 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 {public: 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 disponiblesinst.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 QVulkanInstance se asocia mediante QWindow::setVulkanInstance(). Luego es recuperable vía QWindow::vulkanInstance() desde cualquier lugar, en cualquier thread.
- De forma similar a QVulkanInstance, las extensiones de dispositivo pueden ser consultadas a través de supportedDeviceExtensions() antes de la inicialización real. La solicitud de habilitación de una extensión se realiza a través de setDeviceExtensions(). Estas llamadas deben realizarse antes de que la ventana sea visible, es decir, antes de llamar a show() o funciones similares. Las peticiones de extensión no soportadas son ignoradas.
- El renderizador se implementa en una subclase de QVulkanWindowRenderer, una instancia de la cual se crea en la función de fábrica createRenderer().
- Los comandos principales de Vulkan se exponen a través del objeto QVulkanFunctions, recuperable llamando a QVulkanInstance::functions(). Las funciones a nivel de dispositivo están disponibles después de crear un VkDevice llamando a QVulkanInstance::deviceFunctions().
- La construcción de las llamadas de dibujo para el siguiente frame ocurre en QVulkanWindowRenderer::startNextFrame(). Se espera que la implementación añada comandos al buffer de comandos devuelto por currentCommandBuffer(). El retorno de la función no indica que los comandos estén listos para ser enviados. Más bien, se requiere una llamada explícita a frameReady(). Esto permite la generación asíncrona de comandos, posiblemente en múltiples hilos. Las implementaciones simples simplemente llamarán a frameReady() al final de su QVulkanWindowRenderer::startNextFrame().
- Los recursos basicos de Vulkan (dispositivo fisico, cola de graficos, un pool de comandos, el buffer principal de comandos de la ventana, formatos de imagen, etc.) estan expuestos en QVulkanWindow a traves de ligeras funciones getter. Algunos de estos son sólo por conveniencia, y las aplicaciones son siempre libres de consultar, crear y gestionar recursos adicionales directamente a través de la API Vulkan.
- El renderizador vive en el hilo gui/main, como la propia ventana. Este hilo se ralentiza a la velocidad 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 accessors como vulkanInstance(), currentCommandBuffer(), etc. pueden ser llamados desde cualquier thread. El envío del buffer de comandos principal, la cola de presentes, y la construcción del siguiente frame no comienzan hasta que frameReady() es invocado en el hilo gui/main.
- 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, llame a requestUpdate() después de frameReady().
Para solucionar problemas, active la categoría de registro qt.vulkan. Los errores críticos se imprimen automáticamente a través de qWarning().
Diferencias de sistema de coordenadas entre OpenGL y Vulkan
Hay dos diferencias notables a tener en cuenta: En primer lugar, con Vulkan Y apunta hacia abajo de la pantalla en el espacio de clip, mientras que OpenGL utiliza un eje Y que apunta hacia arriba. En segundo lugar, la matriz de proyección estándar de OpenGL asume unos valores de plano cercano y lejano de -1 y 1, mientras que Vulkan prefiere 0 y 1.
Para ayudar a las aplicaciones a migrar desde código basado en OpenGL sin tener que voltear las coordenadas Y en los datos de vértices, y para permitir el uso de funciones QMatrix4x4 como QMatrix4x4::perspective() mientras se mantienen los valores minDepth y maxDepth de Vulkan a 0 y 1, QVulkanWindow proporciona una matriz de corrección recuperable llamando a clipCorrectionMatrix().
Muestreo múltiple
Aunque está desactivado por defecto, QVulkanWindow soporta completamente el antialiasing multimuestreo. Los buffers de color adicionales y la resolución en los buffers no-multimuestra del swapchain se gestionan automáticamente.
Para consultar el número de muestras soportadas, llame a supportedSampleCounts(). Cuando el conjunto devuelto contiene 4, 8, ..., pasando uno de esos valores a setSampleCount() se solicita el renderizado multimuestra.
Nota: a diferencia de QSurfaceFormat::setSamples(), la lista de recuentos de muestras admitidos se expone a las aplicaciones por adelantado y no se produce un retroceso automático a recuentos de muestras inferiores en setSampleCount(). Si no se admite el valor solicitado, se mostrará una advertencia y no se utilizará el multimuestreo.
Lectura de imágenes
Cuando supportsGrab() devuelve true, QVulkanWindow puede realizar lecturas desde el buffer de color a QImage. grab() es una operación lenta e ineficiente, por lo que debe evitarse su uso frecuente. No obstante, es valiosa ya que permite a las aplicaciones tomar capturas de pantalla, o a las herramientas y tests procesar y verificar la salida del renderizado de la GPU.
Soporte de sRGB
Mientras que muchas aplicaciones estarán bien con el comportamiento por defecto de QVulkanWindow cuando se trata de formatos de imagen swapchain, setPreferredColorFormats() permite solicitar un formato predefinido. Esto es útil sobre todo cuando se trabaja en el espacio de color sRGB. Pasar un formato como VK_FORMAT_B8G8R8A8_SRGB resulta en la elección de un formato sRGB, cuando esté disponible.
Capas de validación
Durante el desarrollo de aplicaciones puede ser extremadamente valioso tener habilitadas las capas de validación de Vulkan. Como se muestra en el código de ejemplo anterior, llamar a QVulkanInstance::setLayers() en QVulkanInstance antes de QVulkanInstance::create() habilita la validación, asumiendo que la pila de controladores Vulkan en el sistema contiene las capas necesarias.
Nota: Tenga en cuenta las diferencias específicas de cada plataforma. En las plataformas de escritorio, instalar el SDK de Vulkan suele ser suficiente. Sin embargo, Android, por ejemplo, requiere desplegar 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 Android Vulkan para obtener más información.
Nota: QVulkanWindow no expone capas de dispositivo ya que esta funcionalidad ha quedado obsoleta desde la versión 1.0.13 de la API Vulkan.
Capas, características del dispositivo y extensiones
Para habilitar las capas de instancia, llama a QVulkanInstance::setLayers() antes de crear la QVulkanInstance. Para consultar qué capas de instancia están disponibles, llama a QVulkanInstance::supportedLayers().
Para habilitar las extensiones de dispositivo, llame a setDeviceExtensions() antes de configurar el QVulkanWindow. Para consultar qué extensiones de dispositivo están disponibles, llama a supportedDeviceExtensions().
Especificar una capa o extensión no soportada es manejado con gracia: esto no fallará la creación de instancia o dispositivo, pero la solicitud de capa o extensión es ignorada.
Cuando se trata de características del dispositivo, QVulkanWindow habilita todas las características de Vulkan 1.0 que son reportadas como soportadas por vkGetPhysicalDeviceFeatures(). Como excepción a esta regla, robustBufferAccess nunca está habilitado. Utilice el mecanismo de llamada de retorno descrito a continuación, si desea habilitar esa característica.
Esto no siempre es deseable, y puede ser insuficiente con Vulkan 1.1 y superiores. Por lo tanto, el control total sobre el VkPhysicalDeviceFeatures utilizado para la creación de dispositivos es posible también mediante el registro de una función de callback con setEnabledFeaturesModifier(). Cuando se establece, la función callback es invocada, dejando que altere el VkPhysicalDeviceFeatures o VkPhysicalDeviceFeatures2.
Véase también QVulkanInstance y QWindow.
Documentación de los tipos de miembros
[since 6.7] QVulkanWindow::EnabledFeatures2Modifier
Una función que es llamada durante la inicialización de gráficos para alterar el VkPhysicalDeviceFeatures2 que es cambiado al VkDeviceCreateInfo.
Por defecto QVulkanWindow habilita todas las características del núcleo Vulkan 1.0 que el dispositivo físico reporta como soportadas, con ciertas excepciones. En la práctica, robustBufferAccess está siempre deshabilitado para evitar problemas de rendimiento inesperados.
Sin embargo, esto no siempre es suficiente cuando se trabaja con funciones y extensiones Vulkan 1.1, 1.2 o 1.3. De ahí este mecanismo de devolución de llamada. Si sólo Vulkan 1.0 es relevante en tiempo de ejecución, utilice setEnabledFeaturesModifier() en su lugar.
La referencia VkPhysicalDeviceFeatures2 se pasa a la función callback con sType establecido, pero el resto a cero. Depende de la función cambiar los miembros a true, o configurar las cadenas pNext como considere oportuno.
Nota: Cuando establezca cadenas pNext, asegúrese de que los objetos referenciados tienen un tiempo de vida suficientemente largo, por ejemplo almacenándolos como variables miembro en la subclase QVulkanWindow.
Este typedef se introdujo en Qt 6.7.
Véase también setEnabledFeaturesModifier().
QVulkanWindow::EnabledFeaturesModifier
Una función que se llama durante la inicialización de gráficos para alterar el VkPhysicalDeviceFeatures que se pasa al crear un objeto de dispositivo Vulkan.
Por defecto QVulkanWindow habilita todas las características principales de Vulkan 1.0 que el dispositivo físico reporta como soportadas, con ciertas excepciones. En la práctica, robustBufferAccess está siempre deshabilitado para evitar problemas de rendimiento inesperados.
La referencia VkPhysicalDeviceFeatures pasada se pone a cero cuando se invoca la función. Depende de la función cambiar los miembros como considere oportuno.
Nota: Para controlar las características de Vulkan 1.1, 1.2, o 1.3, utilice EnabledFeatures2Modifier en su lugar.
Véase también setEnabledFeaturesModifier().
enum QVulkanWindow::Flag
flags QVulkanWindow::Flags
Este enum describe las banderas que pueden pasarse a setFlags().
| Constante | Valor | Descripción |
|---|---|---|
QVulkanWindow::PersistentResources | 0x01 | Asegura que no se liberen recursos gráficos cuando la ventana se vuelve no expuesta. El comportamiento por defecto es liberar todo, y reinicializar más tarde cuando se hace visible de nuevo. |
El tipo Flags es un typedef para QFlags<Flag>. Almacena una combinación OR de valores Flag.
QVulkanWindow::QueueCreateInfoModifier
Función a la que se llama durante la inicialización de gráficos para añadir colas adicionales que deberían crearse.
Se establece si el renderizador necesita colas adicionales además de la cola de gráficos predeterminada (por ejemplo, una cola de transferencia). Las propiedades de la familia de colas proporcionadas pueden utilizarse para seleccionar los índices de las colas adicionales. Posteriormente, el renderizador puede solicitar la cola real en initResources().
Nota: Cuando se solicitan colas de gráficos adicionales, Qt siempre solicita una cola de gráficos. Tendrás que buscar en queueCreateInfo la entrada apropiada y manipularla para obtener la cola adicional.
Véase también setQueueCreateInfoModifier().
Documentación de las funciones miembro
[explicit] QVulkanWindow::QVulkanWindow(QWindow *parent = nullptr)
Construye una nueva QVulkanWindow con la dirección parent.
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 soportados en el sistema.
Nota: Se puede llamar a esta función antes de hacer visible la ventana.
QMatrix4x4 QVulkanWindow::clipCorrectionMatrix()
Devuelve un QMatrix4x4 que se puede utilizar para corregir las diferencias del sistema de coordenadas entre OpenGL y Vulkan.
Pre-multiplicando la matriz de proyección con esta matriz, las aplicaciones pueden continuar asumiendo que Y apunta hacia arriba, y pueden establecer minDepth y maxDepth en el viewport a 0 y 1, respectivamente, sin tener que hacer más correcciones a las posiciones Z de los vértices. La geometría de las aplicaciones OpenGL se puede utilizar tal cual, asumiendo un estado de rasterización que coincida con los ajustes de OpenGL.
VkFormat QVulkanWindow::colorFormat() const
Devuelve el formato del buffer de color utilizado por la swapchain.
Nota: La llamada a esta función sólo 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 tramas que pueden estar potencialmente activas al mismo tiempo.
Nota: El valor es constante durante toda la vida útil de 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 llama una vez durante la 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 aparte de limpiar los buffers.
La ventana toma posesión del objeto renderizador devuelto.
VkCommandBuffer QVulkanWindow::currentCommandBuffer() const
Devuelve el búfer de comandos activo para el marco de la cadena de intercambio actual. Se espera que las implementaciones de QVulkanWindowRenderer::startNextFrame() añadan comandos a este búfer de comandos.
Nota: Esta función sólo debe ser llamada 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 rango [0, concurrentFrameCount() - 1].
Las implementaciones del renderizador tendrán que asegurarse de que los datos uniformes y otros recursos dinámicos existan en múltiples copias, para 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 los tamaños dinámicos de las matrices, las aplicaciones pueden utilizar MAX_CONCURRENT_FRAME_COUNT al declarar las matrices. Se garantiza que siempre será igual o mayor que el valor devuelto por concurrentFrameCount(). Dichas matrices pueden entonces ser indexadas por 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 sólo debe ser llamada 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 swapchain actual usando el pase de renderizado por defecto.
El framebuffer tiene dos adjuntos (color, depth-stencil) cuando el multimuestreo no está en uso, y tres (color resolve, depth-stencil, multisample color) cuando sampleCountFlagBits() es mayor que VK_SAMPLE_COUNT_1_BIT. Los renderizadores deben tener esto en cuenta, por ejemplo cuando proporcionan valores claros.
Nota: Las aplicaciones no están obligadas a utilizar este framebuffer en caso de que proporcionen su propio render pass en lugar de utilizar el devuelto por defaultRenderPass().
Nota: Esta función sólo debe ser llamada 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 rango [0, swapChainImageCount() - 1].
Nota: Esta función sólo debe llamarse 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 pase de renderizado típico con un subpase.
Nota: Las aplicaciones no están obligadas a utilizar este pase de renderizado. Sin embargo, son responsables de garantizar que la cadena de intercambio actual y las imágenes de profundidad del esténcil pasen 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 pase de renderizado personalizado de la aplicación o por otros medios.
Nota: La lectura/escritura de stencils no está habilitada en este pase de renderizado.
Nota: La llamada a esta función sólo 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 el búfer o búferes de profundidad.
Nota: La llamada a esta función sólo es válida desde la invocación de QVulkanWindowRenderer::initResources() hasta QVulkanWindowRenderer::releaseResources().
VkImage QVulkanWindow::depthStencilImage() const
Devuelve la imagen de la plantilla de profundidad.
Nota: La llamada a esta función sólo es válida desde la invocación de QVulkanWindowRenderer::initSwapChainResources() hasta QVulkanWindowRenderer::releaseSwapChainResources().
VkImageView QVulkanWindow::depthStencilImageView() const
Devuelve la vista de la imagen del depth-stencil.
Nota: La llamada a esta función sólo 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 sólo 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 de dispositivo adecuado para uso general.
Nota: La llamada a esta función sólo es válida desde la invocación de QVulkanWindowRenderer::initResources() hasta QVulkanWindowRenderer::releaseResources().
Nota: No se garantiza que este tipo de memoria sea siempre adecuado. La solución correcta de implementación cruzada -especialmente para imágenes locales de dispositivo- es elegir manualmente un tipo de memoria después de comprobar la máscara devuelta por vkGetImageMemoryRequirements.
QVulkanWindow::Flags QVulkanWindow::flags() const
Devuelve las banderas solicitadas.
Véase también setFlags().
[signal] void QVulkanWindow::frameGrabbed(const QImage &image)
Esta señal se emite cuando la image está lista.
void QVulkanWindow::frameReady()
Esta función debe ser llamada exactamente una vez en respuesta a cada invocación de la implementación de QVulkanWindowRenderer::startNextFrame(). En el momento de esta llamada, el buffer de comandos principal, expuesto a través de currentCommandBuffer(), debe tener todos los comandos de renderizado necesarios añadidos, ya que esta función activará el envío de los comandos y la puesta en cola del comando actual.
Nota: Esta función sólo debe ser llamada desde el hilo gui/main, que es donde se invocan las funciones de QVulkanWindowRenderer y donde vive la instancia QVulkanWindow.
Véase también QVulkanWindowRenderer::startNextFrame().
QImage QVulkanWindow::grab()
Construye y renderiza el siguiente fotograma sin presentarlo y, a continuación, realiza una lectura de bloqueo del contenido de la imagen.
Devuelve la imagen si la implementación de startNextFrame() del renderizador llama directamente a frameReady(). En caso contrario, devuelve una imagen incompleta, que tiene el tamaño correcto pero aún no el contenido. En este último caso, el contenido se entregará a través de la señal frameGrabbed().
El QImage devuelto siempre tiene un formato de QImage::Format_RGBA8888. Si el 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 por defecto para los buffers de color swapchain. Con cualquier otro formato de búfer de color, esta función no realiza ninguna conversión.
Nota: Esta función no debe ser llamada cuando un fotograma está en progreso (es decir, frameReady() aún no ha sido llamado por la aplicación).
Nota: Esta función es potencialmente costosa debido al bloqueo adicional de la lectura.
Nota: Esta función requiere actualmente que la swapchain soporte el uso como fuente de transferencia (VK_IMAGE_USAGE_TRANSFER_SRC_BIT), y fallará en caso contrario.
VkCommandPool QVulkanWindow::graphicsCommandPool() const
Devuelve el conjunto de comandos gráficos activo.
Nota: La llamada a esta función sólo 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 sólo 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: Llamar a esta función sólo es válido 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á tanto visible para el host como coherente. Además, también se almacenará en caché, si es posible.
Nota: La llamada a esta función sólo es válida desde la invocación de QVulkanWindowRenderer::initResources() hasta QVulkanWindowRenderer::releaseResources().
bool QVulkanWindow::isValid() const
Devuelve true si esta ventana ha inicializado con éxito todos los recursos Vulkan, incluyendo el swapchain.
Nota: La inicialización ocurre en el primer evento de exposición después de que la ventana se hace visible.
VkImage QVulkanWindow::msaaColorImage(int idx) const
Devuelve la imagen en color multimuestreo especificada, o VK_NULL_HANDLE si no se utiliza el multimuestreo.
idx debe estar en el rango [0, swapChainImageCount() - 1].
Nota: La llamada a esta función sólo es válida desde la invocación de QVulkanWindowRenderer::initSwapChainResources() hasta QVulkanWindowRenderer::releaseSwapChainResources().
VkImageView QVulkanWindow::msaaColorImageView(int idx) const
Devuelve la vista de imagen en color multimuestreo especificada, o VK_NULL_HANDLE si no se utiliza el multimuestreo.
idx debe estar en el rango [0, swapChainImageCount() - 1].
Nota: La llamada a esta función sólo 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 sólo 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 sólo 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 VkSampleCountFlagBits.
Cuando el objetivo de renderizado es el 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 deben activarse.
Las extensiones no soportadas son ignoradas.
La extensión swapchain siempre se añadirá automáticamente, 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 efecto si se llama después.
[since 6.7] void QVulkanWindow::setEnabledFeaturesModifier(const QVulkanWindow::EnabledFeaturesModifier &modifier)
Establece la función de modificación de características de dispositivo habilitada modifier.
Nota: Para controlar las características de Vulkan 1.1, 1.2, o 1.3, utilice la sobrecarga tomando un EnabledFeatures2Modifier en su lugar.
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 habilitado modifier.
Esta es 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 basado en el flags proporcionado.
Nota: Esta función debe llamarse antes de que la ventana se haga visible o como muy tarde en QVulkanWindowRenderer::preInitResources(), y no tiene efecto si se llama después.
Véase también flags().
void QVulkanWindow::setPhysicalDeviceIndex(int idx)
Solicita el uso del dispositivo físico con índice idx. El índice corresponde a 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 como muy tarde en QVulkanWindowRenderer::preInitResources(), y no tiene efecto si se llama después.
void QVulkanWindow::setPreferredColorFormats(const QList<VkFormat> &formats)
Establece el formato preferido formats 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 en formats está ordenada. Si no se admite el primer formato, se considerará el segundo, y así sucesivamente. Cuando no se admite ningún formato de la lista, el comportamiento es el mismo que en el caso por defecto.
Para consultar el formato actual tras la inicialización, llame a colorFormat().
Nota: Esta función debe llamarse antes de que la ventana se haga visible o como muy tarde en QVulkanWindowRenderer::preInitResources(), y no tiene efecto si se llama después.
Nota: La reimplementación de QVulkanWindowRenderer::preInitResources() permite examinar dinámicamente la lista de formatos soportados, si así se desea. Allí la superficie es recuperable vía QVulkanInstace::surfaceForWindow(), mientras que esta función puede ser llamada con seguridad para afectar las etapas posteriores de inicialización.
Ver 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 el antialiasing multimuestra con el valor dado sampleCount. Los valores válidos son 1, 2, 4, 8, ... hasta el valor máximo soportado por el dispositivo físico.
Cuando el recuento de muestras es mayor que 1, QVulkanWindow creará un búfer de color multimuestra en lugar de simplemente apuntar a las imágenes del swapchain. El renderizado en el búfer multimuestra se resolverá en los búferes no multimuestra al final de cada fotograma.
Para examinar la lista de recuentos de muestras soportados, llame a supportedSampleCounts().
Al configurar el canal de renderizado, llame a sampleCountFlagBits() para consultar el recuento de muestras activo como un valor de VkSampleCountFlagBits.
Nota: Esta función debe invocarse antes de hacer visible la ventana o, como muy tarde, en QVulkanWindowRenderer::preInitResources(), y no tiene efecto si se invoca después.
Véase también supportedSampleCounts() y sampleCountFlagBits().
QVulkanInfoVector<QVulkanExtension> QVulkanWindow::supportedDeviceExtensions()
Devuelve la lista de las extensiones soportadas por los dispositivos lógicos creados a partir del dispositivo físico seleccionado por setPhysicalDeviceIndex().
Nota: Se puede llamar a esta función antes de hacer visible la ventana.
QList<int> QVulkanWindow::supportedSampleCounts()
Devuelve el conjunto de recuentos de muestras soportados cuando se utiliza el dispositivo físico seleccionado por setPhysicalDeviceIndex(), como una lista ordenada.
Por defecto QVulkanWindow utiliza un recuento de muestras de 1. Llamando a setSampleCount() con un valor diferente (2, 4, 8, ...) del conjunto devuelto por esta función, se puede solicitar antialiasing multimuestra.
Nota: Esta función puede llamarse antes de hacer visible la ventana.
Véase también setSampleCount().
bool QVulkanWindow::supportsGrab() const
Devuelve true si la swapchain admite el uso como fuente de transferencia, lo que significa que grab() es funcional.
Nota: La llamada a esta función sólo 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 en el rango [0, swapChainImageCount() - 1].
Nota: La llamada a esta función sólo es válida desde la invocación de QVulkanWindowRenderer::initSwapChainResources() hasta QVulkanWindowRenderer::releaseSwapChainResources().
int QVulkanWindow::swapChainImageCount() const
Devuelve el número de imágenes en la cadena de intercambio.
Nota: Es necesario acceder a esto cuando se proporciona un pase de renderizado y un framebuffer personalizados. El framebuffer es específico de la imagen swapchain actual y por lo tanto la aplicación debe proporcionar múltiples framebuffers.
Nota: La llamada a esta función sólo 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 swapchain.
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 superficie reportado por Vulkan es diferente con el escalado DPI alto activo, lo que significa que el QWindow-reportado size() multiplicado con el devicePixelRatio() era 1 pixel menos o más cuando se comparaba con el valor devuelto desde aquí, presumiblemente debido a diferencias en el redondeo. El código de renderizado debe ser consciente de esto, y cualquier lógica de renderizado relacionada debe basarse en el valor devuelto desde aquí, nunca en el tamaño reportado por QWindow. Independientemente del tamaño de píxel que sea correcto en teoría, el renderizado Vulkan sólo debe basarse en el tamaño de superficie indicado por la API Vulkan. De lo contrario, pueden producirse errores de validación, por ejemplo, al establecer la ventana gráfica, porque 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 sólo es válida desde la invocación de QVulkanWindowRenderer::initSwapChainResources() hasta QVulkanWindowRenderer::releaseSwapChainResources().
VkImageView QVulkanWindow::swapChainImageView(int idx) const
Devuelve la vista de la imagen de la cadena de intercambio especificada.
idx debe estar en el rango [0, swapChainImageCount() - 1].
Nota: La llamada a esta función sólo es válida desde la invocación de QVulkanWindowRenderer::initSwapChainResources() hasta QVulkanWindowRenderer::releaseSwapChainResources().
Documentación de variables miembro
const int QVulkanWindow::MAX_CONCURRENT_FRAME_COUNT
Esta variable contiene un valor constante que siempre es igual o mayor que el 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.
