En esta página

QVulkanInstance Class

La clase `QVulkanInstance` representa una instancia nativa de Vulkan, lo que permite el renderizado de Vulkan en un ` QSurface`. Más información...

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

Tipos públicos

DebugFilter
(since 6.5) enum DebugMessageSeverityFlag { VerboseSeverity, InfoSeverity, WarningSeverity, ErrorSeverity }
flags DebugMessageSeverityFlags
(since 6.5) enum DebugMessageTypeFlag { GeneralMessage, ValidationMessage, PerformanceMessage }
flags DebugMessageTypeFlags
(since 6.5) DebugUtilsFilter
enum Flag { NoDebugOutputRedirect, NoPortabilityDrivers }
flags Flags

Funciones públicas

QVulkanInstance()
~QVulkanInstance()
QVersionNumber apiVersion() const
(since 6.5) void clearDebugOutputFilters()
bool create()
void destroy()
QVulkanDeviceFunctions *deviceFunctions(VkDevice device)
VkResult errorCode() const
QByteArrayList extensions() const
QVulkanInstance::Flags flags() const
QVulkanFunctions *functions() const
PFN_vkVoidFunction getInstanceProcAddr(const char *name)
(since 6.5) void installDebugOutputFilter(QVulkanInstance::DebugUtilsFilter filter)
void installDebugOutputFilter(QVulkanInstance::DebugFilter filter)
bool isValid() const
QByteArrayList layers() const
void presentAboutToBeQueued(QWindow *window)
void presentQueued(QWindow *window)
void removeDebugOutputFilter(QVulkanInstance::DebugFilter filter)
void resetDeviceFunctions(VkDevice device)
void setApiVersion(const QVersionNumber &vulkanVersion)
void setExtensions(const QByteArrayList &extensions)
void setFlags(QVulkanInstance::Flags flags)
void setLayers(const QByteArrayList &layers)
void setVkInstance(VkInstance existingVkInstance)
QVersionNumber supportedApiVersion() const
QVulkanInfoVector<QVulkanExtension> supportedExtensions() const
QVulkanInfoVector<QVulkanLayer> supportedLayers() const
bool supportsPresent(VkPhysicalDevice physicalDevice, uint32_t queueFamilyIndex, QWindow *window)
VkInstance vkInstance() const

Miembros públicos estáticos

VkSurfaceKHR surfaceForWindow(QWindow *window)

Descripción detallada

Vulkan es una API multiplataforma para gráficos y cálculo explícito. Esta clase permite cargar una biblioteca de Vulkan y crear una instancia de « instance » de forma multiplataforma. Para obtener una introducción sobre las instancias de Vulkan, consulte la sección 3.2 de la especificación.

Nota: Los distintos complementos deplataforma proporcionan compatibilidadespecífica con las instancias de Vulkan y las ventanas con superficies compatibles con Vulkan. Sin embargo, no todos ellos serán compatibles con Vulkan. Al ejecutarse en una plataforma de este tipo, la llamada ` create()` fallará y siempre devolverá ` false`.

Nota: La compatibilidadcon Vulkan puede desactivarse automáticamente para una compilación determinada de Qt debido a que no se dispone de los encabezados de Vulkan necesarios en el momento de la compilación. Cuando esto ocurra, y el resultado de configure indique que la compatibilidad con Vulkan está desactivada, las clases QVulkan* no estarán disponibles.

Nota: Algunas funciones han cambiado su firma entre las distintas revisiones de los encabezados de Vulkan. Al compilar Qt, si en el sistema solo están presentes encabezados con las firmas antiguas y conflictivas, se desactivará la compatibilidad con Vulkan. Se recomienda utilizar encabezados de Vulkan 1.0.39 o posteriores.

Inicialización

Al igual que en QOpenGLContext, la creación efectiva de una instancia de Vulkan solo se produce al llamar a create(). Esto permite utilizar QVulkanInstance como una variable miembro simple, al tiempo que se mantiene el control sobre cuándo realizar la inicialización.

Es posible consultar las capas y extensiones compatibles a nivel de instancia llamando a ` supportedLayers()` y ` supportedExtensions()`. Estas funciones garantizan que la biblioteca Vulkan esté cargada, por lo que también pueden llamarse de forma segura antes de ` create()`.

