// 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.