Cómo agregar funciones de ritmo de fotogramas

Emplea las siguientes funciones para usar Android Frame Pacing con un motor de procesamiento basado en la API de Vulkan.

Cómo identificar las extensiones necesarias para la creación

A fin de recopilar el conjunto de extensiones necesarias para crear una instancia de Android Frame Pacing cuando se usa Vulkan, completa los pasos que se muestran en el siguiente fragmento de código:

VkPhysicalDevice physicalDevice;
uint32_t availableExtensionCount;
VkExtensionProperties* pAvailableExtensions;
uint32_t requiredExtensionCount;
char** pRequiredExtensions;

// Determine the number of extensions available for this device.
vkEnumerateDeviceExtensionProperties(physicalDevice, layerName, &availableExtensionCount,
    pAvailableExtensions);

// Determine the number of required extensions.
SwappyVk_determineDeviceExtensions(physicalDevice, availableExtensionCount,
    pAvailableExtensions, &requiredExtensionCount, nullptr);

// Determine the required extensions.
pRequiredExtensions = (char**)malloc(requiredExtensionCount * sizeof(char*));
pRequiredExtensionsData = (char*)malloc(requiredExtensionCount * (VK_MAX_EXTENSION_NAME_SIZE + 1));
for (uint32_t i = 0; i < requiredExtensionCount; i++) {
    pRequiredExtensions[i] = &pRequiredExtensionsData[i * (VK_MAX_EXTENSION_NAME_SIZE + 1)];
}
SwappyVk_determineDeviceExtensions(physicalDevice, availableExtensionCount,
    pAvailableExtensions, &requiredExtensionCount, pRequiredExtensions);

Luego, puedes iniciar el Android Frame Pacing llamando a vkCreateDevice(). En el segundo argumento, una estructura de tipo VkDeviceCreateInfo*, debe tener su miembro enabledExtensionCount establecido en la cantidad de extensiones requeridas.

Cómo identificar la familia de filas

Para presentar la fila de visualización correcta, Android Frame Pacing debe conocer la familia de filas que Vulkan usa. Para determinar la familia correcta, completa los pasos que se muestran en el siguiente fragmento de código:

// Reusing local variables from previous snippets:
// VkPhysicalDevice physicalDevice;

const VkDeviceCreateInfo createInfo;
const VkAllocationCallbacks allocator;
VkDevice device;
uint32_t queueFamilyIndex;
uint32_t queueIndex;
VkQueue deviceQueue;

// Values of "device" and "deviceQueue" set in the 1st and 2nd function
// calls, respectively.
vkCreateDevice(physicalDevice, &createInfo, &allocator, &device);
vkGetDeviceQueue(device, queueFamilyIndex, queueIndex, &deviceQueue);
SwappyVk_setQueueFamilyIndex(device, deviceQueue, queueFamilyIndex);

Cómo definir la velocidad de fotogramas para las cadenas de intercambio

Para inicializar Android Frame Pacing para un dispositivo físico y una cadena de intercambio determinados, completa los pasos que se muestran en el siguiente fragmento de código:

// Reusing local variables from previous snippets:
// VkPhysicalDevice physicalDevice;
// VkDevice device;

// Assume that the JNI environment is available in:
// JNIEnv *env;
// jobject jactivity;

// Assume that swapchain is already known.
VkSwapchainKHR swapchain;
uint64_t refreshDuration; // in nanoseconds

// Determine duration between vertical-blanking periods.
// Example: 60 FPS sets "refreshDuration" to 16,666,666.
SwappyVk_initAndGetRefreshCycleDuration(env, jactivity, physicalDevice,
        device, swapchain, &refreshDuration);

Esto determina la duración del intercambio en nanosegundos. Hay macros de ayuda definidas en swappy_common.h para las duraciones de intercambio comunes (por ejemplo, SWAPPY_SWAP_60FPS).

Luego, debes proporcionar la duración del intercambio en nanosegundos.

// Declare the periods in nanoseconds that should elapse before refreshing one
// image with the next image. There are helper macros defined in swappy_common.h
// for common swap durations.
// This example shows what to do when you want to render your game at 30 FPS.

SwappyVk_setSwapIntervalNS(device, swapchain, SWAPPY_SWAP_30FPS);

Cómo configurar ANativeWindow

Swappy necesita el controlador de ANativeWindow a fin de realizar una operación específica de ANativeWindow, como llamar a ANativeWindow_setFrameRate(). Llama a SwappyVk_setWindow() cuando cambie la plataforma de visualización de Android y tengas un nuevo controlador ANativeWindow (consulta la muestra de Cube para ver un ejemplo).

Modos automáticos

Android Frame Pacing ajusta la duración del intercambio y el modo de canalización en función de la duración promedio de los fotogramas anteriores. Puedes controlar este comportamiento mediante las siguientes funciones:

• void SwappyVk_setAutoSwapInterval(bool enabled);
• void SwappyVk_setMaxAutoSwapIntervalNS(uint64_t max_swap_ns);
• void SwappyVk_setAutoPipelineMode(bool enabled);

Cómo presentar un fotograma

A fin de presentar un fotograma de tu juego a Android Frame Pacing, llama a SwappyVk_queuePresent(). Esta función llama a vkQueuePresentKHR() en nombre de tu juego.

Nota: Para lograr un ritmo de fotogramas adecuado, la API de Android Frame Pacing puede insertar comandos de Vulkan en la cola de presentación.

Cómo destruir la cadena de intercambio

Para destruir los datos de SwappyVk asociados con una cadena de intercambio determinada, completa los pasos que se muestran en el siguiente fragmento de código:

// Reusing local variables from previous snippets:
// VkDevice device;
// VkSwapchainKHR swapchain;
// const VkAllocationCallbacks allocator;

SwappyVk_destroySwapchain(device, swapchain);
vkDestroySwapchainKHR(device, swapchain, &allocator);