Las instancias almacenan el estado de Vulkan por aplicación y la creación de un objeto ` VkInstance ` inicializa la biblioteca de Vulkan. En la práctica, normalmente se creará una única instancia al principio de la función `main()`. A continuación, el objeto permanece activo hasta que se cierra la aplicación.

Cada ` QWindow ` basado en Vulkan debe asociarse a una `QVulkanInstance` llamando a ` QWindow::setVulkanInstance()`. Por lo tanto, un patrón típico de aplicación es el siguiente:

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

        QVulkanInstance inst;
        if (!inst.create())
            return 1;

        // ...
        window->setVulkanInstance(&inst);
        window->show();

        return app.exec();
    }

Configuración

QVulkanInstance habilita automáticamente el conjunto mínimo de extensiones que necesita en la instancia recién creada. En la práctica, esto significa la familia de extensiones « VK_KHR_*_surface ».

Por defecto, la salida de depuración de Vulkan, por ejemplo, los mensajes de las capas de validación, se redirige a qDebug(). Esto se puede desactivar pasando el indicador NoDebugOutputRedirect a setFlags() antes de invocar create().

Para habilitar capas y extensiones adicionales, se debe proporcionar la lista mediante setLayers() y setExtensions() antes de invocar create(). Cuando una capa o extensión determinada no aparece como disponible en la instancia, la solicitud se ignora. Tras una llamada correcta a ` create()` (), los valores devueltos por funciones como ` layers()` (y ` extensions()`) reflejan las capas y extensiones realmente habilitadas. Cuando sea necesario, por ejemplo, para evitar solicitar extensiones que entren en conflicto y, por lo tanto, provoquen un error en la creación de la instancia de Vulkan, se puede examinar la lista de capas y extensiones realmente compatibles mediante ` supportedLayers()` (y ` supportedExtensions()`) antes de llamar a ` create()`.

Por ejemplo, para habilitar las capas de validación estándar, se podría hacer lo siguiente:

    QVulkanInstance inst;

    // Enable validation layer, if supported. Messages go to qDebug by default.
    inst.setLayers({ "VK_LAYER_KHRONOS_validation" });

    bool ok = inst.create();
    if (!ok) {
        // ... Vulkan not available
    }

    if (!inst.layers().contains("VK_LAYER_KHRONOS_validation")) {
        // ... validation layer not available
    }

O, como alternativa, para tomar decisiones antes de intentar crear una instancia de Vulkan:

    QVulkanInstance inst;

    if (inst.supportedLayers().contains("VK_LAYER_KHRONOS_validation")) {
        // ...
    }
    bool ok = inst.create();
    // ...

Adopción de una instancia existente

Por defecto, `QVulkanInstance` crea una nueva instancia de Vulkan. Al trabajar con motores y renderizadores externos, esto puede no ser lo más adecuado en algunas ocasiones. Cuando ya haya un identificador de ` VkInstance ` disponible, llama a ` setVkInstance()` antes de invocar ` create()`. De esta forma, no se crearán instancias adicionales y `QVulkanInstance` no será propietario del identificador.

Nota: Corresponde al componente que crea la instancia externa asegurarse de que las extensiones necesarias estén habilitadas en ella. Estas son: VK_KHR_surface, el VK_KHR_*_surface específico de WSI adecuado para la plataforma en cuestión y VK_EXT_debug_utils, en caso de que se desee redirigir la salida de depuración de QVulkanInstance.

Acceso a los comandos principales de Vulkan

Para acceder al identificador VkInstance que envuelve QVulkanInstance, llama a vkInstance(). Para resolver funciones de Vulkan, llama a getInstanceProcAddr(). Para los comandos básicos de Vulkan no es necesaria la resolución manual, ya que se proporcionan a través de los objetos QVulkanFunctions y QVulkanDeviceFunctions, a los que se puede acceder mediante functions() y deviceFunctions().

Nota: QVulkanFunctions y QVulkanDeviceFunctions se generan a partir de las especificaciones XML de la API de Vulkan al compilar las bibliotecas de Qt. Por lo tanto, no se proporciona documentación sobre ellas. Contienen las funciones de Vulkan 1.2 con las mismas firmas que se describen en la documentación de la API de Vulkan.

