Vulkan. Guía del desarrollador. Dibuja un triangulo

Soy traductor en CG Tribe en Izhevsk y sigo cargando traducciones del manual de la API de Vulkan. Enlace fuente: vulkan-tutorial.com .



Esta publicación está dedicada a la traducción de la sección Dibujar un triángulo, es decir, la subsección Configuración, los capítulos Código base e Instancia.

Código base

• Estructura general
• Administracion de recursos
• Integración GLFW

Estructura general

En el capítulo anterior, cubrimos cómo crear un proyecto para Vulkan, configurarlo correctamente y probarlo usando un fragmento de código. En este capítulo, comenzaremos con lo básico.



Considere el siguiente código:

#include <vulkan/vulkan.h>

#include <iostream>
#include <stdexcept>
#include <cstdlib>

class HelloTriangleApplication {
public:
    void run() {
        initVulkan();
        mainLoop();
        cleanup();
    }

private:
    void initVulkan() {

    }

    void mainLoop() {

    }

    void cleanup() {

    }
};

int main() {
    HelloTriangleApplication app;

    try {
        app.run();
    } catch (const std::exception& e) {
        std::cerr << e.what() << std::endl;
        return EXIT_FAILURE;
    }

    return EXIT_SUCCESS;
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Primero, incluimos el archivo de encabezado Vulkan del SDK de LunarG. Los archivos de encabezado stdexcepts



y iostream



se utilizan para el manejo y distribución de errores. El archivo de encabezado cstdlib



proporciona macros EXIT_SUCCESS



y EXIT_FAILURE



.



El programa en sí está envuelto en la clase HelloTriangleApplication, en la que almacenaremos los objetos Vulkan como miembros privados de la clase. Allí también agregaremos funciones para inicializar cada objeto, llamado desde la función initVulkan



. Después de eso, creemos un bucle principal para renderizar cuadros. Para hacer esto, complete una función mainLoop



donde se ejecutará el ciclo hasta que se cierre la ventana. Después de cerrar la ventana y salir, los mainLoop



recursos deben liberarse. Para hacer esto, complete cleanup



.



Si ocurre un error crítico durante la operación, lanzaremos una excepción std::runtime_error



que quedará atrapada en la función main



y la descripción se mostrará en formato std::cerr



. Uno de esos errores podría ser, por ejemplo, un mensaje de que la extensión requerida no es compatible. Para manejar muchos de los tipos estándar de excepciones, capturamos una más general std::exception



.



Casi todos los capítulos posteriores agregarán nuevas funciones que se llaman desde initVulkan



y nuevos objetos Vulkan que deben liberarse al cleanup



final del programa.

Administracion de recursos

Si los objetos Vulkan ya no son necesarios, deben destruirse. C ++ le permite desasignar recursos automáticamente mediante RAII o punteros inteligentes proporcionados por el archivo de encabezado <memory>



. Sin embargo, en este tutorial decidimos escribir explícitamente cuándo asignar y desasignar objetos Vulkan. Después de todo, esta es la peculiaridad del trabajo de Vulkan: describir en detalle cada operación para evitar posibles errores.



Después de leer el tutorial, puede implementar la administración automática de recursos escribiendo clases C ++ que reciben objetos Vulkan en el constructor y los liberan en el destructor. También puede implementar su propio eliminador para std::unique_ptr



o std::shared_ptr



, según sus requisitos. El concepto RAII se recomienda para programas más grandes, pero es útil aprender más sobre él.



Los objetos Vulkan se crean directamente usando una función como vkCreateXXX , o se asignan a través de otro objeto usando una función como vkAllocateXXX . Después de asegurarse de que el objeto no esté en uso en ningún otro lugar, debe destruirlo con vkDestroyXXX o vkFreeXXX . Los parámetros para estas características por lo general varían en función del tipo de objeto, pero hay un parámetro común: pAllocator



. Este es un parámetro opcional que le permite utilizar devoluciones de llamada para la asignación de memoria personalizada. No lo necesitaremos en el manual, lo pasaremos como argumento nullptr



.

Integración GLFW

Vulkan funciona bien sin crear una ventana cuando se usa el renderizado fuera de la pantalla, pero mucho mejor cuando el resultado es visible en la pantalla.

Primero, reemplace la línea con lo #include <vulkan/vulkan.h>



siguiente:

#define GLFW_INCLUDE_VULKAN
#include <GLFW/glfw3.h>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Agregue una función initWindow



y agregue su llamada desde el método run



antes que otras llamadas. Usaremos initWindow



GLFW para inicializar y crear una ventana.

void run() {
    initWindow();
    initVulkan();
    mainLoop();
    cleanup();
}

private:
    void initWindow() {

    }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

La primera llamada a initWindow



debe ser una función glfwInit()



que inicialice la biblioteca GLFW. GLFW fue diseñado originalmente para funcionar con OpenGL. No necesitamos un contexto OpenGL, así que indique que no necesitamos crearlo usando la siguiente llamada:

glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Desactive temporalmente la capacidad de cambiar el tamaño de la ventana, ya que manejar esta situación requiere una consideración por separado:

glfwWindowHint(GLFW_RESIZABLE, GLFW_FALSE);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Queda por crear una ventana. Para hacer esto, agregue un miembro privado GLFWwindow* window;



e inicialice la ventana con:

window = glfwCreateWindow(800, 600, "Vulkan", nullptr, nullptr);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Los primeros tres parámetros definen el ancho, alto y título de la ventana. El cuarto parámetro es opcional, le permite especificar el monitor en el que se mostrará la ventana. El último parámetro es específico de OpenGL.



Sería bueno usar constantes para el ancho y alto de la ventana, ya que necesitaremos estos valores en otros lugares. Agregue las siguientes líneas antes de la definición de clase HelloTriangleApplication



:

const uint32_t WIDTH = 800;
const uint32_t HEIGHT = 600;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

y reemplace la llamada para crear una ventana con

window = glfwCreateWindow(WIDTH, HEIGHT, "Vulkan", nullptr, nullptr);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Deberías tener la siguiente función initWindow



:

void initWindow() {
    glfwInit();

    glfwWindowHint(GLFW_CLIENT_API, GLFW_NO_API);
    glfwWindowHint(GLFW_RESIZABLE, GLFW_FALSE);

    window = glfwCreateWindow(WIDTH, HEIGHT, "Vulkan", nullptr, nullptr);
}


      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Describamos el ciclo principal en el método mainLoop



para mantener la aplicación ejecutándose hasta que se cierre la ventana:

void mainLoop() {
    while (!glfwWindowShouldClose(window)) {
        glfwPollEvents();
    }
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Este código no debería plantear ninguna pregunta. Maneja eventos como presionar el botón X antes de que el usuario cierre la ventana. También desde este bucle llamaremos a una función para renderizar cuadros individuales.



Después de cerrar la ventana, necesitamos liberar recursos y salir de GLFW. Primero, agreguemos al cleanup



siguiente código:

void cleanup() {
    glfwDestroyWindow(window);

    glfwTerminate();
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Como resultado, después de iniciar el programa, verá una ventana con un nombre Vulkan



que se mostrará hasta que se cierre el programa. Ahora que tenemos un esqueleto para trabajar con Vulkan, ¡pasemos a crear nuestro primer objeto Vulkan!

Código C ++

Ejemplo

• Instanciación
• Comprobación de extensiones admitidas
• Limpieza

Instanciación

Lo primero que debe hacer es crear una instancia para inicializar la biblioteca. Una instancia es el vínculo entre su programa y la biblioteca Vulkan, y para crearla, deberá proporcionar al controlador cierta información sobre su programa.



Agregue un método createInstance



y llámelo desde una función initVulkan



.

void initVulkan() {
    createInstance();
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Agregue un miembro de instancia a nuestra clase para mantener un identificador de instancia:

private:
VkInstance instance;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Ahora necesitamos completar una estructura especial con información sobre el programa. Técnicamente, los datos son opcionales, sin embargo, esto permitirá al conductor obtener información útil para optimizar el trabajo con su programa. Esta estructura se llama VkApplicationInfo



:

void createInstance() {
    VkApplicationInfo appInfo{};
    appInfo.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
    appInfo.pApplicationName = "Hello Triangle";
    appInfo.applicationVersion = VK_MAKE_VERSION(1, 0, 0);
    appInfo.pEngineName = "No Engine";
    appInfo.engineVersion = VK_MAKE_VERSION(1, 0, 0);
    appInfo.apiVersion = VK_API_VERSION_1_0;
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Como se mencionó, muchas estructuras en Vulkan requieren una definición de tipo explícita en el miembro sType . Además, esta estructura, como muchas otras, contiene un elemento pNext



que le permite brindar información para extensiones. Usamos la inicialización de valor para llenar la estructura con ceros.



La mayor parte de la información en Vulkan se transmite a través de estructuras, por lo que debe completar una estructura más para proporcionar suficiente información para crear una instancia. Se requiere la siguiente estructura, le dice al controlador qué extensiones globales y capas de validación queremos usar. "Global" significa que las extensiones se aplican a todo el programa y no a un dispositivo específico.

VkInstanceCreateInfo createInfo{};
createInfo.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
createInfo.pApplicationInfo = &appInfo;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Los dos primeros parámetros no plantean dudas. Los dos miembros siguientes definen las extensiones globales necesarias. Como ya sabe, la API de Vulkan es completamente independiente de la plataforma. Esto significa que necesita una extensión para interactuar con el sistema de ventanas. GLFW tiene una práctica función incorporada que devuelve una lista de extensiones requeridas.

uint32_t glfwExtensionCount = 0;
const char** glfwExtensions;

glfwExtensions = glfwGetRequiredInstanceExtensions(&glfwExtensionCount);

createInfo.enabledExtensionCount = glfwExtensionCount;
createInfo.ppEnabledExtensionNames = glfwExtensions;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Los dos últimos miembros de la estructura definen qué capas de validación global incluir. Hablaremos de ellos con más detalle en el próximo capítulo, así que deje estos valores en blanco por ahora.

createInfo.enabledLayerCount = 0;
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Ahora ha hecho todo lo necesario para crear una instancia. Hacer una llamada vkCreateInstance



:

VkResult result = vkCreateInstance(&createInfo, nullptr, &instance);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Como regla general, los parámetros de las funciones para crear objetos están en este orden:

• Puntero a una estructura con la información requerida
• Puntero al asignador personalizado
• Puntero a la variable donde se escribirá el descriptor del nuevo objeto

Si todo se hace correctamente, el descriptor de instancia se almacenará en instancia . Casi todas las funciones de Vulkan devuelven un valor de VkResult , que puede ser un VK_SUCCESS



código de error o un código de error. No necesitamos almacenar el resultado para asegurarnos de que se haya creado la instancia. Usemos un cheque simple:

if (vkCreateInstance(&createInfo, nullptr, &instance) != VK_SUCCESS) {
    throw std::runtime_error("failed to create instance!");
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Ahora ejecute el programa para verificar que la instancia se creó correctamente.

Comprobación de extensiones admitidas

Si miramos la documentación de Vulkan , podemos encontrar que uno de los posibles códigos de error es VK_ERROR_EXTENSION_NOT_PRESENT



. Simplemente podemos especificar las extensiones requeridas y dejar de funcionar si no son compatibles. Esto tiene sentido para extensiones importantes como la interfaz del sistema de ventanas, pero ¿qué pasa si queremos probar las capacidades opcionales?



Para obtener una lista de extensiones admitidas antes de crear una instancia, use la función vkEnumerateInstanceExtensionProperties... El primer parámetro de la función es opcional, te permite filtrar extensiones por una capa de validación específica, así que lo dejaremos vacío por ahora. La función también requiere un puntero a una variable, donde se escribirá el número de extensiones y un puntero a un área de memoria donde se debe escribir información sobre ellas.



Para asignar memoria para almacenar información de extensión, primero necesita saber el número de extensiones. Deje el último parámetro en blanco para solicitar el número de extensiones:

uint32_t extensionCount = 0;
vkEnumerateInstanceExtensionProperties(nullptr, &extensionCount, nullptr);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Asigne una matriz para almacenar información de extensión (no se olvide include <vector>



):

std::vector<VkExtensionProperties> extensions(extensionCount);
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Ahora puede solicitar información sobre extensiones.

vkEnumerateInstanceExtensionProperties(nullptr, &extensionCount, extensions.data());
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Cada estructura de VkExtensionProperties contiene el nombre y la versión de la extensión. Se pueden enumerar con un bucle for simple ( \t



aquí está la pestaña de sangría):

std::cout << "available extensions:\n";

for (const auto& extension : extensions) {
    std::cout << '\t' << extension.extensionName << '\n';
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Puede agregar este código a una función createInstance



para obtener más información sobre el soporte de Vulkan. También puede intentar crear una función que verifique si todas las extensiones devueltas por la función glfwGetRequiredInstanceExtensions



están incluidas en la lista de extensiones compatibles.

Limpieza

VkInstance debe destruirse antes de cerrar el programa. Esto se puede hacercleanup



usando la función VkDestroyInstance :

void cleanup() {
    vkDestroyInstance(instance, nullptr);

    glfwDestroyWindow(window);

    glfwTerminate();
}
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
    

Los parámetros de la función vkDestroyInstance son autoexplicativos. Como se mencionó en el capítulo anterior, las funciones de asignación y desasignación en Vulkan aceptan punteros opcionales a asignadores personalizados que no usamos y pasamos nullptr



. Todos los demás recursos de Vulkan deben limpiarse antes de que se destruya la instancia.



Antes de pasar a pasos más complejos, debemos configurar las capas de validación para facilitar la depuración.



Código C ++