Trait vulkano::sync::future::GpuFuture

pub unsafe trait GpuFuture: DeviceOwned {
    // Required methods
    fn cleanup_finished(&mut self);
    unsafe fn build_submission(
        &self
    ) -> Result<SubmitAnyBuilder, Validated<VulkanError>>;
    fn flush(&self) -> Result<(), Validated<VulkanError>>;
    unsafe fn signal_finished(&self);
    fn queue(&self) -> Option<Arc<Queue>>;
    fn queue_change_allowed(&self) -> bool;
    fn check_buffer_access(
        &self,
        buffer: &Buffer,
        range: Range<DeviceSize>,
        exclusive: bool,
        queue: &Queue
    ) -> Result<(), AccessCheckError>;
    fn check_image_access(
        &self,
        image: &Image,
        range: Range<DeviceSize>,
        exclusive: bool,
        expected_layout: ImageLayout,
        queue: &Queue
    ) -> Result<(), AccessCheckError>;
    fn check_swapchain_image_acquired(
        &self,
        swapchain: &Swapchain,
        image_index: u32,
        before: bool
    ) -> Result<(), AccessCheckError>;

    // Provided methods
    fn join<F>(self, other: F) -> JoinFuture<Self, F>
       where Self: Sized,
             F: GpuFuture { ... }
    fn then_execute(
        self,
        queue: Arc<Queue>,
        command_buffer: Arc<impl PrimaryCommandBufferAbstract + 'static>
    ) -> Result<CommandBufferExecFuture<Self>, CommandBufferExecError>
       where Self: Sized { ... }
    fn then_execute_same_queue(
        self,
        command_buffer: Arc<impl PrimaryCommandBufferAbstract + 'static>
    ) -> Result<CommandBufferExecFuture<Self>, CommandBufferExecError>
       where Self: Sized { ... }
    fn then_signal_semaphore(self) -> SemaphoreSignalFuture<Self>
       where Self: Sized { ... }
    fn then_signal_semaphore_and_flush(
        self
    ) -> Result<SemaphoreSignalFuture<Self>, Validated<VulkanError>>
       where Self: Sized { ... }
    fn then_signal_fence(self) -> FenceSignalFuture<Self> 
       where Self: Sized { ... }
    fn then_signal_fence_and_flush(
        self
    ) -> Result<FenceSignalFuture<Self>, Validated<VulkanError>>
       where Self: Sized { ... }
    fn then_swapchain_present(
        self,
        queue: Arc<Queue>,
        swapchain_info: SwapchainPresentInfo
    ) -> PresentFuture<Self>
       where Self: Sized { ... }
    fn boxed(self) -> Box<dyn GpuFuture>
       where Self: Sized + 'static { ... }
    fn boxed_send(self) -> Box<dyn GpuFuture + Send>
       where Self: Sized + Send + 'static { ... }
    fn boxed_sync(self) -> Box<dyn GpuFuture + Sync>
       where Self: Sized + Sync + 'static { ... }
    fn boxed_send_sync(self) -> Box<dyn GpuFuture + Send + Sync>
       where Self: Sized + Send + Sync + 'static { ... }
}

Represents an event that will happen on the GPU in the future.

See the documentation of the sync module for explanations about futures.

Required Methods

fn cleanup_finished(&mut self)

If possible, checks whether the submission has finished. If so, gives up ownership of the resources used by these submissions.

It is highly recommended to call cleanup_finished from time to time. Doing so will prevent memory usage from increasing over time, and will also destroy the locks on resources used by the GPU.

unsafe fn build_submission( &self ) -> Result<SubmitAnyBuilder, Validated<VulkanError>>

Builds a submission that, if submitted, makes sure that the event represented by this GpuFuture will happen, and possibly contains extra elements (eg. a semaphore wait or an event wait) that makes the dependency with subsequent operations work.

It is the responsibility of the caller to ensure that the submission is going to be submitted only once. However keep in mind that this function can perfectly be called multiple times (as long as the returned object is only submitted once). Also note that calling flush() on the future may change the value returned by build_submission().

It is however the responsibility of the implementation to not return the same submission from multiple different future objects. For example if you implement GpuFuture on Arc<Foo> then build_submission() must always return SubmitAnyBuilder::Empty, otherwise it would be possible for the user to clone the Arc and make the same submission be submitted multiple times.

It is also the responsibility of the implementation to ensure that it works if you call build_submission() and submits the returned value without calling flush() first. In other words, build_submission() should perform an implicit flush if necessary.