Obtener una superficie nativa de Vulkan para una ventana

Las dos operaciones específicas del sistema de ventanas más habituales son obtener una superficie (un identificador de VkSurfaceKHR ) para una ventana y consultar si una familia de colas determinada admite la presentación en una superficie concreta. Para evitar elementos específicos de WSI en las aplicaciones, estas operaciones se abstraen mediante QVulkanInstance y las capas QPA subyacentes.

Para crear una superficie Vulkan para una ventana, o recuperar una ya existente, llama a ` surfaceForWindow()` (). La mayoría de las plataformas solo crearán la superficie mediante VK_KHR_*_surface al llamar por primera vez a surfaceForWindow(), pero puede haber variaciones específicas de cada plataforma en el comportamiento interno. Una vez creada, las llamadas posteriores a surfaceForWindow() simplemente devuelven el mismo identificador. Esto se adapta bien a la estructura de las subclases típicas de QWindow compatibles con Vulkan.

Para comprobar si una familia de colas determinada dentro de un dispositivo físico puede utilizarse para realizar la presentación en una superficie determinada, llama a ` supportsPresent()`. Esto encapsula tanto la comprobación genérica ` vkGetPhysicalDeviceSurfaceSupportKHR ` como la específica de WSI ` vkGetPhysicalDevice*PresentationSupportKHR `.

Resolución de problemas

Además de devolver « false » desde ` create()` o « 0 » desde ` surfaceForWindow()`, los errores críticos también se mostrarán en la salida de depuración mediante ` qWarning()`. Se puede solicitar un registro adicional habilitando la salida de depuración para la categoría de registro « qt.vulkan ». El código de error real de Vulkan correspondiente a la creación de la instancia se puede recuperar llamando a ` errorCode()` tras un fallo en ` create()`.

En algunos casos especiales, puede ser necesario anular el nombre de la biblioteca Vulkan. Esto se puede lograr configurando la variable de entorno QT_VULKAN_LIB.

Ejemplo

A continuación se muestra el esquema básico para crear un ` QWindow` compatible con Vulkan:

class VulkanWindow : public QWindow
{
public:
    VulkanWindow() {
        setSurfaceType(VulkanSurface);
    }

    void exposeEvent(QExposeEvent*) {
        if (isExposed()) {
            if (!m_initialized) {
                m_initialized = true;
                // inicializar el dispositivo, la cadena de intercambio, etc.
                QVulkanInstance*inst = vulkanInstance();
                QVulkanFunctions*f = inst->functions();
                uint32_t devCount = 0;
                f->vkEnumeratePhysicalDevices(inst->vkInstance(), &devCount, nullptr);
                // ...
               // crear el primer fotograma
                render();
            }
        }
    }

    bool event(QEvent*e) {
        if (e->type()== QEvent::UpdateRequest)
            render();
        return QWindow::event(e);
    }

   void render() {
       // ...
       requestUpdate(); // renderizar de forma continua
    }

private:
    bool m_initialized = false;
};

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

    QVulkanInstance inst;
    if (!inst.create()) {
        qWarning("Vulkan not available");
       return 1;
    }

    VulkanWindow window;
    window.showMaximized();

    return app.exec();

}

Nota: Además de la función «expose», una implementación de ventana que funcione correctamente también deberá gestionar eventos adicionales como «resize» y « QPlatformSurfaceEvent » para garantizar una gestión adecuada de la cadena de intercambio. Además, algunas plataformas pueden requerir la liberación de recursos cuando ya no se exponga la ventana.

Uso de los enlaces de C++ para Vulkan

