Configuración de Vulkan

En este documento, te explicamos la manera de dar los primeros pasos con la biblioteca de gráficos de Vulkan mediante la descarga, compilación y ejecución de varias apps de ejemplo.

Antes de comenzar, asegúrate de tener el hardware adecuado y la versión correcta de la plataforma preparados. Debes usar un dispositivo compatible con Vulkan que ejecute Android API nivel 24 o superior.

Para confirmar la versión de Android, ve al menú Configuración y selecciona Acerca del dispositivo > Versión de Android. Una vez que confirmas que tienes configurados el hardware y la versión de la plataforma correctos, puedes descargar el software necesario.

Cómo descargar

Antes de comenzar, debes descargar varias herramientas y otros elementos de software. Ten en cuenta que, en un host de Windows, se recomienda evitar una jerarquía de ruta de acceso de archivo profunda para las herramientas y el código fuente; esto es para evitar límites de ruta de acceso de archivo en algunas versiones del SO Windows.

  1. Si aún no tienes Android Studio, descárgalo. Esto incluye el SDK de Android más reciente.
  2. Instala el NDK desde Android Studio o descárgalo manualmente.
  3. Para compilar Shaderc, navega hasta <ndk-root>/sources/third_party/shaderc/ y ejecuta el siguiente comando:
  4. En Mac o Linux:

        ../../../ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk \
          APP_STL:=c++_static APP_ABI=all NDK_TOOLCHAIN_VERSION:=clang libshaderc_combined \
          -j16
        

    En Windows:

        ..\..\..\ndk-build NDK_PROJECT_PATH=. APP_BUILD_SCRIPT=Android.mk ^
         APP_ABI=all APP_PLATFORM=android-24 APP_STL=c++_static ^
         -j8 clean libshaderc_combined
        

    Consulta el artículo Compiladores de sombreadores para obtener documentación adicional sobre Shaderc.

Cómo importar

En esta sección, descargarás el repositorio LunarG Vulkan ©, generarás proyectos de Android Studio para las muestras de API y, luego, importarás estos proyectos al IDE:

  1. Abre una terminal y descarga el código fuente en tu directorio de desarrollo:

        cd dev-directory
        git clone --recursive https://github.com/LunarG/VulkanSamples.git
        
  2. Sigue estas instrucciones (desde Cómo compilar en Android) a fin de generar los proyectos de muestra para Android:

        cd VulkanSamples/API-Samples
        cmake -DANDROID=ON -DABI_NAME=abi
        cd android
        python3 compile_shaders.py
        

    Las ABI admitidas incluyen lo siguiente:

    • armeabi-v7a
    • arm64-v8a
    • x86
    • x86_64
  3. Configura variables de entorno para especificar la ruta de acceso al NDK y al SDK de Android:

        export ANDROID_SDK_ROOT=/path/to/sdk-directory
        export ANDROID_NDK_ROOT=/path/to/ndk-directory
        

    La versión actual de targetSdk para las muestras es 26, por lo que es posible que debas actualizar tus herramientas con SDK Manager.

  4. Abre Android Studio. Selecciona File > Open y, luego, VulkanSamples/API-Samples/android/build.gradle.

El panel Project se parece a la ventana que se muestra en la figura 1.

Panel Project después de la importación de ejemplos a Android Studio

Figura 1: Panel Project donde se muestran los ejemplos una vez importados

Cómo compilar

Puedes compilar tu proyecto en Android Studio o desde la línea de comandos.

Android Studio

  1. Selecciona File > Project Structure. Selecciona SDK Location y asegúrate de que las ubicaciones del SDK y el NDK estén establecidas.
  2. Selecciona tu proyecto en el panel Project de Android Studio.
  3. Desde el menú Build, selecciona Make Module <module-name> o elige Build APK para generar el APK.
  4. Resuelve los problemas de dependencia y luego realiza la compilación. Como se muestra en la figura 2, puedes seleccionar proyectos individuales para la compilación seleccionándolos de la lista desplegable de configuración.
  5. Cómo seleccionar el proyecto del cubo 3D desde el menú desplegable de configuración

    Figura 2: Selecciona un proyecto individual para compilarlo.

Línea de comandos

Usa los siguientes comandos para compilar los proyectos desde la línea de comandos (asegúrate de que aún estés en el directorio VulkanSamples/API-Samples/android):

    ./gradlew build
    

Cómo ejecutar

Para ejecutar tu proyecto, elige el APK que ejecutarás en Run > Run <project-name>.

Para depurar un APK, selecciona Run > Debug <project-name>. Por ejemplo, para drawcube, ejecuta 15-draw_cube.

La mayoría de los ejemplos tienen funcionalidad simple para demostrar cómo usar una API y se detienen automáticamente después de la ejecución. El ejemplo del cubo 3D es uno de los más interesantes en términos visuales. Cuando lo ejecutes, deberá mostrar la imagen que aparece en la figura 3.

. Si la ejecución es exitosa, se mostrará un cubo multicolor.

Figura 3: El programa compilado exitosamente se ejecuta y genera una representación

Cómo usar el cargador dinámico

En los ejemplos, se usa una función de ayuda llamada cargador dinámico que se define en vulkan_wrapper.h/cpp para recuperar punteros de la API de Vulkan mediante dlopen() y dlsym(). Lo hace en lugar de realizar una vinculación estática con vulkan.so.

El uso de este cargador permite la vinculación del código con API nivel 23 y versiones anteriores de la plataforma. Esas versiones anteriores no incluyen la biblioteca compartida vulkan.so, pero pueden ejecutarse en dispositivos compatibles con la API de Vulkan.

En el siguiente fragmento, se muestra la manera de usar el cargador dinámico.

    #include "vulkan_wrapper.h" // Include Vulkan_wrapper and dynamically load symbols.
    ...
    // Before any Vulkan API usage,
    InitVulkan();
    

Recursos adicionales

  • Especificación de Vulkan

    Khronos Group mantiene la especificación de Vulkan. Consulta la página principal de Vulkan para obtener la especificación completa, la capacitación y los instructivos.

  • Shaderc

    El código de Shaderc en NDK se encuentra en un nivel inferior al del repositorio de Shaderc. Si necesitas la versión más reciente de Shaderc, consulta Compiladores de sombreadores.