pub struct ImageCmd<'c, T: 'c> { /* private fields */ }
Expand description
An image command builder for enqueuing reads, writes, fills, and copies.
§Examples
// Copies one image to another:
src_image.cmd().copy(&dst_image, [0, 0, 0]).enq().unwrap();
// Writes from a vector to an image, waiting on an event:
image.write(&src_vec).ewait(&event).enq().unwrap();
// Reads from a image into a vector, waiting on an event list and
// filling a new empty event:
image.read(&dst_vec).ewait(&event_list).enew(&empty_event).enq().unwrap();
// Reads without blocking:
image.cmd().read_async(&dst_vec).enew(&empty_event).enq().unwrap();
[FIXME]: Fills not yet implemented.
Implementations§
source§impl<'c, T: 'c + OclPrm> ImageCmd<'c, T>
impl<'c, T: 'c + OclPrm> ImageCmd<'c, T>
[UNSTABLE]: All methods still in a state of adjustifulsomeness.
sourcepub fn read<'d>(self, dst_data: &'d mut [T]) -> ImageCmd<'c, T>where
'd: 'c,
pub fn read<'d>(self, dst_data: &'d mut [T]) -> ImageCmd<'c, T>where
'd: 'c,
Specifies that this command will be a blocking read operation.
After calling this method, the blocking state of this command will
be locked to true and a call to ::block
will cause a panic.
§Panics
The command operation kind must not have already been specified.
§More Information
See SDK docs for more details.
sourcepub unsafe fn map(self) -> ImageMapCmd<'c, T>
pub unsafe fn map(self) -> ImageMapCmd<'c, T>
Specifies that this command will be a map operation.
If .block(..)
has been set it will be ignored. Non-blocking map
commands are enqueued using ::enq_async
.
§Safety
The caller must ensure that only one mapping of a particular memory region exists at a time.
§Panics
The command operation kind must not have already been specified
§More Information
See SDK docs for more details.
sourcepub fn copy<'d>(
self,
dst_image: &'d Image<T>,
dst_origin: [usize; 3]
) -> ImageCmd<'c, T>where
'd: 'c,
pub fn copy<'d>(
self,
dst_image: &'d Image<T>,
dst_origin: [usize; 3]
) -> ImageCmd<'c, T>where
'd: 'c,
sourcepub fn copy_to_buffer<'d>(
self,
buffer: &'d MemCore,
dst_offset: usize
) -> ImageCmd<'c, T>where
'd: 'c,
pub fn copy_to_buffer<'d>(
self,
buffer: &'d MemCore,
dst_offset: usize
) -> ImageCmd<'c, T>where
'd: 'c,
Specifies that this command will be a copy to image.
If .block(..)
has been set it will be ignored.
§Panics
The command operation kind must not have already been specified
sourcepub fn gl_acquire(self) -> ImageCmd<'c, T>
pub fn gl_acquire(self) -> ImageCmd<'c, T>
Specifies that this command will acquire a GL buffer.
If .block(..)
has been set it will be ignored.
§Panics
The command operation kind must not have already been specified
sourcepub fn gl_release(self) -> ImageCmd<'c, T>
pub fn gl_release(self) -> ImageCmd<'c, T>
Specifies that this command will release a GL buffer.
If .block(..)
has been set it will be ignored.
§Panics
The command operation kind must not have already been specified
sourcepub fn d3d11_acquire(self) -> ImageCmd<'c, T>
pub fn d3d11_acquire(self) -> ImageCmd<'c, T>
Specifies that this command will acquire a D3D11 buffer.
If .block(..)
has been set it will be ignored.
§Panics
The command operation kind must not have already been specified
sourcepub fn d3d11_release(self) -> ImageCmd<'c, T>
pub fn d3d11_release(self) -> ImageCmd<'c, T>
Specifies that this command will release a D3D11 buffer.
If .block(..)
has been set it will be ignored.
§Panics
The command operation kind must not have already been specified
sourcepub fn fill(self, color: T) -> ImageCmd<'c, T>
pub fn fill(self, color: T) -> ImageCmd<'c, T>
Specifies that this command will be a fill.
If .block(..)
has been set it will be ignored.
§Panics
The command operation kind must not have already been specified
sourcepub fn queue(self, queue: &'c Queue) -> ImageCmd<'c, T>
pub fn queue(self, queue: &'c Queue) -> ImageCmd<'c, T>
Specifies a queue to use for this call only.
Overrides the image’s default queue if one is set. If no default queue is set, this method must be called before enqueuing the command.
sourcepub unsafe fn block(self, block: bool) -> ImageCmd<'c, T>
pub unsafe fn block(self, block: bool) -> ImageCmd<'c, T>
Specifies whether or not to block the current thread until completion.
Ignored if this is not a read or write operation.
Default is block = true
.
§Safety
When performing non-blocking reads or writes, the caller must ensure
that the data being read from or written to is not accessed improperly
until the command completes. Use events (Event::wait_for
) or the
command queue (Queue::finish
) to synchronize.
If possible, prefer instead to use ::map
with ::enq_async
for
optimal performance and data integrity.
sourcepub fn origin<D>(self, origin: D) -> ImageCmd<'c, T>where
D: Into<SpatialDims>,
pub fn origin<D>(self, origin: D) -> ImageCmd<'c, T>where
D: Into<SpatialDims>,
Sets the three dimensional offset, the origin point, for an operation.
Defaults to [0, 0, 0] if not set.
§Panics
The ‘shape’ may not have already been set to rectangular by the
::rect
function.
sourcepub fn region<D>(self, region: D) -> ImageCmd<'c, T>where
D: Into<SpatialDims>,
pub fn region<D>(self, region: D) -> ImageCmd<'c, T>where
D: Into<SpatialDims>,
Sets the region size for an operation.
Defaults to the full region size of the image(s) as defined when first created if not set.
§Panics [TENATIVE]
Panics if the region is out of range on any of the three dimensions.
[FIXME]: Probably delay checking this until enq().
sourcepub unsafe fn pitch_bytes(
self,
row_pitch_bytes: usize,
slc_pitch_bytes: usize
) -> ImageCmd<'c, T>
pub unsafe fn pitch_bytes( self, row_pitch_bytes: usize, slc_pitch_bytes: usize ) -> ImageCmd<'c, T>
Sets the row and slice pitch for a read or write operation in bytes.
row_pitch_bytes
: Must be greater than or equal to the region width
in bytes (region[0] * sizeof(T)).
slice_pitch: Must be greater than or equal to
row_pitch` * region
height in bytes (region[1] * sizeof(T)).
Only needs to be set if region has been set to something other than the (default) image buffer size.
sourcepub fn ewait<'e, Ewl>(self, ewait: Ewl) -> ImageCmd<'c, T>where
Ewl: Into<ClWaitListPtrEnum<'e>>,
'e: 'c,
pub fn ewait<'e, Ewl>(self, ewait: Ewl) -> ImageCmd<'c, T>where
Ewl: Into<ClWaitListPtrEnum<'e>>,
'e: 'c,
Specifies an event or list of events to wait on before the command will run.
When events generated using the ::enew
method of other,
previously enqueued commands are passed here (either individually or
as part of an EventList
), this command will not execute until
those commands have completed.
Using events can compliment the use of queues to order commands by creating temporal dependencies between them (where commands in one queue must wait for the completion of commands in another). Events can also supplant queues altogether when, for example, using out-of-order queues.
§Example
// Create an event list:
let mut event_list = EventList::new();
// Enqueue a kernel on `queue_1`, creating an event representing the kernel
// command in our list:
kernel.cmd().queue(&queue_1).enew(&mut event_list).enq()?;
// Read from a buffer using `queue_2`, ensuring the read does not begin until
// after the kernel command has completed:
buffer.read(rwvec.clone()).queue(&queue_2).ewait(&event_list).enq_async()?;
sourcepub fn enew<'e, En>(self, enew: En) -> ImageCmd<'c, T>where
En: Into<ClNullEventPtrEnum<'e>>,
'e: 'c,
pub fn enew<'e, En>(self, enew: En) -> ImageCmd<'c, T>where
En: Into<ClNullEventPtrEnum<'e>>,
'e: 'c,
Specifies the destination to store a new, optionally created event associated with this command.
The destination can be a mutable reference to an empty event (created
using Event::empty
) or a mutable reference to an event list.
After this command is enqueued, the event in the destination can be
passed to the ::ewait
method of another command. Doing so will cause
the other command to wait until this command has completed before
executing.
Using events can compliment the use of queues to order commands by creating temporal dependencies between them (where commands in one queue must wait for the completion of commands in another). Events can also supplant queues altogether when, for example, using out-of-order queues.
§Example
// Create an event list:
let mut event = Event::empty();
// Enqueue a kernel on `queue_1`, creating an event representing the kernel
// command in our list:
kernel.cmd().queue(&queue_1).enew(&mut event).enq()?;
// Read from a buffer using `queue_2`, ensuring the read does not begin until
// after the kernel command has completed:
buffer.read(rwvec.clone()).queue(&queue_2).ewait(&event).enq_async()?;