También es posible combinar los habilitadores de Vulkan de Qt con un envoltorio de Vulkan para C++, como por ejemplo Vulkan-Hpp. El requisito previo en este caso es que la capa de C++ debe poder adoptar identificadores nativos (VkInstance, VkSurfaceKHR) en sus clases sin asumir la propiedad (ya que la propiedad sigue recayendo en QVulkanInstance y QWindow). Ten en cuenta también lo siguiente:

  • Algunas envoltorias requieren que se habilite el soporte de excepciones. Qt no utiliza excepciones. Para habilitar las excepciones en la aplicación, añade CONFIG += exceptions al archivo .pro.
  • Algunos envoltorios llaman directamente a funciones de Vulkan, dando por hecho que ` vulkan.h ` proporciona los prototipos y que la aplicación se enlaza a una biblioteca de Vulkan que exporta todos los símbolos necesarios. Es posible que Qt no se enlace directamente a una biblioteca de Vulkan. Por lo tanto, en algunas plataformas puede ser necesario añadir ` LIBS += -lvulkan ` o algo similar en el archivo ` .pro ` de la aplicación.
  • Los encabezados de las clases QVulkan pueden incluir vulkan.h con VK_NO_PROTOTYPES activado. Esto puede causar problemas en los encabezados de los envoltorios de C++ que dependen de los prototipos. Por lo tanto, en el código de la aplicación puede ser necesario incluir vulkan.hpp o algo similar antes de cualquiera de los encabezados de QVulkan.

Consideraciones de seguridad

La implementación de Vulkan —es decir, el cargador de Vulkan, los controladores y cualquier capa habilitada— es una dependencia de la plataforma de confianza que se ejecuta en el mismo proceso. Qt la carga y la invoca directamente, sin ningún tipo de aislamiento en un entorno de pruebas ni verificación, del mismo modo que trata la implementación de OpenGL.

Se espera que todos los datos utilizados por `QVulkanInstance` y las clases que se basan en ella, como ` QVulkanWindow ` y ` QRhi ` con su backend de Vulkan, sean contenido de confianza. Esto incluye los nombres de capas y extensiones pasados a ` setLayers()` y ` setExtensions()`, un identificador nativo ` VkInstance ` obtenido mediante ` setVkInstance()`, y todo el contenido de renderizado y los parámetros de comando de Vulkan generados por la aplicación.

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 QVulkanFunctions y QSurface::SurfaceType.

Documentación sobre tipos de miembros

QVulkanInstance::DebugFilter

Definición de tipo para funciones de devolución de llamada de filtrado de depuración, con la siguiente firma:

bool myDebugFilter(VkDebugReportFlagsEXT flags, VkDebugReportObjectTypeEXT objectType, uint64_t object,
                   size_t location, int32_t messageCode, const char *pLayerPrefix, const char *pMessage)

Si se devuelve ` true `, se suprime la visualización del mensaje.

Nota: A partir de Qt 6.5, se utiliza ` VK_EXT_debug_utils ` en lugar de ` VK_EXT_debug_report`, que ha quedado obsoleto. La firma de la función de devolución de llamada se basa en `VK_EXT_debug_report`. Por lo tanto, no cabe esperar que todos los argumentos sigan siendo válidos. Evita depender de argumentos distintos de ` pMessage`, ` messageCode` y ` object`. Las aplicaciones que deseen acceder a todos los datos de la función de devolución de llamada tal y como se especifican en `VK_EXT_debug_utils` deben migrar a ` DebugUtilsFilter`.

Véanse también installDebugOutputFilter() y removeDebugOutputFilter().

[since 6.5] enum QVulkanInstance::DebugMessageSeverityFlag
flags QVulkanInstance::DebugMessageSeverityFlags

ConstanteValor
QVulkanInstance::VerboseSeverity0x01
QVulkanInstance::InfoSeverity0x02
QVulkanInstance::WarningSeverity0x04
QVulkanInstance::ErrorSeverity0x08

Esta enumeración se introdujo en Qt 6.5.

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

[since 6.5] enum QVulkanInstance::DebugMessageTypeFlag
flags QVulkanInstance::DebugMessageTypeFlags

ConstanteValor
QVulkanInstance::GeneralMessage0x01
QVulkanInstance::ValidationMessage0x02
QVulkanInstance::PerformanceMessage0x04

Esta enumeración se introdujo en Qt 6.5.

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

[alias, since 6.5] QVulkanInstance::DebugUtilsFilter

Definición de tipo para funciones de devolución de llamada de filtrado de depuración, con la siguiente firma:

