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

    #[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

ⓘThis example is not tested

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

[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,`
[src]

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

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,`
[src]

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,`
[src]

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

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>`
[src]

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>`
[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 origin<D>(self, origin: D) -> ImageCmd<'c, T> where
D: Into<SpatialDims>,`
[src]

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>,`
[src]

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>`
[src]

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 to`row_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>>,`
[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) -> ImageCmd<'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) -> OclCoreResult<()>`
[src]

Enqueues this command.

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

# 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`)