[−][src]Trait vulkano::sync::GpuFuture

pub unsafe trait GpuFuture: DeviceOwned {
    fn cleanup_finished(&mut self);

    unsafe fn build_submission(&self) -> Result<SubmitAnyBuilder, FlushError>;

    fn flush(&self) -> Result<(), FlushError>;

    unsafe fn signal_finished(&self);

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

    fn queue_change_allowed(&self) -> bool;

    fn check_buffer_access(
        &self, 
        buffer: &dyn BufferAccess, 
        exclusive: bool, 
        queue: &Queue
    ) -> Result<Option<(PipelineStages, AccessFlagBits)>, AccessCheckError>;

    fn check_image_access(
        &self, 
        image: &dyn ImageAccess, 
        layout: ImageLayout, 
        exclusive: bool, 
        queue: &Queue
    ) -> Result<Option<(PipelineStages, AccessFlagBits)>, AccessCheckError>;

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

    fn then_execute<Cb>(
        self, 
        queue: Arc<Queue>, 
        command_buffer: Cb
    ) -> Result<CommandBufferExecFuture<Self, Cb>, CommandBufferExecError>
    where
        Self: Sized,
        Cb: CommandBuffer + 'static,
    { ... }

    fn then_execute_same_queue<Cb>(
        self, 
        command_buffer: Cb
    ) -> Result<CommandBufferExecFuture<Self, Cb>, CommandBufferExecError>
    where
        Self: Sized,
        Cb: CommandBuffer + 'static,
    { ... }

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

    fn then_signal_semaphore_and_flush(
        self
    ) -> Result<SemaphoreSignalFuture<Self>, FlushError>
    where
        Self: Sized,
    { ... }

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

    fn then_signal_fence_and_flush(
        self
    ) -> Result<FenceSignalFuture<Self>, FlushError>
    where
        Self: Sized,
    { ... }

    fn then_swapchain_present<W>(
        self, 
        queue: Arc<Queue>, 
        swapchain: Arc<Swapchain<W>>, 
        image_index: usize
    ) -> PresentFuture<Self, W>
    where
        Self: Sized,
    { ... }

    fn then_swapchain_present_incremental<W>(
        self, 
        queue: Arc<Queue>, 
        swapchain: Arc<Swapchain<W>>, 
        image_index: usize, 
        present_region: PresentRegion
    ) -> PresentFuture<Self, W>
    where
        Self: Sized,
    { ... }
}

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, FlushError>

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<(), FlushError>

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: &dyn BufferAccess,
    exclusive: bool,
    queue: &Queue
) -> Result<Option<(PipelineStages, AccessFlagBits)>, 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.

If the access is granted, returns the pipeline stage and access flags of the latest usage of this resource, or None if irrelevant.

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: &dyn ImageAccess,
    layout: ImageLayout,
    exclusive: bool,
    queue: &Queue
) -> Result<Option<(PipelineStages, AccessFlagBits)>, 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.

If the access is granted, returns the pipeline stage and access flags of the latest usage of this resource, or None if irrelevant.

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.

Loading content...

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<Cb>(
    self,
    queue: Arc<Queue>,
    command_buffer: Cb
) -> Result<CommandBufferExecFuture<Self, Cb>, CommandBufferExecError> where
    Self: Sized,
    Cb: CommandBuffer + 'static, 

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<Cb>(
    self,
    command_buffer: Cb
) -> Result<CommandBufferExecFuture<Self, Cb>, CommandBufferExecError> where
    Self: Sized,
    Cb: CommandBuffer + 'static, 

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>, FlushError> 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>, FlushError> 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<W>(
    self,
    queue: Arc<Queue>,
    swapchain: Arc<Swapchain<W>>,
    image_index: usize
) -> PresentFuture<Self, W> 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 then_swapchain_present_incremental<W>(
    self,
    queue: Arc<Queue>,
    swapchain: Arc<Swapchain<W>>,
    image_index: usize,
    present_region: PresentRegion
) -> PresentFuture<Self, W> where
    Self: Sized, 

Same as then_swapchain_present, except it allows specifying a present region.

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

Loading content...

Implementations on Foreign Types

impl<F> GpuFuture for Arc<FenceSignalFuture<F>> where
    F: GpuFuture, [src]

impl<F: ?Sized> GpuFuture for Box<F> where
    F: GpuFuture, [src]

Loading content...

Implementors

impl GpuFuture for NowFuture[src]

impl<A, B> GpuFuture for JoinFuture<A, B> where
    A: GpuFuture,
    B: GpuFuture, [src]

impl<F> GpuFuture for FenceSignalFuture<F> where
    F: GpuFuture, [src]

impl<F> GpuFuture for SemaphoreSignalFuture<F> where
    F: GpuFuture, [src]

impl<F, Cb> GpuFuture for CommandBufferExecFuture<F, Cb> where
    F: GpuFuture,
    Cb: CommandBuffer, [src]

impl<P, W> GpuFuture for PresentFuture<P, W> where
    P: GpuFuture, [src]

impl<W> GpuFuture for SwapchainAcquireFuture<W>[src]

Loading content...