std::function<bool(DebugMessageSeverityFlags severity, DebugMessageTypeFlags type, const void *message)>;

El argumento ` message ` es un puntero a la estructura `VkDebugUtilsMessengerCallbackDataEXT`. Consulta la documentación de VK_EXT_debug_utils para obtener más detalles. Los encabezados de Qt no utilizan el tipo real para evitar introducir una dependencia de los encabezados de Vulkan posteriores a la versión 1.0.

Al devolver ` true ` se suprime la visualización del mensaje.

Este typedef se introdujo en Qt 6.5.

Véase también installDebugOutputFilter() y removeDebugOutputFilter().

enum QVulkanInstance::Flag
flags QVulkanInstance::Flags

Esta enumeración describe los parámetros que se pueden pasar a la función ` setFlags()`. Estos controlan el comportamiento de la función ` create()`.

ConstanteValorDescripción
QVulkanInstance::NoDebugOutputRedirect0x01Desactiva la redirección de la salida de depuración de Vulkan (VK_EXT_debug_utils) a qDebug.
QVulkanInstance::NoPortabilityDrivers (since Qt 6.5)0x02Desactiva la enumeración de dispositivos físicos marcados como «Vulkan Portability».

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

Documentación de las funciones miembro

QVulkanInstance::QVulkanInstance()

Crea una nueva instancia.

Nota: En el constructorno se lleva a caboninguna inicialización de Vulkan.

[noexcept] QVulkanInstance::~QVulkanInstance()

Destructor.

Nota: ` vkInstance()` devolverá ` nullptr ` una vez que se haya destruido la instancia.

QVersionNumber QVulkanInstance::apiVersion() const

Devuelve la versión de la API de Vulkan solicitada con la que la aplicación espera ejecutarse, o un número de versión nulo si no se ha llamado a setApiVersion() antes de create().

Véase también setApiVersion().

[since 6.5] void QVulkanInstance::clearDebugOutputFilters()

Elimina todas las funciones de filtro instaladas previamente mediante installDebugOutputFilter().

Nota: Esta función se puede llamar antes de create().

Esta función se introdujo en Qt 6.5.

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

bool QVulkanInstance::create()

Inicializa la biblioteca Vulkan y crea una nueva instancia de Vulkan o adopta una ya existente.

Devuelve «true» si se realiza correctamente, «false» en caso de error o cuando Vulkan no es compatible.

Si se realiza correctamente, se puede recuperar el puntero a este ` QVulkanInstance ` mediante ` vkInstance()`.

La instancia y la biblioteca de Vulkan estarán disponibles mientras exista este ` QVulkanInstance `, o hasta que se llame a ` destroy()`.

De forma predeterminada, la VkInstance se crea con el indicador VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR activado. Esto significa que también se enumeran los dispositivos físicos de Vulkan Portability. Si no se desea que esto ocurra, se debe establecer el indicador NoPortabilityDrivers.

void QVulkanInstance::destroy()

Elimina la instancia de la plataforma subyacente, con lo que se elimina la VkInstance (cuando se posee). El objeto ` QVulkanInstance ` sigue siendo reutilizable llamando de nuevo a ` create()`.

QVulkanDeviceFunctions *QVulkanInstance::deviceFunctions(VkDevice device)

Devuelve el objeto ` QVulkanDeviceFunctions `, que expone el conjunto básico de comandos de Vulkan a nivel de dispositivo y cuya funcionalidad está garantizada en todas las plataformas.

Nota: Las funciones de Vulkan del objeto devuelto solo deben invocarse con ` device ` o un objeto secundario (VkQueue, VkCommandBuffer) de ` device ` como primer parámetro. Esto se debe a que estas funciones se resuelven mediante `vkGetDeviceProcAddr` para evitar la posible sobrecarga que supone el despacho interno.

Nota: El objeto devuelto es propiedad de QVulkanInstance y está gestionado por este. No lo destruyas ni lo modifiques.

Nota: El objeto se almacena en caché, por lo que volver a llamar a esta función con el mismo device es una operación de bajo coste. Sin embargo, cuando el dispositivo se destruye, corresponde a la aplicación notificarlo al QVulkanInstance llamando a resetDeviceFunctions().

