1 /* 2 * Copyright 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef SWAPPYVK_H 18 #define SWAPPYVK_H 19 20 #if (defined ANDROID) && (defined SWAPPYVK_USE_WRAPPER) 21 #include <vulkan_wrapper.h> 22 #else 23 #include <vulkan/vulkan.h> 24 #endif 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** 31 * Determine any Vulkan device extensions that must be enabled for a new 32 * VkDevice. 33 * 34 * Swappy-for-Vulkan (SwappyVk) benefits from certain Vulkan device extensions 35 * (e.g. VK_GOOGLE_display_timing). Before the application calls 36 * vkCreateDevice, SwappyVk needs to look at the list of available extensions 37 * (returned by vkEnumerateDeviceExtensionProperties) and potentially identify 38 * one or more extensions that the application must add to: 39 * 40 * - VkDeviceCreateInfo::enabledExtensionCount 41 * - VkDeviceCreateInfo::ppEnabledExtensionNames 42 * 43 * before the application calls vkCreateDevice. For each VkPhysicalDevice that 44 * the application will call vkCreateDevice for, the application must call this 45 * function, and then must add the identified extension(s) to the list that are 46 * enabled for the VkDevice. Similar to many Vulkan functions, this function 47 * can be called twice, once to identify the number of required extensions, and 48 * again with application-allocated memory that the function can write into. 49 * 50 * Parameters: 51 * 52 * (IN) physicalDevice - The VkPhysicalDevice associated with the 53 * available extensions. 54 * (IN) availableExtensionCount - This is the returned value of 55 * pPropertyCount from vkEnumerateDeviceExtensionProperties. 56 * (IN) pAvailableExtensions - This is the returned value of 57 * pProperties from vkEnumerateDeviceExtensionProperties. 58 * (INOUT) pRequiredExtensionCount - If pRequiredExtensions is nullptr, the 59 * function sets this to the number of extensions that are 60 * required. If pRequiredExtensions is non-nullptr, this 61 * is the number of required extensions that the function 62 * should write into pRequiredExtensions. 63 * (INOUT) pRequiredExtensions - If non-nullptr, this is application-allocated 64 * memory into which the function will write the names of 65 * required extensions. It is a pointer to an array of 66 * char* strings (i.e. the same as 67 * VkDeviceCreateInfo::ppEnabledExtensionNames). 68 */ 69 void SwappyVk_determineDeviceExtensions( 70 VkPhysicalDevice physicalDevice, 71 uint32_t availableExtensionCount, 72 VkExtensionProperties* pAvailableExtensions, 73 uint32_t* pRequiredExtensionCount, 74 char** pRequiredExtensions); 75 76 /** 77 * Tell Swappy The queueFamilyIndex used to create a specific VkQueue 78 * 79 * Swappy needs to know the queueFamilyIndex used for creating a specific VkQueue 80 * so it can use it when presenting. 81 * 82 * Parameters: 83 * 84 * (IN) device - The VkDevice associated with the queue 85 * (IN) queue - A device queue. 86 * (IN) queueFamilyIndex - The queue family index used to create the VkQueue. 87 * 88 */ 89 void SwappyVk_setQueueFamilyIndex( 90 VkDevice device, 91 VkQueue queue, 92 uint32_t queueFamilyIndex); 93 94 95 // TBD: For now, SwappyVk assumes only one VkSwapchainKHR per VkDevice, and that 96 // applications don't re-create swapchains. Is this long-term sufficient? 97 98 /** 99 * Initialize SwappyVk for a given device and swapchain, and obtain the 100 * approximate time duration between vertical-blanking periods. 101 * 102 * If your application presents to more than one swapchain at a time, you must 103 * call this for each swapchain before calling swappyVkSetSwapInterval() for it. 104 * 105 * The duration between vertical-blanking periods (an interval) is expressed as 106 * the approximate number of nanoseconds between vertical-blanking periods of 107 * the swapchain’s physical display. 108 * 109 * If the application converts this number to a fraction (e.g. 16,666,666 nsec 110 * to 0.016666666) and divides one by that fraction, it will be the approximate 111 * refresh rate of the display (e.g. 16,666,666 nanoseconds corresponds to a 112 * 60Hz display, 11,111,111 nsec corresponds to a 90Hz display). 113 * 114 * Parameters: 115 * 116 * (IN) physicalDevice - The VkPhysicalDevice associated with the swapchain 117 * (IN) device - The VkDevice associated with the swapchain 118 * (IN) swapchain - The VkSwapchainKHR the application wants Swappy to swap 119 * (OUT) pRefreshDuration - The returned refresh cycle duration 120 * 121 * Return value: 122 * 123 * bool - true if the value returned by pRefreshDuration is valid, 124 * otherwise false if an error. 125 */ 126 bool SwappyVk_initAndGetRefreshCycleDuration( 127 VkPhysicalDevice physicalDevice, 128 VkDevice device, 129 VkSwapchainKHR swapchain, 130 uint64_t* pRefreshDuration); 131 132 133 /** 134 * Tell Swappy the number of vertical-blanking intervals that each presented 135 * image should be visible for. 136 * 137 * For example, if the refresh duration is approximately 16,666,666 nses (60Hz 138 * display), and if the application wants to present at 30 frames-per-second 139 * (FPS), the application would set the swap interval to 2. For 30FPS on a 90Hz 140 * display, set the swap interval to 3. 141 * 142 * If your application presents to more than one swapchain at a time, you must 143 * call this for each swapchain before presenting to it. 144 * 145 * Parameters: 146 * 147 * (IN) device - The VkDevice associated with the swapchain 148 * (IN) swapchain - The VkSwapchainKHR the application wants Swappy to swap 149 * (IN) interval - The number of vertical-blanking intervals each image 150 * should be visible 151 */ 152 void SwappyVk_setSwapInterval( 153 VkDevice device, 154 VkSwapchainKHR swapchain, 155 uint32_t interval); 156 157 /** 158 * Tell Swappy to present one or more images to corresponding swapchains. 159 * 160 * Swappy will call vkQueuePresentKHR for your application. Swappy may insert a 161 * struct to the pNext-chain of VkPresentInfoKHR, or it may insert other Vulkan 162 * commands in order to attempt to honor the desired swap interval. 163 * 164 * Note: If your application presents to more than one swapchain at a time, and 165 * if you use a different swap interval for each swapchain, Swappy will attempt 166 * to honor the swap interval for each swapchain (being more successful on 167 * devices that support an underlying presentation-timing extension, such as 168 * VK_GOOGLE_display_timing). 169 * 170 * Parameters: 171 * 172 * (IN) queue - The VkQueue associated with the device and swapchain 173 * (IN) pPresentInfo - A pointer to the VkPresentInfoKHR containing the 174 * information about what image(s) to present on which 175 * swapchain(s). 176 */ 177 VkResult SwappyVk_queuePresent( 178 VkQueue queue, 179 const VkPresentInfoKHR* pPresentInfo); 180 181 182 /** 183 * Destroy SwappyVk instance associated to the swapchain 184 * 185 * This API is expected to be called before calling to vkDestroySwapchainKHR() 186 * so Swappy could cleanup its internal state. 187 * 188 * Parameters: 189 * 190 * (IN) device - The VkDevice associated with SwappyVk 191 */ 192 void SwappyVk_destroySwapchain( 193 VkDevice device, 194 VkSwapchainKHR swapchain); 195 196 #ifdef __cplusplus 197 } // extern "C" 198 #endif 199 200 #endif //SWAPPYVK_H 201