// This section is included inside the Pipelines chapter (pipelines.txt) [[pipelines-raytracing]] == Ray Tracing Pipeline Ray tracing pipelines consist of multiple shader stages, fixed-function traversal stages, and a pipeline layout. [open,refpage='vkCreateRayTracingPipelinesNV',desc='Creates a new ray tracing pipeline object',type='protos'] -- To create ray tracing pipelines, call: include::../../api/protos/vkCreateRayTracingPipelinesNV.txt[] * pname:device is the logical device that creates the ray tracing pipelines. * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that pipeline caching is disabled, or the handle of a valid <> object, in which case use of that cache is enabled for the duration of the command. * pname:createInfoCount is the length of the pname:pCreateInfos and pname:pPipelines arrays. * pname:pCreateInfos is an array of sname:VkRayTracingPipelineCreateInfoNV structures. * pname:pAllocator controls host memory allocation as described in the <> chapter. * pname:pPipelines is a pointer to an array in which the resulting ray tracing pipeline objects are returned. .Valid Usage **** * [[VUID-vkCreateRayTracingPipelinesNV-flags-02402]] If the pname:flags member of any element of pname:pCreateInfos contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and the pname:basePipelineIndex member of that same element is not `-1`, pname:basePipelineIndex must: be less than the index into pname:pCreateInfos that corresponds to that element * [[VUID-vkCreateRayTracingPipelinesNV-flags-02403]] If the pname:flags member of any element of pname:pCreateInfos contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, the base pipeline must: have been created with the ename:VK_PIPELINE_CREATE_ALLOW_DERIVATIVES_BIT flag set **** include::../../validity/protos/vkCreateRayTracingPipelinesNV.txt[] -- [open,refpage='VkRayTracingPipelineCreateInfoNV',desc='Structure specifying parameters of a newly created ray tracing pipeline',type='structs'] -- The sname:VkRayTracingPipelineCreateInfoNV structure is defined as: include::../../api/structs/VkRayTracingPipelineCreateInfoNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:flags is a bitmask of elink:VkPipelineCreateFlagBits specifying how the pipeline will be generated. * pname:stageCount is the number of entries in the pname:pStages array. * pname:pStages is an array of size pname:stageCount structures of type slink:VkPipelineShaderStageCreateInfo describing the set of the shader stages to be included in the ray tracing pipeline. * pname:groupCount is the number of entries in the pname:pGroups array. * pname:pGroups is an array of size pname:groupCount structures of type slink:VkRayTracingShaderGroupCreateInfoNV describing the set of the shader stages to be included in each shader group in the ray tracing pipeline. * pname:maxRecursionDepth is the maximum recursion that will be called from this pipeline. * pname:layout is the description of binding locations used by both the pipeline and descriptor sets used with the pipeline. * pname:basePipelineHandle is a pipeline to derive from. * pname:basePipelineIndex is an index into the pname:pCreateInfos parameter to use as a pipeline to derive from. The parameters pname:basePipelineHandle and pname:basePipelineIndex are described in more detail in <>. .Valid Usage **** * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02404]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and pname:basePipelineIndex is `-1`, pname:basePipelineHandle must: be a valid handle to a ray tracing sname:VkPipeline * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02405]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and pname:basePipelineHandle is dlink:VK_NULL_HANDLE, pname:basePipelineIndex must: be a valid index into the calling command's pname:pCreateInfos parameter * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02406]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and pname:basePipelineIndex is not `-1`, pname:basePipelineHandle must: be dlink:VK_NULL_HANDLE * [[VUID-VkRayTracingPipelineCreateInfoNV-flags-02407]] If pname:flags contains the ename:VK_PIPELINE_CREATE_DERIVATIVE_BIT flag, and pname:basePipelineHandle is not dlink:VK_NULL_HANDLE, pname:basePipelineIndex must: be `-1` * [[VUID-VkRayTracingPipelineCreateInfoNV-stage-02408]] The pname:stage member of one element of pname:pStages must: be ename:VK_SHADER_STAGE_RAYGEN_BIT_NV * [[VUID-VkRayTracingPipelineCreateInfoNV-pStages-02409]] The shader code for the entry points identified by pname:pStages, and the rest of the state identified by this structure must: adhere to the pipeline linking rules described in the <> chapter * [[VUID-VkRayTracingPipelineCreateInfoNV-layout-02410]] pname:layout must: be <> with all shaders specified in pname:pStages * [[VUID-VkRayTracingPipelineCreateInfoNV-layout-02411]] The number of resources in pname:layout accessible to each shader stage that is used by the pipeline must: be less than or equal to slink:VkPhysicalDeviceLimits::pname:maxPerStageResources * [[VUID-VkRayTracingPipelineCreateInfoNV-maxRecursionDepth-02412]] pname:maxRecursionDepth must: be less than or equal to slink:VkPhysicalDeviceRayTracingPropertiesNV::pname:maxRecursionDepth **** include::../../validity/structs/VkRayTracingPipelineCreateInfoNV.txt[] -- [open,refpage='VkRayTracingShaderGroupCreateInfoNV',desc='Structure specifying shaders in a shader group',type='structs'] -- The sname:VkRayTracingShaderGroupCreateInfoNV structure is defined as: include::../../api/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] * pname:sType is the type of this structure. * pname:pNext is `NULL` or a pointer to an extension-specific structure. * pname:type is the type of hit group specified in this structure. * pname:generalShader is the index of the ray generation, miss, or callable shader from sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if the shader group has pname:type of ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV and ename:VK_SHADER_UNUSED_NV otherwise. * pname:closestHitShader is the optional index of the closest hit shader from sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if the shader group has pname:type of ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and ename:VK_SHADER_UNUSED_NV otherwise. * pname:anyHitShader is the optional index of the any-hit shader from sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if the shader group has pname:type of ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV or ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and ename:VK_SHADER_UNUSED_NV otherwise. * pname:intersectionShader is the index of the intersection shader from sname:VkRayTracingPipelineCreateInfoNV::pname:pStages in the group if the shader group has pname:type of ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV and ename:VK_SHADER_UNUSED_NV otherwise. .Valid Usage **** * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02413]] If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then pname:generalShader must: be a valid index into pname:pStages referring to a shader of ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, ename:VK_SHADER_STAGE_MISS_BIT_NV, or ename:VK_SHADER_STAGE_CALLABLE_BIT_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02414]] If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV then pname:closestHitShader, pname:anyHitShader, and pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02415]] If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV then pname:intersectionShader must: be a valid index into pname:pStages referring to a shader of ename:VK_SHADER_STAGE_INTERSECTION_BIT_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-type-02416]] If pname:type is ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV then pname:intersectionShader must: be ename:VK_SHADER_UNUSED_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-closestHitShader-02417]] pname:closestHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid index into pname:pStages referring to a shader of ename:VK_SHADER_STAGE_CLOSEST_HIT_BIT_NV * [[VUID-VkRayTracingShaderGroupCreateInfoNV-anyHitShader-02418]] pname:anyHitShader must: be either ename:VK_SHADER_UNUSED_NV or a valid index into pname:pStages referring to a shader of ename:VK_SHADER_STAGE_ANY_HIT_BIT_NV **** include::../../validity/structs/VkRayTracingShaderGroupCreateInfoNV.txt[] -- [open,refpage='VkRayTracingShaderGroupTypeNV',desc='Shader group types',type='enums'] -- Possible values of pname:type in sname:VkRayTracingShaderGroupCreateInfoNV are: include::../../api/enums/VkRayTracingShaderGroupTypeNV.txt[] * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_GENERAL_NV indicates a shader group with a single ename:VK_SHADER_STAGE_RAYGEN_BIT_NV, ename:VK_SHADER_STAGE_MISS_BIT_NV, or ename:VK_SHADER_STAGE_CALLABLE_BIT_NV shader in it. * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_TRIANGLES_HIT_GROUP_NV specifies a shader group that only hits triangles and must: not contain an intersection shader, only closest hit and any-hit. * ename:VK_RAY_TRACING_SHADER_GROUP_TYPE_PROCEDURAL_HIT_GROUP_NV specifies a shader group that only intersects with custom geometry and must: contain an intersection shader and may: contain closest hit and any-hit shaders. [NOTE] .Note ==== For current group types, the hit group type could be inferred from the presence or absence of the intersection shader, but we provide the type explicitly for future hit groups that do not have that property. ==== -- [open,refpage='vkGetRayTracingShaderGroupHandlesNV',desc='Query ray tracing pipeline shader group handles',type='protos'] -- To query the opaque handles of shaders in the ray tracing pipeline, call: include::../../api/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] * pname:device is the logical device that contains the ray tracing pipeline. * pname:pipeline is the ray tracing pipeline object that contains the shaders. * pname:firstGroup is the index of the first group to retrieve a handle for from the sname:VkPipelineShaderStageCreateInfo::pname:pGroups array. * pname:groupCount is the number of shader handles to retrieve. * pname:dataSize is the size in bytes of the buffer pointed to by pname:pData. * pname:pData is a pointer to a user-allocated buffer where the results will be written. .Valid Usage **** * [[VUID-vkGetRayTracingShaderGroupHandlesNV-firstGroup-02419]] The sum of pname:firstGroup and pname:groupCount must: be less than the number of shader groups in pname:pipeline. * [[VUID-vkGetRayTracingShaderGroupHandlesNV-dataSize-02420]] pname:dataSize must: be at least [eq]#sname:VkPhysicalDeviceRayTracingPropertiesNV::pname:shaderGroupHandleSize {times} pname:groupCount# **** include::../../validity/protos/vkGetRayTracingShaderGroupHandlesNV.txt[] -- Ray tracing pipelines can: contain more shaders than a graphics or compute pipeline, so to allow parallel compilation of shaders within a pipeline, an application can: choose to defer compilation until a later point in time. [open,refpage='vkCompileDeferredNV',desc='Deferred compilation of shaders',type='protos'] -- To compile a deferred shader in a pipeline call: include::../../api/protos/vkCompileDeferredNV.txt[] * pname:device is the logical device that contains the ray tracing pipeline. * pname:pipeline is the ray tracing pipeline object that contains the shaders. * pname:shader is the index of the shader to compile. .Valid Usage **** * [[VUID-vkCompileDeferredNV-pipeline-02237]] pname:pipeline must: have been created with ename:VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NV * [[VUID-vkCompileDeferredNV-shader-02238]] pname:shader must: not have been called as a deferred compile before **** include::../../validity/protos/vkCompileDeferredNV.txt[] --