| // Copyright 2014-2021 The Khronos Group, Inc. |
| // |
| // SPDX-License-Identifier: CC-BY-4.0 |
| // This section is included inside the Pipelines chapter (pipelines.txt) |
| |
| [[pipelines-creation-feedback]] |
| == Pipeline Creation Feedback |
| |
| [open,refpage='VkPipelineCreationFeedbackCreateInfoEXT',desc='Request for feedback about the creation of a pipeline',type='structs',xrefs='VkGraphicsPipelineCreateInfo VkComputePipelineCreateInfo VkRayTracingPipelineCreateInfoNV VkRayTracingPipelineCreateInfoKHR VkPipelineCreationFeedbackEXT'] |
| -- |
| Feedback about the creation of a particular pipeline object can: be obtained |
| by adding a sname:VkPipelineCreationFeedbackCreateInfoEXT structure to the |
| pname:pNext chain of slink:VkGraphicsPipelineCreateInfo, |
| ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,] |
| ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,] |
| or slink:VkComputePipelineCreateInfo. |
| The sname:VkPipelineCreationFeedbackCreateInfoEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkPipelineCreationFeedbackCreateInfoEXT.txt[] |
| |
| * pname:sType is the type of this structure. |
| * pname:pNext is `NULL` or a pointer to a structure extending this |
| structure. |
| * pname:pPipelineCreationFeedback is a pointer to a |
| slink:VkPipelineCreationFeedbackEXT structure. |
| * pname:pipelineStageCreationFeedbackCount is the number of elements in |
| pname:pPipelineStageCreationFeedbacks. |
| * pname:pPipelineStageCreationFeedbacks is a pointer to an array of |
| pname:pipelineStageCreationFeedbackCount |
| slink:VkPipelineCreationFeedbackEXT structures. |
| |
| An implementation should: write pipeline creation feedback to |
| pname:pPipelineCreationFeedback and may: write pipeline stage creation |
| feedback to pname:pPipelineStageCreationFeedbacks. |
| An implementation must: set or clear the |
| ename:VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT in |
| slink:VkPipelineCreationFeedbackEXT::pname:flags for |
| pname:pPipelineCreationFeedback and every element of |
| pname:pPipelineStageCreationFeedbacks. |
| |
| [NOTE] |
| .Note |
| ==== |
| One common scenario for an implementation to skip per-stage feedback is when |
| ename:VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT |
| is set in pname:pPipelineCreationFeedback. |
| ==== |
| |
| When chained to |
| ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR,] |
| ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV,] |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[or] |
| slink:VkGraphicsPipelineCreateInfo, the `i` element of |
| pname:pPipelineStageCreationFeedbacks corresponds to the `i` element of |
| ifdef::VK_KHR_ray_tracing_pipeline[slink:VkRayTracingPipelineCreateInfoKHR::pname:pStages,] |
| ifdef::VK_NV_ray_tracing[slink:VkRayTracingPipelineCreateInfoNV::pname:pStages,] |
| ifdef::VK_NV_ray_tracing,VK_KHR_ray_tracing_pipeline[or] |
| slink:VkGraphicsPipelineCreateInfo::pname:pStages. |
| When chained to slink:VkComputePipelineCreateInfo, the first element of |
| pname:pPipelineStageCreationFeedbacks corresponds to |
| slink:VkComputePipelineCreateInfo::pname:stage. |
| |
| .Valid Usage |
| **** |
| * [[VUID-VkPipelineCreationFeedbackCreateInfoEXT-pipelineStageCreationFeedbackCount-02668]] |
| When chained to slink:VkGraphicsPipelineCreateInfo, |
| slink:VkPipelineCreationFeedbackEXT::pname:pipelineStageCreationFeedbackCount |
| must: equal slink:VkGraphicsPipelineCreateInfo::pname:stageCount |
| * [[VUID-VkPipelineCreationFeedbackCreateInfoEXT-pipelineStageCreationFeedbackCount-02669]] |
| When chained to slink:VkComputePipelineCreateInfo, |
| slink:VkPipelineCreationFeedbackEXT::pname:pipelineStageCreationFeedbackCount |
| must: equal 1 |
| ifdef::VK_KHR_ray_tracing_pipeline[] |
| * [[VUID-VkPipelineCreationFeedbackCreateInfoEXT-pipelineStageCreationFeedbackCount-02670]] |
| When chained to slink:VkRayTracingPipelineCreateInfoKHR, |
| slink:VkPipelineCreationFeedbackEXT::pname:pipelineStageCreationFeedbackCount |
| must: equal slink:VkRayTracingPipelineCreateInfoKHR::pname:stageCount |
| endif::VK_KHR_ray_tracing_pipeline[] |
| ifdef::VK_NV_ray_tracing[] |
| * [[VUID-VkPipelineCreationFeedbackCreateInfoEXT-pipelineStageCreationFeedbackCount-02969]] |
| When chained to slink:VkRayTracingPipelineCreateInfoNV, |
| slink:VkPipelineCreationFeedbackEXT::pname:pipelineStageCreationFeedbackCount |
| must: equal slink:VkRayTracingPipelineCreateInfoNV::pname:stageCount |
| endif::VK_NV_ray_tracing[] |
| **** |
| |
| include::{generated}/validity/structs/VkPipelineCreationFeedbackCreateInfoEXT.txt[] |
| -- |
| |
| [open,refpage='VkPipelineCreationFeedbackEXT',desc='Feedback about the creation of a pipeline or pipeline stage',type='structs',xrefs='VkPipelineCreationFeedbackCreateInfoEXT VkPipelineCreationFeedbackFlagBitsEXT'] |
| -- |
| The sname:VkPipelineCreationFeedbackEXT structure is defined as: |
| |
| include::{generated}/api/structs/VkPipelineCreationFeedbackEXT.txt[] |
| |
| * pname:flags is a bitmask of elink:VkPipelineCreationFeedbackFlagBitsEXT |
| providing feedback about the creation of a pipeline or of a pipeline |
| stage. |
| * pname:duration is the duration spent creating a pipeline or pipeline |
| stage in nanoseconds. |
| |
| If the ename:VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT is not set in |
| pname:flags, an implementation must: not set any other bits in pname:flags, |
| and the values of all other sname:VkPipelineCreationFeedbackEXT data members |
| are undefined:. |
| |
| include::{generated}/validity/structs/VkPipelineCreationFeedbackEXT.txt[] |
| -- |
| |
| [open,refpage='VkPipelineCreationFeedbackFlagBitsEXT',desc='Bitmask specifying pipeline or pipeline stage creation feedback',type='enums',xrefs='VkPipelineCreationFeedbackCreateInfoEXT VkPipelineCreationFeedbackEXT'] |
| -- |
| Possible values of the pname:flags member of |
| slink:VkPipelineCreationFeedbackEXT are: |
| |
| include::{generated}/api/enums/VkPipelineCreationFeedbackFlagBitsEXT.txt[] |
| |
| * ename:VK_PIPELINE_CREATION_FEEDBACK_VALID_BIT_EXT indicates that the |
| feedback information is valid. |
| * ename:VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT |
| indicates that a readily usable pipeline or pipeline stage was found in |
| the pname:pipelineCache specified by the application in the pipeline |
| creation command. |
| + |
| An implementation should: set the |
| ename:VK_PIPELINE_CREATION_FEEDBACK_APPLICATION_PIPELINE_CACHE_HIT_BIT_EXT |
| bit if it was able to avoid the large majority of pipeline or pipeline stage |
| creation work by using the pname:pipelineCache parameter of |
| flink:vkCreateGraphicsPipelines, |
| ifdef::VK_KHR_ray_tracing_pipeline[flink:vkCreateRayTracingPipelinesKHR,] |
| ifdef::VK_NV_ray_tracing[flink:vkCreateRayTracingPipelinesNV,] |
| or flink:vkCreateComputePipelines. |
| When an implementation sets this bit for the entire pipeline, it may: leave |
| it unset for any stage. |
| + |
| [NOTE] |
| .Note |
| ==== |
| Implementations are encouraged to provide a meaningful signal to |
| applications using this bit. |
| The intention is to communicate to the application that the pipeline or |
| pipeline stage was created "as fast as it gets" using the pipeline cache |
| provided by the application. |
| If an implementation uses an internal cache, it is discouraged from setting |
| this bit as the feedback would be unactionable. |
| ==== |
| |
| * ename:VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT_EXT |
| indicates that the base pipeline specified by the |
| pname:basePipelineHandle or pname:basePipelineIndex member of the |
| stext:Vk*PipelineCreateInfo structure was used to accelerate the |
| creation of the pipeline. |
| + |
| An implementation should: set the |
| ename:VK_PIPELINE_CREATION_FEEDBACK_BASE_PIPELINE_ACCELERATION_BIT_EXT bit |
| if it was able to avoid a significant amount of work by using the base |
| pipeline. |
| + |
| [NOTE] |
| .Note |
| ==== |
| While "significant amount of work" is subjective, implementations are |
| encouraged to provide a meaningful signal to applications using this bit. |
| For example, a 1% reduction in duration may not warrant setting this bit, |
| while a 50% reduction would. |
| ==== |
| -- |
| |
| [open,refpage='VkPipelineCreationFeedbackFlagsEXT',desc='Bitmask of VkPipelineCreationFeedbackFlagBitsEXT',type='flags',xrefs='VkPipelineCreationFeedbackEXT VkPipelineCreationFeedbackFlagBitsEXT'] |
| -- |
| include::{generated}/api/flags/VkPipelineCreationFeedbackFlagsEXT.txt[] |
| |
| tname:VkPipelineCreationFeedbackFlagsEXT is a bitmask type for providing |
| zero or more elink:VkPipelineCreationFeedbackFlagBitsEXT. |
| -- |