Struct ocl::builders::ImageCmd

pub struct ImageCmd<'b, E: 'b + OclPrm> { /* 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<'b, E: 'b + OclPrm> ImageCmd<'b, E>

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

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

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 queue(self, queue: &'b Queue) -> ImageCmd<'b, E>

Specifies a queue to use for this call only.

fn block(self, block: bool) -> ImageCmd<'b, E>

Specifies whether or not to block thread until completion.

Ignored if this is a copy, fill, or copy to image operation.

Panics

Will panic if ::read has already been called. Use ::read_async (unsafe) for a non-blocking read operation.

fn origin(self, origin: [usize; 3]) -> ImageCmd<'b, E>

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(self, region: [usize; 3]) -> ImageCmd<'b, E>

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(self, row_pitch: usize, slc_pitch: usize) -> ImageCmd<'b, E>

[UNSTABLE] Sets the row and slice pitch for a read or write operation.

row_pitch: Must be greater than or equal to the region width (region[0]).

slice_pitch: Must be greater than or equal torow_pitch` * region height (region[1]).

Only needs to be set if region has been set to something other than the (default) image buffer size.

Stability

Probably will be depricated unless I can think of a reason why you'd set the pitches to something other than the image dims.

[FIXME]: Remove this or figure out if it's necessary at all.

fn read(self, dst_data: &'b mut [E]) -> ImageCmd<'b, E>

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.

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

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

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(self, src_data: &'b [E]) -> ImageCmd<'b, E>

Specifies that this command will be a write operation.

Panics

The command operation kind must not have already been specified

fn copy(self,
        dst_image: &'b Image<E>,
        dst_origin: [usize; 3])
        -> ImageCmd<'b, E>

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(self,
                  buffer: &'b MemCore,
                  dst_origin: usize)
                  -> ImageCmd<'b, E>

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<'b, E>

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<'b, E>

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: E) -> ImageCmd<'b, E>

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 ewait(self, ewait: &'b ClWaitList) -> ImageCmd<'b, E>

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

fn ewait_opt(self, ewait: Option<&'b ClWaitList>) -> ImageCmd<'b, E>

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

fn enew(self, enew: &'b mut ClEventPtrNew) -> ImageCmd<'b, E>

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

fn enew_opt(self, enew: Option<&'b mut ClEventPtrNew>) -> ImageCmd<'b, 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.