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.

fn new(
    queue: Option<&'c Queue>,
    obj_core: &'c MemCore,
    dims: [usize; 3]
) -> ImageCmd<'c, T>

Returns a new image command builder associated with with the memory object obj_core along with a default queue and to_len (the length of the device side image).

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.

unsafe fn read_async(self, dst_data: &'c mut [T]) -> ImageCmd<'c, T>

Deprecated since 0.13.0

: Use '::read' with '::block(false)' for unsafe asynchronous reads.

Specifies that this command will be a non-blocking, asynchronous read operation. [DEPRICATED]

Sets the block mode to false automatically but it may still be freely toggled back. If set back to true this method call becomes equivalent to calling ::read.

Safety

Caller must ensure that the container referred to by dst_data lives until the call completes.

Panics

The command operation kind must not have already been specified

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.

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.

Panics

The command operation kind must not have already been specified

More Information

See SDK docs for more details.

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

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

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

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

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

fn queue(self, queue: &'c Queue) -> ImageCmd<'c, T>

Specifies a queue to use for this call only.

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.

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.

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

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.

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

Specifies a list of events to wait on before the command will run.

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

Specifies a list of events to wait on before the command will run or resets it to None.

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

Specifies the destination for a new, optionally created event associated with this command.

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

Specifies a destination for a new, optionally created event associated with this command or resets it to None.

fn enq(self) -> OclResult<()>

Enqueues this command.

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