Struct ocl::builders::ImageCmd

#[must_use = "commands do nothing unless enqueued"]
pub struct ImageCmd<'c, T: 'c> { /* fields omitted */ }

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.

Methods

impl<'c, T: 'c + OclPrm> ImageCmd<'c, T>

[UNSTABLE]: All methods still in a state of adjustifulsomeness.

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.

pub fn write<'d>(self, src_data: &'d [T]) -> ImageCmd<'c, T> where
    'd: 'c, 

Specifies that this command will be a write operation.

Panics

The command operation kind must not have already been specified

More Information

See SDK docs for more details.

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.

pub fn copy<'d>(
    self,
    dst_image: &'d Image<T>,
    dst_origin: [usize; 3]
) -> ImageCmd<'c, T> where
    'd: 'c, 

Specifies that this command will be a copy operation.

If .block(..) has been set it will be ignored.

Errors

If this is a rectangular copy, dst_origin and len must be zero.

Panics

The command operation kind must not have already been specified

pub fn copy_to_buffer<'d>(
    self,
    buffer: &'d MemCore,
    dst_origin: 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

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

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

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

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.

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.

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.

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().

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 torow_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.

pub fn ewait<'e, Ewl>(self, ewait: Ewl) -> ImageCmd<'c, T> where
    'e: 'c,
    Ewl: Into<ClWaitListPtrEnum<'e>>, 

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()?;

pub fn enew<'e, En>(self, enew: En) -> ImageCmd<'c, T> where
    'e: 'c,
    En: Into<ClNullEventPtrEnum<'e>>, 

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()?;

pub fn enq(self) -> OclCoreResult<()>

Enqueues this command.

• TODO: FOR COPY, FILL, AND COPYTOBUFFER -- ENSURE PITCHES ARE BOTH UNSET.