Las funciones de la API principal de Vulkan 1.0 estarán siempre disponibles. En cuanto a las versiones superiores de Vulkan, como la 1.1 y la 1.2, el objeto QVulkanDeviceFunctions intentará resolver también las funciones de la API principal para dichas versiones; sin embargo, si el dispositivo físico de Vulkan en tiempo de ejecución no las admite, llamar a cualquiera de esas funciones no compatibles dará lugar a un comportamiento no especificado. Para habilitar correctamente la compatibilidad con versiones de Vulkan superiores a la 1.0, puede ser necesario establecer una versión adecuada de la API de instancia llamando a ` setApiVersion()` antes de ` create()`. Además, se espera que las aplicaciones comprueben el valor de « apiVersion » del dispositivo físico en `VkPhysicalDeviceProperties`.

Véanse también functions() y resetDeviceFunctions().

VkResult QVulkanInstance::errorCode() const

Devuelve el código de error de Vulkan tras una llamada fallida a ` create()`; en caso contrario, devuelve ` VK_SUCCESS `.

El valor suele ser el valor devuelto por vkCreateInstance() (al crear una nueva instancia de Vulkan en lugar de adoptar una ya existente), pero también puede ser « VK_NOT_READY » si el complemento de la plataforma no es compatible con Vulkan.

QByteArrayList QVulkanInstance::extensions() const

Devuelve las extensiones de instancia habilitadas, siempre que se haya llamado a ` create()` y la llamada haya tenido éxito. En caso contrario, devuelve las extensiones solicitadas.

Véase también setExtensions().

QVulkanInstance::Flags QVulkanInstance::flags() const

Devuelve los indicadores solicitados.

Véase también setFlags().

QVulkanFunctions *QVulkanInstance::functions() const

Devuelve el objeto QVulkanFunctions correspondiente, que expone el conjunto básico de comandos de Vulkan —excluidas las funciones a nivel de dispositivo— y cuya funcionalidad está garantizada en todas las plataformas.

Nota: El objeto devuelto es propiedad de QVulkanInstance y está gestionado por este. No lo destruyas ni lo modifiques.

Las funciones de la API básica de Vulkan 1.0 estarán siempre disponibles. En el caso de versiones superiores de Vulkan, como la 1.1 y la 1.2, el objeto ` QVulkanFunctions ` intentará resolver también las funciones de la API básica para dichas versiones, pero si la implementación de la instancia de Vulkan en tiempo de ejecución no las admite, llamar a cualquiera de esas funciones no compatibles dará lugar a un comportamiento no especificado. Además, para habilitar correctamente la compatibilidad con versiones de Vulkan superiores a la 1.0, puede ser necesario establecer una versión adecuada de la API de la instancia llamando a ` setApiVersion()` antes de ` create()`. Para consultar la versión a nivel de instancia de la implementación de Vulkan, llama a ` supportedApiVersion()`.

Véase también deviceFunctions() y supportedApiVersion().

PFN_vkVoidFunction QVulkanInstance::getInstanceProcAddr(const char *name)

Resuelve la función de Vulkan con el name proporcionado.

Para los comandos básicos de Vulkan, es preferible utilizar las envolventas de funciones que se pueden obtener en functions() y deviceFunctions().

[since 6.5] void QVulkanInstance::installDebugOutputFilter(QVulkanInstance::DebugUtilsFilter filter)

Instala una función de « filter » que se invoca cada vez que se genera un mensaje de depuración de Vulkan. Cuando la función de devolución devuelve « true », el mensaje se detiene (se filtra) y no aparecerá en la salida de depuración.

Nota: El filtrado solo es efectivo cuando NoDebugOutputRedirect no es set. En caso contrario, la instalación de filtros no tiene ningún efecto.

Nota: Esta función se puede llamar antes de create().

Esta función se introdujo en Qt 6.5.

Véase también clearDebugOutputFilters().

void QVulkanInstance::installDebugOutputFilter(QVulkanInstance::DebugFilter filter)

Instala una función ` filter ` que se invoca cada vez que se genera un mensaje de depuración de Vulkan. Cuando la función de devolución devuelve ` true`, el mensaje se detiene (se filtra) y no aparecerá en la salida de depuración.

