| // Copyright 2019-2021 The Khronos Group Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| |
| include::{generated}/meta/{refprefix}VK_EXT_pipeline_creation_cache_control.txt[] |
| |
| === Other Extension Metadata |
| |
| *Last Modified Date*:: |
| 2020-03-23 |
| *IP Status*:: |
| No known IP claims. |
| *Contributors*:: |
| - Gregory Grebe, AMD |
| - Tobias Hector, AMD |
| - Matthaeus Chajdas, AMD |
| - Mitch Singer, AMD |
| - Spencer Fricke, Samsung Electronics |
| - Stuart Smith, Imagination Technologies |
| - Jeff Bolz, NVIDIA Corporation |
| - Daniel Koch, NVIDIA Corporation |
| - Dan Ginsburg, Valve Corporation |
| - Jeff Leger, QUALCOMM |
| - Michal Pietrasiuk, Intel |
| - Jan-Harald Fredriksen, Arm Limited |
| |
| === Description |
| |
| This extension adds flags to stext:Vk*PipelineCreateInfo and |
| slink:VkPipelineCacheCreateInfo structures with the aim of improving the |
| predictability of pipeline creation cost. |
| The goal is to provide information about potentially expensive hazards |
| within the client driver during pipeline creation to the application before |
| carrying them out rather than after. |
| |
| === Background |
| |
| Pipeline creation is a costly operation, and the explicit nature of the |
| Vulkan design means that cost is not hidden from the developer. |
| Applications are also expected to schedule, prioritize, and load balance all |
| calls for pipeline creation. |
| It is strongly advised that applications create pipelines sufficiently ahead |
| of their usage. |
| Failure to do so will result in an unresponsive application, intermittent |
| stuttering, or other poor user experiences. |
| Proper usage of pipeline caches and/or derivative pipelines help mitigate |
| this but is not assured to eliminate disruption in all cases. |
| In the event that an ahead-of-time creation is not possible, considerations |
| should be taken to ensure that the current execution context is suitable for |
| the workload of pipeline creation including possible shader compilation. |
| |
| Applications making API calls to create a pipeline must be prepared for any |
| of the following to occur: |
| |
| * OS/kernel calls to be made by the ICD |
| * Internal memory allocation not tracked by the pname:pAllocator passed to |
| ftext:vkCreate*Pipelines |
| * Internal thread synchronization or yielding of the current thread's core |
| * Extremely long (multi-millisecond+), blocking, compilation times |
| * Arbitrary call stacks depths and stack memory usage |
| |
| The job or task based game engines that are being developed to take |
| advantage of explicit graphics APIs like Vulkan may behave exceptionally |
| poorly if any of the above scenarios occur. |
| However, most game engines are already built to "`stream`" in assets |
| dynamically as the user plays the game. |
| By adding control by way of tlink:VkPipelineCreateFlags, we can require an |
| ICD to report back a failure in critical execution paths rather than forcing |
| an unexpected wait. |
| |
| Applications can prevent unexpected compilation by setting |
| ename:VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT on |
| stext:Vk*PipelineCreateInfo::pname:flags. |
| When set, an ICD must not attempt pipeline or shader compilation to create |
| the pipeline object. |
| The ICD will return the result ename:VK_PIPELINE_COMPILE_REQUIRED_EXT. |
| An ICD may still return a valid sname:VkPipeline object by either re-using |
| existing pre-compiled objects such as those from a pipeline cache, or |
| derivative pipelines. |
| |
| By default ftext:vkCreate*Pipelines calls must attempt to create all |
| pipelines before returning. |
| Setting ename:VK_PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT on |
| stext:Vk*PipelineCreateInfo::pname:flags can be used as an escape hatch for |
| batched pipeline creates. |
| |
| Hidden locks also add to the unpredictability of the cost of pipeline |
| creation. |
| The most common case of locks inside the stext:vkCreate*Pipelines is |
| internal synchronization of the slink:VkPipelineCache object. |
| ename:VK_PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT can be set |
| when calling flink:vkCreatePipelineCache to state the cache is |
| <<fundamentals-threadingbehavior,externally synchronized>>. |
| |
| The hope is that armed with this information application and engine |
| developers can leverage existing asset streaming systems to recover from |
| "just-in-time" pipeline creation stalls. |
| |
| include::{generated}/interfaces/VK_EXT_pipeline_creation_cache_control.txt[] |
| |
| === Version History |
| |
| * Revision 1, 2019-11-01 (Gregory Grebe) |
| - Initial revision |
| * Revision 2, 2020-02-24 (Gregory Grebe) |
| - Initial public revision |
| * Revision 3, 2020-03-23 (Tobias Hector) |
| - Changed ename:VK_PIPELINE_COMPILE_REQUIRED_EXT to a success code, |
| adding an alias for the original |
| ename:VK_ERROR_PIPELINE_COMPILE_REQUIRED_EXT. |
| Also updated the xml to include these codes as return values. |
