173 lines
7.4 KiB
Plaintext
173 lines
7.4 KiB
Plaintext
|
// Copyright (c) 2014-2019 Khronos Group. This work is licensed under a
|
||
|
|
// Creative Commons Attribution 4.0 International License; see
|
||
|
|
// http://creativecommons.org/licenses/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 VkPipelineCreationFeedbackEXT']
|
||
|
|
--
|
||
|
|
|
||
|
|
Feedback about the creation of a particular pipeline object can: be obtained
|
||
|
|
by including a sname:VkPipelineCreationFeedbackCreateInfoEXT structure in
|
||
|
|
the pNext chain of slink:VkGraphicsPipelineCreateInfo,
|
||
|
|
ifdef::VK_NV_ray_tracing[]
|
||
|
|
slink:VkRayTracingPipelineCreateInfoNV,
|
||
|
|
endif::VK_NV_ray_tracing[]
|
||
|
|
or slink:VkComputePipelineCreateInfo.
|
||
|
|
The sname:VkPipelineCreationFeedbackCreateInfoEXT structure is defined as:
|
||
|
|
|
||
|
|
include::../../api/structs/VkPipelineCreationFeedbackCreateInfoEXT.txt[]
|
||
|
|
|
||
|
|
* pname:sType is the type of this structure.
|
||
|
|
* pname:pNext is `NULL` or a pointer to an extension-specific structure.
|
||
|
|
* pname:pPipelineCreationFeedback is a pointer to a
|
||
|
|
slink:VkPipelineCreationFeedbackEXT structure.
|
||
|
|
* pname:pipelineStageCreationFeedbackCount is the number of elements in
|
||
|
|
pname:pPipelineStageCreationFeedbacks.
|
||
|
|
* pname:pPipelineStageCreationFeedbacks is an array of size
|
||
|
|
pname:pipelineStageCreationFeedbackCount of
|
||
|
|
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_NV_ray_tracing[]
|
||
|
|
slink:VkRayTracingPipelineCreateInfoNV or
|
||
|
|
endif::VK_NV_ray_tracing[]
|
||
|
|
slink:VkGraphicsPipelineCreateInfo, the `i` element of
|
||
|
|
pname:pPipelineStageCreationFeedbacks corresponds to the `i` element of
|
||
|
|
ifdef::VK_NV_ray_tracing[]
|
||
|
|
slink:VkRayTracingPipelineCreateInfoNV::pname:pStages or
|
||
|
|
endif::VK_NV_ray_tracing[]
|
||
|
|
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_NV_ray_tracing[]
|
||
|
|
* [[VUID-VkPipelineCreationFeedbackCreateInfoEXT-pipelineStageCreationFeedbackCount-02670]]
|
||
|
|
When chained to slink:VkRayTracingPipelineCreateInfoNV,
|
||
|
|
slink:VkPipelineCreationFeedbackEXT::pname:pipelineStageCreationFeedbackCount
|
||
|
|
must: equal slink:VkRayTracingPipelineCreateInfoNV::pname:stageCount
|
||
|
|
endif::VK_NV_ray_tracing[]
|
||
|
|
****
|
||
|
|
|
||
|
|
include::../../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::../../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 all other sname:VkPipelineCreationFeedbackEXT data members are
|
||
|
|
undefined.
|
||
|
|
|
||
|
|
include::../../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::../../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_NV_ray_tracing[]
|
||
|
|
flink:vkCreateRayTracingPipelinesNV,
|
||
|
|
endif::VK_NV_ray_tracing[]
|
||
|
|
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::../../api/flags/VkPipelineCreationFeedbackFlagsEXT.txt[]
|
||
|
|
|
||
|
|
tname:VkPipelineCreationFeedbackFlagsEXT is a bitmask type for providing
|
||
|
|
zero or more elink:VkPipelineCreationFeedbackFlagBitsEXT.
|
||
|
|
--
|