Nota: El filtrado solo es efectivo cuando NoDebugOutputRedirect no es set. De lo contrario, la instalación de filtros no tiene ningún efecto.

Nota: Esta función se puede llamar antes de create().

Se trata de una función sobrecargada.

Véase también removeDebugOutputFilter().

bool QVulkanInstance::isValid() const

Devuelve «true» si la función ` create()` se ha ejecutado correctamente y la instancia es válida.

QByteArrayList QVulkanInstance::layers() const

Devuelve las capas de la instancia que están habilitadas, si se ha llamado a create() y la operación se ha realizado correctamente. De lo contrario, devuelve las capas solicitadas.

Véase también setLayers().

void QVulkanInstance::presentAboutToBeQueued(QWindow *window)

El renderizador de la aplicación debe llamar a esta función antes de poner en cola una operación de presentación para « window ».

Aunque en algunas plataformas esto no tendrá ningún efecto, en otras puede realizar una sincronización dependiente del sistema de ventanas. Por ejemplo, en Wayland esto añadirá el envío de una solicitud wl_surface.frame para evitar que el controlador se bloquee con las ventanas minimizadas.

void QVulkanInstance::presentQueued(QWindow *window)

El renderizador de la aplicación debe llamar a esta función tras poner en cola una operación de presentación para window.

Aunque en algunas plataformas esto no tendrá ningún efecto, en otras puede que se realice una sincronización dependiente del sistema de ventanas. Por ejemplo, en X11 esto actualizará _NET_WM_SYNC_REQUEST_COUNTER.

void QVulkanInstance::removeDebugOutputFilter(QVulkanInstance::DebugFilter filter)

Elimina una función de filter instalada previamente mediante installDebugOutputFilter().

Nota: Esta función se puede llamar antes de create().

Véase también installDebugOutputFilter().

void QVulkanInstance::resetDeviceFunctions(VkDevice device)

Invalida y destruye el objeto ` QVulkanDeviceFunctions ` correspondiente al ` device` indicado.

Esta función debe llamarse cuando un VkDevice, para el que se haya llamado a deviceFunctions(), se destruya mientras la aplicación pretende seguir ejecutándose, con la posibilidad de crear un nuevo dispositivo lógico de Vulkan más adelante.

No es necesario llamar a esta función antes de destruir el ` QVulkanInstance `, ya que la limpieza se realiza automáticamente en ese momento.

Véase también deviceFunctions().

void QVulkanInstance::setApiVersion(const QVersionNumber &vulkanVersion)

Especifica la versión más alta de la API de Vulkan para la que está diseñada la aplicación.

Por defecto, ` vulkanVersion ` es 0, lo que se corresponde con Vulkan 1.0.

Nota: Esta función solo se puede invocar antes de create() y no tiene ningún efecto si se invoca después.

Nota: Ten en cuenta que Vulkan 1.1 cambia el comportamiento en lo que respecta al campo de versión de la API de Vulkan. En Vulkan 1.0, especificar un vulkanVersion no compatible provocaba que create() fallara con el error « VK_ERROR_INCOMPATIBLE_DRIVER », tal y como exigía la especificación. A partir de Vulkan 1.1, la especificación no permite esto, por lo que el controlador debe aceptar cualquier versión sin que falle la creación de la instancia.

Se recomienda a los desarrolladores de aplicaciones que se familiaricen con las notas sobre « apiVersion » en la especificación de Vulkan.

Véanse también apiVersion() y supportedApiVersion().

void QVulkanInstance::setExtensions(const QByteArrayList &extensions)

Especifica la lista de extensiones de instancia adicionales extensions que se deben habilitar. No supone ningún riesgo especificar también extensiones no compatibles, ya que estas se ignoran cuando no son compatibles en tiempo de ejecución.

Nota: Las extensiones relacionadas con las superficies que requiere Qt (por ejemplo, VK_KHR_win32_surface) siempre se añadirán automáticamente, por lo que no es necesario incluirlas en esta lista.

Nota: VK_KHR_portability_enumeration se añade automáticamente a menos que se active el indicador « NoPortabilityDrivers ». Este valor se introdujo en Qt 6.5.