Once the caller has submitted the submission and has determined that the GPU has finished executing it, it should call signal_finished. Failure to do so will incur a large runtime overhead, as the future will have to block to make sure that it is finished.

fn flush(&self) -> Result<(), Validated<VulkanError>>

Flushes the future and submits to the GPU the actions that will permit this future to occur.

The implementation must remember that it was flushed. If the function is called multiple times, only the first time must result in a flush.

unsafe fn signal_finished(&self)

Sets the future to its “complete” state, meaning that it can safely be destroyed.

This must only be done if you called build_submission(), submitted the returned submission, and determined that it was finished.

The implementation must be aware that this function can be called multiple times on the same future.

fn queue(&self) -> Option<Arc<Queue>>

Returns the queue that triggers the event. Returns None if unknown or irrelevant.

If this function returns None and queue_change_allowed returns false, then a panic is likely to occur if you use this future. This is only a problem if you implement the GpuFuture trait yourself for a type outside of vulkano.

fn queue_change_allowed(&self) -> bool

Returns true if elements submitted after this future can be submitted to a different queue than the other returned by queue().

fn check_buffer_access( &self, buffer: &Buffer, range: Range<DeviceSize>, exclusive: bool, queue: &Queue ) -> Result<(), AccessCheckError>

Checks whether submitting something after this future grants access (exclusive or shared, depending on the parameter) to the given buffer on the given queue.

Note: Returning Ok means “access granted”, while returning Err means “don’t know”. Therefore returning Err is never unsafe.

fn check_image_access( &self, image: &Image, range: Range<DeviceSize>, exclusive: bool, expected_layout: ImageLayout, queue: &Queue ) -> Result<(), AccessCheckError>

Checks whether submitting something after this future grants access (exclusive or shared, depending on the parameter) to the given image on the given queue.

Implementations must ensure that the image is in the given layout. However if the layout is Undefined then the implementation should accept any actual layout.

Note: Returning Ok means “access granted”, while returning Err means “don’t know”. Therefore returning Err is never unsafe.

Note: Keep in mind that changing the layout of an image also requires exclusive access.

fn check_swapchain_image_acquired( &self, swapchain: &Swapchain, image_index: u32, before: bool ) -> Result<(), AccessCheckError>

Checks whether accessing a swapchain image is permitted.

Note: Setting before to true should skip checking the current future and always forward the call to the future before.

Provided Methods

fn join<F>(self, other: F) -> JoinFuture<Self, F>where Self: Sized, F: GpuFuture,

Joins this future with another one, representing the moment when both events have happened.

