# Struct ocl::builders::BufferCmd [−] [src]

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

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

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

## Examples

ⓘThis example is not tested

    // Copies one buffer to another:
    src_buffer.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(&mut empty_event).enq().unwrap();

    // Reads without blocking:
    buffer.read(&dst_vec).block(false).enew(&mut empty_event).enq().unwrap();

## Methods

### `impl<'c, T> BufferCmd<'c, T> where
T: 'c + OclPrm,`
[src]

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

#### `pub fn read<'d, R>(self, dst_data: R) -> BufferReadCmd<'c, 'd, T> where
R: Into<ReadDst<'d, T>>,`
[src]

Specifies that this command will be a read operation.

After calling this method, the blocking state of this command will be unchanged.

### Panics

The command operation kind must not have already been specified.

### More Information

See SDK docs for more details.

#### `pub fn write<'d, W>(self, src_data: W) -> BufferWriteCmd<'c, 'd, T> where
W: Into<WriteSrc<'d, T>>,`
[src]

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 fn map(self) -> BufferMapCmd<'c, T>`
[src]

Specifies that this command will be a map operation.

Enqueuing a map command will map a region of a buffer into the host address space and return a `MemMap` or `FutureMemMap`, allowing access to this mapped region. Accessing memory via a `MemMap` is exactly like using a slice.

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.

#### `pub fn copy<'d, M>(
self,
dst_buffer: &'d M,
dst_offset: Option<usize>,
len: Option<usize>
) -> BufferCmd<'c, T> where
'd: 'c,
M: AsMem<T>,`
[src]

Specifies that this command will be a copy operation.

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

`dst_offset` defaults to `0`, `len` defaults to the full length of the source buffer.

## Errors

If this is a rectangular copy, `dst_offset` and `len` must be None.

## Panics

The command operation kind must not have already been specified

### More Information

See SDK docs for more details.

#### `pub fn copy_to_image<'d>(
self,
image: &'d MemCore,
dst_origin: [usize; 3],
region: [usize; 3]
) -> BufferCmd<'c, T> where
'd: 'c,`
[src]

Specifies that this command will be a copy to image operation.

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) -> BufferCmd<'c, T>`
[src]

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) -> BufferCmd<'c, T>`
[src]

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, pattern: T, len: Option<usize>) -> BufferCmd<'c, T>`
[src]

Specifies that this command will be a fill operation.

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

#### `pub fn queue(self, queue: &'c Queue) -> BufferCmd<'c, T>`
[src]

Specifies a queue to use for this call only.

Overrides the buffer'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) -> BufferCmd<'c, T>`
[src]

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 offset(self, offset: usize) -> BufferCmd<'c, T>`
[src]

Sets the linear offset for an operation.

## Panics

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

#### `pub fn rect(
self,
src_origin: [usize; 3],
dst_origin: [usize; 3],
region: [usize; 3],
src_row_pitch_bytes: usize,
src_slc_pitch_bytes: usize,
dst_row_pitch_bytes: usize,
dst_slc_pitch_bytes: usize
) -> BufferCmd<'c, T>`
[src]

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

Row and slice pitches must all be expressed in bytes.

Only valid for 'read', 'write', and 'copy' modes. Will error if used with any other mode.

#### `pub fn ewait<'e, Ewl>(self, ewait: Ewl) -> BufferCmd<'c, T> where
'e: 'c,
Ewl: Into<ClWaitListPtrEnum<'e>>,`
[src]

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

ⓘThis example is not tested

    // 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) -> BufferCmd<'c, T> where
'e: 'c,
En: Into<ClNullEventPtrEnum<'e>>,`
[src]

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

ⓘThis example is not tested

    // 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) -> OclResult<()>`
[src]

Enqueues this command.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)