Nota: Esta función solo se puede llamar antes de create() y no tiene ningún efecto si se llama después.

Véase también extensions().

void QVulkanInstance::setFlags(QVulkanInstance::Flags flags)

Configura el comportamiento de ` create()` en función del ` flags` proporcionado.

Nota: Esta función solo se puede invocar antes de create() y no tiene ningún efecto si se invoca después.

Véase también flags().

void QVulkanInstance::setLayers(const QByteArrayList &layers)

Especifica la lista de capas de instancia layers que se van a habilitar. No supone ningún riesgo especificar también capas no compatibles, ya que estas se ignoran en tiempo de ejecución si no son compatibles.

Nota: Esta función solo se puede llamar antes de ` create()` y no tiene ningún efecto si se llama después.

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

void QVulkanInstance::setVkInstance(VkInstance existingVkInstance)

Hace que ` QVulkanInstance ` adopte un identificador de `VkInstance` ya existente en lugar de crear uno nuevo.

Nota: « existingVkInstance » debe tener habilitadas al menos las extensiones « VK_KHR_surface » y las extensiones específicas de WSI « VK_KHR_*_surface » correspondientes. Para garantizar que la redirección de la salida de depuración funcione correctamente, también es necesario « VK_EXT_debug_utils ».

Qt no dispone de ningún medio para habilitar capas y extensiones en una VkInstance ya creada. Por lo tanto, es responsabilidad del llamante asegurarse de que existingVkInstance sea adecuado para su uso con Qt. Si se utiliza renderizado basado en QRhi, llame a QRhiVulkanInitParams::preferredInstanceExtensions() para consultar una lista adicional de extensiones de instancia que debería habilitar el creador de existingVkInstance, además de las extensiones mencionadas anteriormente, siempre que estén disponibles y sean compatibles con el sistema en tiempo de ejecución.

Nota: Esta función solo se puede llamar antes de create() y no tiene ningún efecto si se llama después.

Véase también vkInstance().

QVersionNumber QVulkanInstance::supportedApiVersion() const

Devuelve la versión de la funcionalidad a nivel de instancia que admite la implementación de Vulkan.

En la práctica, se trata bien del valor devuelto por vkEnumerateInstanceVersion, si dicha función está disponible (a partir de Vulkan 1.1), bien del valor 1.0.

Las aplicaciones que deseen adaptar el uso de las características y la API de Vulkan en función de la versión de Vulkan disponible en tiempo de ejecución pueden utilizar esta función para determinar qué versión deben pasar a ` setApiVersion()` antes de llamar a ` create()`.

Nota: Esta función se puede llamar antes de create().

Véase también setApiVersion().

QVulkanInfoVector<QVulkanExtension> QVulkanInstance::supportedExtensions() const

Devuelve la lista de extensiones compatibles a nivel de instancia.

Nota: Esta función se puede invocar antes de create().

QVulkanInfoVector<QVulkanLayer> QVulkanInstance::supportedLayers() const

Devuelve la lista de capas a nivel de instancia compatibles.

Nota: Esta función se puede llamar antes de ` create()`.

bool QVulkanInstance::supportsPresent(VkPhysicalDevice physicalDevice, uint32_t queueFamilyIndex, QWindow *window)

Devuelve «true» si la familia de colas con queueFamilyIndex dentro de physicalDevice admite la presentación en window.

Llama a esta función al examinar las colas de un dispositivo Vulkan determinado, con el fin de decidir qué cola se puede utilizar para realizar la presentación.

[static] VkSurfaceKHR QVulkanInstance::surfaceForWindow(QWindow *window)

Crea o recupera el identificador de « VkSurfaceKHR » ya existente para el « window » indicado.

Devuelve el identificador de superficie de Vulkan o 0 en caso de fallo.

VkInstance QVulkanInstance::vkInstance() const

Devuelve el identificador VkInstance que envuelve esta función ` QVulkanInstance `, o ` nullptr ` si aún no se ha llamado correctamente a ` create()` y no se ha proporcionado ninguna instancia existente mediante ` setVkInstance()`.

Véase también setVkInstance().

© 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.