Struct ocl::builders::BufferMapCmd

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

A command builder used to enqueue a map command.

See SDK docs for more details.

Methods

impl<'c, T> BufferMapCmd<'c, T> where
    T: OclPrm, 

fn flags(self, flags: MapFlags) -> BufferMapCmd<'c, T>

Specifies the flags to be used for this map command.

Flags can also be specified using the ::read, ::write, and ::write_invalidate methods instead.

See SDK docs for more details.

fn read(self) -> BufferMapCmd<'c, T>

Specifies that the memory object is being mapped for reading.

Sets the flag to be used for this map command to [CL_]MAP_READ.

This is the fastest way to move data from device to host for many use cases when used with buffers created with the MEM_ALLOC_HOST_PTR or MEM_USE_HOST_PTR flags.

fn write(self) -> BufferMapCmd<'c, T>

Specifies that the memory object is being mapped for writing.

Sets the flag to be used for this map command to [CL_]MAP_WRITE.

This is not the most efficient method of transferring data from host to device due to the memory being synchronized beforehand. Prefer ::write_invalidate unless you need the memory region to be updated (e.g. if you are only writing to particular portions of the data, and will not be overwriting the entire contents, etc.). Use this with buffers created with the MEM_ALLOC_HOST_PTR or MEM_USE_HOST_PTR flags for best performance.

fn write_invalidate(self) -> BufferMapCmd<'c, T>

Specifies that the memory object is being mapped for writing and that the local (host) memory region may contain stale data that must be completely overwritten before unmapping.

Sets the flag to be used for this map command to [CL_]MAP_WRITE_INVALIDATE_REGION.

This option may provide a substantial performance improvement when writing and is the fastest method for moving data in bulk from host to device memory when used with buffers created with the MEM_ALLOC_HOST_PTR or MEM_USE_HOST_PTR flags. Only use this when you will be overwriting the entire contents of the mapped region otherwise you will send stale or junk data to the device.

fn len(self, len: usize) -> BufferMapCmd<'c, T>

Specifies the length of the region to map.

If unspecified the entire buffer will be mapped.

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

Specifies a queue to use for this call only.

fn offset(self, offset: usize) -> BufferMapCmd<'c, T>

Sets the linear offset for an operation.

Panics

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

fn ewait<'e, Ewl>(self, ewait: Ewl) -> BufferMapCmd<'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>) -> BufferMapCmd<'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) -> BufferMapCmd<'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>) -> BufferMapCmd<'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<MemMap<T>>

Enqueues a map command.

fn enq_async(self) -> OclResult<FutureMemMap<T>>

Enqueues a map command and returns a future representing the completion of that map command and containing a reference to the mapped memory.