fn then_execute( self, queue: Arc<Queue>, command_buffer: Arc<impl PrimaryCommandBufferAbstract + 'static> ) -> Result<CommandBufferExecFuture<Self>, CommandBufferExecError>where Self: Sized,

Executes a command buffer after this future.

Note: This is just a shortcut function. The actual implementation is in the CommandBuffer trait.

fn then_execute_same_queue( self, command_buffer: Arc<impl PrimaryCommandBufferAbstract + 'static> ) -> Result<CommandBufferExecFuture<Self>, CommandBufferExecError>where Self: Sized,

Executes a command buffer after this future, on the same queue as the future.

Note: This is just a shortcut function. The actual implementation is in the CommandBuffer trait.

fn then_signal_semaphore(self) -> SemaphoreSignalFuture<Self>where Self: Sized,

Signals a semaphore after this future. Returns another future that represents the signal.

Call this function when you want to execute some operations on a queue and want to see the result on another queue.

fn then_signal_semaphore_and_flush( self ) -> Result<SemaphoreSignalFuture<Self>, Validated<VulkanError>>where Self: Sized,

Signals a semaphore after this future and flushes it. Returns another future that represents the moment when the semaphore is signalled.

This is a just a shortcut for then_signal_semaphore() followed with flush().

When you want to execute some operations A on a queue and some operations B on another queue that need to see the results of A, it can be a good idea to submit A as soon as possible while you’re preparing B.

If you ran A and B on the same queue, you would have to decide between submitting A then B, or A and B simultaneously. Both approaches have their trade-offs. But if A and B are on two different queues, then you would need two submits anyway and it is always advantageous to submit A as soon as possible.

fn then_signal_fence(self) -> FenceSignalFuture<Self> where Self: Sized,

Signals a fence after this future. Returns another future that represents the signal.

Note: More often than not you want to immediately flush the future after calling this function. If so, consider using then_signal_fence_and_flush.

fn then_signal_fence_and_flush( self ) -> Result<FenceSignalFuture<Self>, Validated<VulkanError>>where Self: Sized,

Signals a fence after this future. Returns another future that represents the signal.

This is a just a shortcut for then_signal_fence() followed with flush().

fn then_swapchain_present( self, queue: Arc<Queue>, swapchain_info: SwapchainPresentInfo ) -> PresentFuture<Self>where Self: Sized,

Presents a swapchain image after this future.

You should only ever do this indirectly after a SwapchainAcquireFuture of the same image, otherwise an error will occur when flushing.

Note: This is just a shortcut for the Swapchain::present() function.

fn boxed(self) -> Box<dyn GpuFuture>where Self: Sized + 'static,

Turn the current future into a Box<dyn GpuFuture>.

This is a helper function that calls Box::new(yourFuture) as Box<dyn GpuFuture>.

fn boxed_send(self) -> Box<dyn GpuFuture + Send>where Self: Sized + Send + 'static,

Turn the current future into a Box<dyn GpuFuture + Send>.

This is a helper function that calls Box::new(yourFuture) as Box<dyn GpuFuture + Send>.

fn boxed_sync(self) -> Box<dyn GpuFuture + Sync>where Self: Sized + Sync + 'static,

Turn the current future into a Box<dyn GpuFuture + Sync>.

This is a helper function that calls Box::new(yourFuture) as Box<dyn GpuFuture + Sync>.

fn boxed_send_sync(self) -> Box<dyn GpuFuture + Send + Sync>where Self: Sized + Send + Sync + 'static,

Turn the current future into a Box<dyn GpuFuture + Send + Sync>.

This is a helper function that calls Box::new(yourFuture) as Box<dyn GpuFuture + Send + Sync>.

Implementations on Foreign Types

impl<F> GpuFuture for Box<F>where F: GpuFuture + ?Sized,

fn cleanup_finished(&mut self)

unsafe fn build_submission( &self ) -> Result<SubmitAnyBuilder, Validated<VulkanError>>

fn flush(&self) -> Result<(), Validated<VulkanError>>

unsafe fn signal_finished(&self)

fn queue_change_allowed(&self) -> bool

fn queue(&self) -> Option<Arc<Queue>>

fn check_buffer_access( &self, buffer: &Buffer, range: Range<DeviceSize>, exclusive: bool, queue: &Queue ) -> Result<(), AccessCheckError>

fn check_image_access( &self, image: &Image, range: Range<DeviceSize>, exclusive: bool, expected_layout: ImageLayout, queue: &Queue ) -> Result<(), AccessCheckError>

fn check_swapchain_image_acquired( &self, swapchain: &Swapchain, image_index: u32, before: bool ) -> Result<(), AccessCheckError>

impl<F> GpuFuture for Arc<FenceSignalFuture<F>>where F: GpuFuture,

fn cleanup_finished(&mut self)

unsafe fn build_submission( &self ) -> Result<SubmitAnyBuilder, Validated<VulkanError>>

fn flush(&self) -> Result<(), Validated<VulkanError>>

unsafe fn signal_finished(&self)

fn queue_change_allowed(&self) -> bool

fn queue(&self) -> Option<Arc<Queue>>

fn check_buffer_access( &self, buffer: &Buffer, range: Range<DeviceSize>, exclusive: bool, queue: &Queue ) -> Result<(), AccessCheckError>

fn check_image_access( &self, image: &Image, range: Range<DeviceSize>, exclusive: bool, expected_layout: ImageLayout, queue: &Queue ) -> Result<(), AccessCheckError>

fn check_swapchain_image_acquired( &self, swapchain: &Swapchain, image_index: u32, before: bool ) -> Result<(), AccessCheckError>

Implementors

impl GpuFuture for SwapchainAcquireFuture

impl GpuFuture for NowFuture

impl<A, B> GpuFuture for JoinFuture<A, B>where A: GpuFuture, B: GpuFuture,

impl<F> GpuFuture for CommandBufferExecFuture<F>where F: GpuFuture,

impl<F> GpuFuture for FenceSignalFuture<F>where F: GpuFuture,

impl<F> GpuFuture for SemaphoreSignalFuture<F>where F: GpuFuture,

impl<P> GpuFuture for PresentFuture<P>where P: GpuFuture,