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