Struct vulkano::command_buffer::submit::SubmitCommandBufferBuilder

pub struct SubmitCommandBufferBuilder<'a> { /* fields omitted */ }

Prototype for a submission that executes command buffers.

Implementations

impl<'a> SubmitCommandBufferBuilder<'a>

pub fn new() -> SubmitCommandBufferBuilder<'a>

Builds a new empty SubmitCommandBufferBuilder.

pub fn has_fence(&self) -> bool

Returns true if this builder will signal a fence when submitted.

Example

use vulkano::command_buffer::submit::SubmitCommandBufferBuilder;
use vulkano::sync::Fence;

unsafe {
    let fence = Fence::from_pool(device.clone()).unwrap();

    let mut builder = SubmitCommandBufferBuilder::new();
    assert!(!builder.has_fence());
    builder.set_fence_signal(&fence);
    assert!(builder.has_fence());
}

pub unsafe fn set_fence_signal(&mut self, fence: &'a Fence)

Adds an operation that signals a fence after this submission ends.

Example

use std::time::Duration;
use vulkano::command_buffer::submit::SubmitCommandBufferBuilder;
use vulkano::sync::Fence;

unsafe {
    let fence = Fence::from_pool(device.clone()).unwrap();

    let mut builder = SubmitCommandBufferBuilder::new();
    builder.set_fence_signal(&fence);

    builder.submit(&queue).unwrap();

    // We must not destroy the fence before it is signaled.
    fence.wait(Some(Duration::from_secs(5))).unwrap();
}

Safety

• The fence must not be signaled at the time when you call submit().

• If you use the fence for multiple submissions, only one at a time must be executed by the GPU. In other words, you must submit one, wait for the fence to be signaled, then reset the fence, and then only submit the second.

• If you submit this builder, the fence must be kept alive until it is signaled by the GPU. Destroying the fence earlier is an undefined behavior.

• The fence, command buffers, and semaphores must all belong to the same device.

pub unsafe fn add_wait_semaphore(
    &mut self,
    semaphore: &'a Semaphore,
    stages: PipelineStages
)

Adds a semaphore to be waited upon before the command buffers are executed.

Only the given stages of the command buffers added afterwards will wait upon the semaphore. Other stages not included in stages can execute before waiting.

Safety

• The stages must be supported by the device.

• If you submit this builder, the semaphore must be kept alive until you are guaranteed that the GPU has at least started executing the command buffers.

• If you submit this builder, no other queue must be waiting on these semaphores. In other words, each semaphore signal can only correspond to one semaphore wait.

• If you submit this builder, the semaphores must be signaled when the queue execution reaches this submission, or there must be one or more submissions in queues that are going to signal these semaphores. In other words, you must not block the queue with semaphores that can't get signaled.

• The fence, command buffers, and semaphores must all belong to the same device.

pub unsafe fn add_command_buffer<P>(
    &mut self,
    command_buffer: &'a UnsafeCommandBuffer<P>
)

Adds a command buffer that is executed as part of this command.

The command buffers are submitted in the order in which they are added.

Safety

• If you submit this builder, the command buffer must be kept alive until you are guaranteed that the GPU has finished executing it.

• Any calls to vkCmdSetEvent, vkCmdResetEvent or vkCmdWaitEvents that have been recorded into the command buffer must not reference any VkEvent that is referenced by any of those commands that is pending execution on another queue. TODO: rephrase ^ ?

• The fence, command buffers, and semaphores must all belong to the same device.

TODO: more here

pub fn num_signal_semaphores(&self) -> usize

Returns the number of semaphores to signal.

In other words, this is the number of times add_signal_semaphore has been called.

pub unsafe fn add_signal_semaphore(&mut self, semaphore: &'a Semaphore)

Adds a semaphore that is going to be signaled at the end of the submission.

Safety

• If you submit this builder, the semaphore must be kept alive until you are guaranteed that the GPU has finished executing this submission.

• The semaphore must be in the unsignaled state when queue execution reaches this submission.

• The fence, command buffers, and semaphores must all belong to the same device.

pub fn submit(self, queue: &Queue) -> Result<(), SubmitCommandBufferError>

Submits the command buffer to the given queue.

Note: This is an expensive operation, so you may want to merge as many builders as possible together and avoid submitting them one by one.

pub fn merge(self, other: Self) -> Self

Merges this builder with another builder.

Panic

Panics if both builders have a fence already set.

Trait Implementations

impl<'a> Debug for SubmitCommandBufferBuilder<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Into<SubmitCommandBufferBuilder<'a>> for SubmitSemaphoresWaitBuilder<'a>

fn into(self) -> SubmitCommandBufferBuilder<'a>

Performs the conversion.