Struct RayTracingCommandRef 

pub struct RayTracingCommandRef<'a> { /* private fields */ }

Recording interface for ray tracing commands.

This structure provides a strongly-typed set of methods which allow ray tracing shader code to be executed. An instance is provided to the closure argument of PipelineCommand::record_cmd which may be accessed by binding a RayTracingPipeline to a command.

Examples

Basic usage:

my_graph.begin_cmd()
        .debug_name("my ray tracing command")
        .bind_pipeline(&my_ray_tracing_pipeline)
        .record_cmd(move |cmd| {
            // During this closure we have access to the ray tracing functions!
        });

Implementations

impl RayTracingCommandRef<'_>

pub fn push_constants(&self, offset: u32, data: &[u8]) -> &Self

Updates push constants.

Push constants represent a high-speed path to modify constant data in pipelines that is expected to outperform memory-backed resource updates.

Push constant values can be updated incrementally, causing shader stages to read the new data for push constants modified by this command, while still reading the previous data for push constants not modified by this command.

Device limitations

See VkPhysicalDeviceLimits::maxPushConstantsSize for the limit of the current device. You may also check [gpuinfo.org] for a listing of reported limits on other devices.

Examples

Basic usage:

#version 460
#pragma shader_stage(closest)

layout(push_constant) uniform PushConstants {
    layout(offset = 0) uint some_val;
} push_constants;

void main() {
    uint value = push_constants.some_val;
}

my_graph.begin_cmd()
        .debug_name("draw a cornell box")
        .bind_pipeline(&my_ray_tracing_pipeline)
        .record_cmd(move |cmd| {
            cmd.push_constants(0, &[0xcb])
                   .trace_rays(&rgen_sbt, &hit_sbt, &miss_sbt, &call_sbt, 320, 200, 1);
        });

See vkCmdPushConstants.

pub fn set_stack_size(&self, pipeline_stack_size: u32) -> &Self

Sets the stack size dynamically for a ray tracing pipeline.

The pipeline must have been created with RayTracingPipelineInfo::dynamic_stack_size enabled.

See vkCmdSetRayTracingPipelineStackSizeKHR.

pub fn trace_rays( &self, raygen_shader_binding_table: &StridedDeviceAddressRegionKHR, miss_shader_binding_table: &StridedDeviceAddressRegionKHR, hit_shader_binding_table: &StridedDeviceAddressRegionKHR, callable_shader_binding_table: &StridedDeviceAddressRegionKHR, width: u32, height: u32, depth: u32, ) -> &Self

Ray traces using the currently-bound RayTracingPipeline and the given shader binding tables.

Shader binding tables must be constructed according to this example.

See vkCmdTraceRaysKHR.

Examples

Basic usage:

my_graph.begin_cmd()
        .debug_name("draw a cornell box")
        .bind_pipeline(&my_ray_tracing_pipeline)
        .record_cmd(move |cmd| {
            cmd.trace_rays(&rgen_sbt, &hit_sbt, &miss_sbt, &call_sbt, 320, 200, 1);
        });

pub fn trace_rays_indirect( &self, raygen_shader_binding_table: &StridedDeviceAddressRegionKHR, miss_shader_binding_table: &StridedDeviceAddressRegionKHR, hit_shader_binding_table: &StridedDeviceAddressRegionKHR, callable_shader_binding_table: &StridedDeviceAddressRegionKHR, indirect_device_address: DeviceAddress, ) -> &Self

Ray traces using the currently-bound RayTracingPipeline and the given shader binding tables.

indirect_device_address is a buffer device address which is a pointer to a vk::TraceRaysIndirectCommandKHR structure containing the trace ray parameters.

See vkCmdTraceRaysIndirectKHR.

Methods from Deref<Target = CommandRef<'a>>

pub fn build_accel_struct( &self, infos: &[BuildAccelerationStructureInfo], ) -> &Self

Build acceleration structures.

There is no ordering or synchronization implied between any of the individual acceleration structure builds.

Requires a scratch buffer which was created with the following requirements:

• Flags must include vk::BufferUsageFlags::SHADER_DEVICE_ADDRESS
• Size must be equal to or greater than the build_size value returned by AccelerationStructure::size_of, aligned to min_accel_struct_scratch_offset_alignment of PhysicalDevice::vk_khr_acceleration_structure.

Examples

Basic usage:

