pub unsafe trait GpuFuture: DeviceOwned {
Show 21 methods
// 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 { ... }
}
Expand description
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§
sourcefn cleanup_finished(&mut self)
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.
sourceunsafe fn build_submission(
&self
) -> Result<SubmitAnyBuilder, Validated<VulkanError>>
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.
sourcefn flush(&self) -> Result<(), Validated<VulkanError>>
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.
sourceunsafe fn signal_finished(&self)
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.
sourcefn queue(&self) -> Option<Arc<Queue>>
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.
sourcefn queue_change_allowed(&self) -> bool
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()
.
sourcefn check_buffer_access(
&self,
buffer: &Buffer,
range: Range<DeviceSize>,
exclusive: bool,
queue: &Queue
) -> Result<(), AccessCheckError>
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 returningErr
means “don’t know”. Therefore returningErr
is never unsafe.
sourcefn check_image_access(
&self,
image: &Image,
range: Range<DeviceSize>,
exclusive: bool,
expected_layout: ImageLayout,
queue: &Queue
) -> Result<(), AccessCheckError>
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 returningErr
means “don’t know”. Therefore returningErr
is never unsafe.
Note: Keep in mind that changing the layout of an image also requires exclusive access.
sourcefn check_swapchain_image_acquired(
&self,
swapchain: &Swapchain,
image_index: u32,
before: bool
) -> Result<(), AccessCheckError>
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
totrue
should skip checking the current future and always forward the call to the future before.
Provided Methods§
sourcefn join<F>(self, other: F) -> JoinFuture<Self, F>where
Self: Sized,
F: GpuFuture,
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.
sourcefn then_execute(
self,
queue: Arc<Queue>,
command_buffer: Arc<impl PrimaryCommandBufferAbstract + 'static>
) -> Result<CommandBufferExecFuture<Self>, CommandBufferExecError>where
Self: Sized,
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.
sourcefn then_execute_same_queue(
self,
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,
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.
sourcefn then_signal_semaphore(self) -> SemaphoreSignalFuture<Self>where
Self: Sized,
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.
sourcefn then_signal_semaphore_and_flush(
self
) -> Result<SemaphoreSignalFuture<Self>, Validated<VulkanError>>where
Self: Sized,
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.
sourcefn then_signal_fence(self) -> FenceSignalFuture<Self> ⓘwhere
Self: Sized,
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
.
sourcefn then_signal_fence_and_flush(
self
) -> Result<FenceSignalFuture<Self>, Validated<VulkanError>>where
Self: Sized,
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()
.
sourcefn then_swapchain_present(
self,
queue: Arc<Queue>,
swapchain_info: SwapchainPresentInfo
) -> PresentFuture<Self>where
Self: Sized,
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.
sourcefn boxed(self) -> Box<dyn GpuFuture>where
Self: Sized + 'static,
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>
.
sourcefn boxed_send(self) -> Box<dyn GpuFuture + Send>where
Self: Sized + Send + 'static,
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>
.