// This section is included inside the Pipelines chapter (pipelines.txt)

[[pipelines-raytracing]]
== Raytracing Pipeline

Raytracing pipelines consist of multiple shader stages, fixed-function
traversal stages, and a pipeline layout.

[open,refpage='vkCreateRaytracingPipelinesNVX',desc='Creates a new raytracing pipeline object',type='protos']
--

To create raytracing pipelines, call:

include::../../api/protos/vkCreateRaytracingPipelinesNVX.txt[]

  * pname:device is the logical device that creates the raytracing
    pipelines.
  * pname:pipelineCache is either dlink:VK_NULL_HANDLE, indicating that
    pipeline caching is disabled; or the handle of a valid
    <<pipelines-cache,pipeline cache>> 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:VkRaytracingPipelineCreateInfoNVX structures.
  * pname:pAllocator controls host memory allocation as described in the
    <<memory-allocation, Memory Allocation>> chapter.
  * pname:pPipelines is a pointer to an array in which the resulting compute
    pipeline objects are returned.

.Valid Usage
****
****

include::../../validity/protos/vkCreateRaytracingPipelinesNVX.txt[]
--

[open,refpage='VkRaytracingPipelineCreateInfoNVX',desc='Structure specifying parameters of a newly created raytracing pipeline',type='structs']
--

The sname:VkRaytracingPipelineCreateInfoNVX structure is defined as:

include::../../api/structs/VkRaytracingPipelineCreateInfoNVX.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 and
    pname:pGroupNumbers arrays.
  * 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 raytracing pipeline.
  * pname:pGroupNumbers is an array of size pname:stageCount integers, where
    each integer indicates the hit group that the corresponding shader
    belongs to.
  * 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 <<pipelines-pipeline-derivatives,Pipeline
Derivatives>>.

.Valid Usage
****
****

include::../../validity/structs/VkRaytracingPipelineCreateInfoNVX.txt[]
--

[open,refpage='vkGetRaytracingShaderHandlesNVX',desc='Query raytracing pipeline shader handles',type='protos']
--

To query the opaque handles of shaders in the raytracing pipeline, call:

include::../../api/protos/vkGetRaytracingShaderHandlesNVX.txt[]

  * pname:device is the logical device that contains the raytracing
    pipeline.
  * pname:pipeline is the raytracing pipeline object that contains the
    shaders.
  * pname:firstShader is the index of the first shader to retrieve a handle
    for from the pname:pStages array of
    sname:VkPipelineShaderStageCreateInfo entries.
  * pname:shaderCount is the number of shader handles to retrieve.
  * pname:dataSize is the size in bytes of the buffer pointed to by pData.
  * pname:pData is a pointer to a user-allocated buffer where the results
    will be written.

.Valid Usage
****
****

include::../../validity/protos/vkGetRaytracingShaderHandlesNVX.txt[]
--

Raytracing pipelines can contain more shaders than a graphics or compute
pipeline, so to allow parallel compilation of shaders within a pipeline, an
application may: choose to defer compilation until a later point in time.

[open,refpage='vkCompileDeferredNVX',desc='Deferred compilation of shaders',type='protos']
--

To compile a deferred shader in a pipeline call:

include::../../api/protos/vkCompileDeferredNVX.txt[]

  * pname:device is the logical device that contains the raytracing
    pipeline.
  * pname:pipeline is the raytracing pipeline object that contains the
    shaders.
  * pname:shader is the index of the shader to compile.

.Valid Usage
****
  * [[VUID-vkCompileDeferredNVX-pipeline-02237]]
    pname:pipeline must: have been created with
    VK_PIPELINE_CREATE_DEFER_COMPILE_BIT_NVX.
  * [[VUID-vkCompileDeferredNVX-shader-02238]]
    pname:shader must: not have been called as a deferred compile before.
****

include::../../validity/protos/vkCompileDeferredNVX.txt[]
--