my_graph.begin_cmd()
        .resource_access(index_buf, AccessType::IndexBuffer)
        .resource_access(vertex_buf, AccessType::VertexBuffer)
        .resource_access(scratch_buf, AccessType::AccelerationStructureBufferWrite)
        .resource_access(blas_node, AccessType::AccelerationStructureBuildWrite)
        .record_cmd(move |cmd| {
            let scratch_addr = cmd.resource(scratch_buf).device_address();
            let geom = AccelerationStructureGeometry {
                max_primitive_count: 64,
                flags: vk::GeometryFlagsKHR::OPAQUE,
                geometry: AccelerationStructureGeometryData::Triangles {
                    index_addr: DeviceOrHostAddress::DeviceAddress(
                        cmd.resource(index_buf).device_address()
                    ),
                    index_type: vk::IndexType::UINT32,
                    max_vertex: 42,
                    transform_addr: None,
                    vertex_addr: DeviceOrHostAddress::DeviceAddress(
                        cmd.resource(vertex_buf).device_address(),
                    ),
                    vertex_format: vk::Format::R32G32B32_SFLOAT,
                    vertex_stride: 12,
                },
            };
            let build_range = vk::AccelerationStructureBuildRangeInfoKHR {
                first_vertex: 0,
                primitive_count: 1,
                primitive_offset: 0,
                transform_offset: 0,
            };
            let info = AccelerationStructureGeometryInfo::blas([(geom, build_range)]);

            cmd.build_accel_struct(&[
                BuildAccelerationStructureInfo::new(blas_node, scratch_addr, info)
            ]);
        });

See also:

• examples/ray_omni.rs
• examples/ray_tracing.rs
• examples/rt_triangle.rs

pub fn build_accel_struct_indirect( &self, infos: &[BuildAccelerationStructureIndirectInfo], ) -> &Self

Builds acceleration structures with some parameters provided on the device.

There is no ordering or synchronization implied between any of the individual acceleration structure builds.

Each BuildAccelerationStructureIndirectInfo::range_base is a buffer device address which points to an array of vk::AccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored.

pub fn update_accel_struct( &self, infos: &[UpdateAccelerationStructureInfo], ) -> &Self

Update acceleration structures.

There is no ordering or synchronization implied between any of the individual acceleration structure updates.

Requires a scratch buffer which was created with the following requirements:

• Flags must include vk::BufferUsageFlags::SHADER_DEVICE_ADDRESS
• Size must be equal to or greater than the update_size value returned by AccelerationStructure::size_of, aligned to min_accel_struct_scratch_offset_alignment of PhysicalDevice::vk_khr_acceleration_structure.

pub fn update_accel_struct_indirect( &self, infos: &[UpdateAccelerationStructureIndirectInfo], ) -> &Self

Updates acceleration structures with some parameters provided on the device.

There is no ordering or synchronization implied between any of the individual acceleration structure updates.

Each UpdateAccelerationStructureIndirectInfo::range_base is a buffer device address which points to an array of vk::AccelerationStructureBuildRangeInfoKHR structures defining dynamic offsets to the addresses where geometry data is stored.

pub fn resource<N>(&self, resource_node: N) -> &N::Resource

where N: Node,

Returns a borrow of the original Vulkan resource (buffer, image or acceleration structure) which the given bound resource node represents.

Methods from Deref<Target = CommandBuffer>

pub fn begin( &self, info: &CommandBufferBeginInfo<'_>, ) -> Result<(), DriverError>

Begins recording this command buffer.

This is a thin wrapper around ash::Device::begin_command_buffer that maps Vulkan errors to DriverError variants.

See vkBeginCommandBuffer.

pub fn end(&self) -> Result<(), DriverError>

Ends recording this command buffer.

This is a thin wrapper around ash::Device::end_command_buffer that maps Vulkan errors to DriverError variants.

See vkEndCommandBuffer.

pub fn end_render_pass(&self)

Ends recording a render pass.

pub fn queue_submit( &self, queue: Queue, fence: &mut Fence, submits: &[SubmitInfo<'_>], ) -> Result<(), DriverError>

Submits command buffers to a queue using fence.

This method does not begin, end, or reset self or fence. Callers are expected to submit only executable command buffers and to manage fence waits and resets as needed.

Typical handling is:

1. Begin recording with Self::begin.
2. Record commands.
3. End recording with Self::end.
4. Submit this command buffer with queue_submit.
5. Later, check or wait for completion with Fence::status or Fence::wait.
6. Before re-submitting this same command buffer, reset the fence with Fence::reset, then begin recording again.

See vkQueueSubmit.

pub fn queue_submit2( &self, queue: Queue, fence: &mut Fence, submits: &[SubmitInfo2<'_>], ) -> Result<(), DriverError>

Submits command buffers to a queue using vkQueueSubmit2 (Vulkan 1.3 core or VK_KHR_synchronization2).

See vkQueueSubmit2 and VK_KHR_synchronization2.

pub fn set_debug_name(&self, name: impl AsRef<str>)

Sets the debugging name assigned to this command buffer.

Trait Implementations

impl<'a> Deref for RayTracingCommandRef<'a>

type Target = CommandRef<'a>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.