Vulkan.Extensions.VK_EXT_pipeline_creation_cache_control

Name

VK_EXT_pipeline_creation_cache_control - device extension

VK_EXT_pipeline_creation_cache_control

Name String

VK_EXT_pipeline_creation_cache_control

Extension Type

Device extension

Registered Extension Number

298

Revision

3

Extension and Version Dependencies

• Requires Vulkan 1.0

Contact

• Gregory Grebe @grgrebe_amd%0A<<Here describe the issue or question you have about the VK_EXT_pipeline_creation_cache_control extension> >

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 Vk*PipelineCreateInfo and PipelineCacheCreateInfo 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 pAllocator passed to 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 PipelineCreateFlags, 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 PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT on Vk*PipelineCreateInfo::flags. When set, an ICD must not attempt pipeline or shader compilation to create the pipeline object. The ICD will return the result PIPELINE_COMPILE_REQUIRED_EXT. An ICD may still return a valid Pipeline object by either re-using existing pre-compiled objects such as those from a pipeline cache, or derivative pipelines.

By default vkCreate*Pipelines calls must attempt to create all pipelines before returning. Setting PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT on Vk*PipelineCreateInfo::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 vkCreate*Pipelines is internal synchronization of the PipelineCache object. PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT can be set when calling createPipelineCache to state the cache is 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.

New Structures

• Extending PhysicalDeviceFeatures2, DeviceCreateInfo:

  • PhysicalDevicePipelineCreationCacheControlFeaturesEXT

New Enums

• PipelineCacheCreateFlagBits

New Enum Constants

• EXT_PIPELINE_CREATION_CACHE_CONTROL_EXTENSION_NAME

• EXT_PIPELINE_CREATION_CACHE_CONTROL_SPEC_VERSION

• Extending PipelineCacheCreateFlagBits:

  • PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT

• Extending PipelineCreateFlagBits:

  • PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT
  • PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT

• Extending Result:

  • ERROR_PIPELINE_COMPILE_REQUIRED_EXT
  • PIPELINE_COMPILE_REQUIRED_EXT

• Extending StructureType:

  • STRUCTURE_TYPE_PHYSICAL_DEVICE_PIPELINE_CREATION_CACHE_CONTROL_FEATURES_EXT

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 PIPELINE_COMPILE_REQUIRED_EXT to a success code, adding an alias for the original ERROR_PIPELINE_COMPILE_REQUIRED_EXT. Also updated the xml to include these codes as return values.

See Also

PhysicalDevicePipelineCreationCacheControlFeaturesEXT, PipelineCacheCreateFlagBits

Document Notes

For more information, see the Vulkan Specification

This page is a generated document. Fixes and changes should be made to the generator scripts, not directly.

Documentation

pattern ERROR_PIPELINE_COMPILE_REQUIRED_EXT :: Result

data PhysicalDevicePipelineCreationCacheControlFeaturesEXT

VkPhysicalDevicePipelineCreationCacheControlFeaturesEXT - Structure describing whether pipeline cache control can be supported by an implementation

Members

This structure describes the following feature:

Description

If the PhysicalDevicePipelineCreationCacheControlFeaturesEXT structure is included in the pNext chain of the PhysicalDeviceFeatures2 structure passed to getPhysicalDeviceFeatures2, it is filled in to indicate whether each corresponding feature is supported. PhysicalDevicePipelineCreationCacheControlFeaturesEXT can also be used in the pNext chain of DeviceCreateInfo to selectively enable these features.

Valid Usage (Implicit)

See Also

VK_EXT_pipeline_creation_cache_control, Bool32, StructureType

Constructors

PhysicalDevicePipelineCreationCacheControlFeaturesEXT

Fields

• pipelineCreationCacheControl :: Bool

  pipelineCreationCacheControl indicates that the implementation supports:

  • The following can be used in Vk*PipelineCreateInfo::flags:

    • PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT_EXT
    • PIPELINE_CREATE_EARLY_RETURN_ON_FAILURE_BIT_EXT

  • The following can be used in PipelineCacheCreateInfo::flags:

    • PIPELINE_CACHE_CREATE_EXTERNALLY_SYNCHRONIZED_BIT_EXT

Instances

Eq PhysicalDevicePipelineCreationCacheControlFeaturesEXT

Defined in Vulkan.Extensions.VK_EXT_pipeline_creation_cache_control

Methods

(==) :: PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> Bool

(/=) :: PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> Bool

Show PhysicalDevicePipelineCreationCacheControlFeaturesEXT

Defined in Vulkan.Extensions.VK_EXT_pipeline_creation_cache_control

Methods

showsPrec :: Int -> PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> ShowS

show :: PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> String

showList :: [PhysicalDevicePipelineCreationCacheControlFeaturesEXT] -> ShowS

Storable PhysicalDevicePipelineCreationCacheControlFeaturesEXT

Defined in Vulkan.Extensions.VK_EXT_pipeline_creation_cache_control

Methods

sizeOf :: PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> Int

alignment :: PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> Int

peekElemOff :: Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> Int -> IO PhysicalDevicePipelineCreationCacheControlFeaturesEXT

pokeElemOff :: Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> Int -> PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO ()

peekByteOff :: Ptr b -> Int -> IO PhysicalDevicePipelineCreationCacheControlFeaturesEXT

pokeByteOff :: Ptr b -> Int -> PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO ()

peek :: Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO PhysicalDevicePipelineCreationCacheControlFeaturesEXT

poke :: Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO ()

FromCStruct PhysicalDevicePipelineCreationCacheControlFeaturesEXT

Defined in Vulkan.Extensions.VK_EXT_pipeline_creation_cache_control

Methods

peekCStruct :: Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO PhysicalDevicePipelineCreationCacheControlFeaturesEXT

ToCStruct PhysicalDevicePipelineCreationCacheControlFeaturesEXT

Defined in Vulkan.Extensions.VK_EXT_pipeline_creation_cache_control

Methods

withCStruct :: PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> (Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO b) -> IO b

pokeCStruct :: Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO b -> IO b

withZeroCStruct :: (Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO b) -> IO b

pokeZeroCStruct :: Ptr PhysicalDevicePipelineCreationCacheControlFeaturesEXT -> IO b -> IO b

cStructSize :: Int

cStructAlignment :: Int

Zero PhysicalDevicePipelineCreationCacheControlFeaturesEXT

Defined in Vulkan.Extensions.VK_EXT_pipeline_creation_cache_control

Methods

zero :: PhysicalDevicePipelineCreationCacheControlFeaturesEXT

type EXT_PIPELINE_CREATION_CACHE_CONTROL_SPEC_VERSION = 3

pattern EXT_PIPELINE_CREATION_CACHE_CONTROL_SPEC_VERSION :: forall a. Integral a => a

type EXT_PIPELINE_CREATION_CACHE_CONTROL_EXTENSION_NAME = "VK_EXT_pipeline_creation_cache_control"

pattern EXT_PIPELINE_CREATION_CACHE_CONTROL_EXTENSION_NAME :: forall a. (Eq a, IsString a) => a