Struct ocl::builders::BufferCmd

pub struct BufferCmd<'b, T: 'b + OclPrm> { /* fields omitted */ }

A buffer command builder used to enqueue reads, writes, fills, and copies.

Create one using Buffer::cmd or with shortcut methods such as Buffer::read and Buffer::write.

Examples

// Copies one buffer to another:
src_buffer.cmd().copy(&dst_buffer, 0, dst_buffer.len()).enq().unwrap();

// Writes from a vector to an buffer, waiting on an event:
buffer.write(&src_vec).ewait(&event).enq().unwrap();

// Reads from a buffer into a vector, waiting on an event list and
// filling a new empty event:
buffer.read(&dst_vec).ewait(&event_list).enew(&empty_event).enq().unwrap();

// Reads without blocking:
buffer.cmd().read_async(&dst_vec).enew(&empty_event).enq().unwrap();

Methods

impl<'b, T: 'b + OclPrm> BufferCmd<'b, T>

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

fn new(queue: &'b Queue,
       obj_core: &'b MemCore,
       mem_len: usize)
       -> BufferCmd<'b, T>

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

fn queue(self, queue: &'b Queue) -> BufferCmd<'b, T>

Specifies a queue to use for this call only.

fn block(self, block: bool) -> BufferCmd<'b, T>

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 offset(self, offset: usize) -> BufferCmd<'b, T>

Sets the linear offset for an operation.

Panics

The 'shape' may not have already been set to rectangular by the ::rect function.

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

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 [T]) -> BufferCmd<'b, T>

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 [T]) -> BufferCmd<'b, T>

Specifies that this command will be a write operation.

Panics

The command operation kind must not have already been specified

fn copy(self,
        dst_buffer: &'b Buffer<T>,
        dst_offset: usize,
        len: usize)
        -> BufferCmd<'b, T>

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_offset and len must be zero.

Panics

The command operation kind must not have already been specified

fn copy_to_image(self,
                 image: &'b MemCore,
                 dst_origin: [usize; 3],
                 region: [usize; 3])
                 -> BufferCmd<'b, T>

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) -> BufferCmd<'b, 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) -> BufferCmd<'b, 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, pattern: T, len: Option<usize>) -> BufferCmd<'b, T>

Specifies that this command will be a fill.

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

pattern is the vector or scalar value to repeat contiguously. len is the overall size expressed in units of sizeof(T) If len is None, the pattern will fill the entire buffer, otherwise, len must be divisible by sizeof(pattern).

As an example if you want to fill the first 100 cl_float4 sized elements of a buffer, pattern would be a cl_float4 and len would be 400.

Panics

The command operation kind must not have already been specified

fn rect(self,
        src_origin: [usize; 3],
        dst_origin: [usize; 3],
        region: [usize; 3],
        src_row_pitch: usize,
        src_slc_pitch: usize,
        dst_row_pitch: usize,
        dst_slc_pitch: usize)
        -> BufferCmd<'b, T>

Specifies that this will be a rectangularly shaped operation (the default being linear).

Only valid for 'read', 'write', and 'copy' modes. Will error if used with 'fill' or 'copy to image'.

fn ewait(self, ewait: &'b ClWaitList) -> BufferCmd<'b, T>

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

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

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) -> BufferCmd<'b, T>

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

fn enew_opt(self, enew: Option<&'b mut ClEventPtrNew>) -> BufferCmd<'b, T>

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.