Struct fil_ocl::Buffer

pub struct Buffer<T: OclPrm> { /* fields omitted */ }

A chunk of memory physically located on a device, such as a GPU.

Data is stored remotely in a memory buffer on the device associated with queue.

Methods

impl<T: OclPrm> Buffer<T>

pub fn builder<'a>() -> BufferBuilder<'a, T>

Returns a new buffer builder.

This is the preferred (and forward compatible) way to create a buffer.

pub unsafe fn new<'e, 'o, Q, D>(
    que_ctx: Q,
    flags: MemFlags,
    len: D,
    host_slice: Option<&[T]>
) -> OclResult<Buffer<T>> where
    Q: Into<QueCtx<'o>>,
    D: Into<SpatialDims>, 

Creates a new buffer.

[UNSTABLE]: Arguments may still be in a state of flux. It is recommended to use ::builder instead.

See the BufferBuilder and SDK documentation for argument details.

Safety

Incorrectly using flags and/or host_slice is unsafe.

pub fn from_gl_buffer<'o, Q>(
    que_ctx: Q,
    flags_opt: Option<MemFlags>,
    gl_object: cl_GLuint
) -> OclResult<Buffer<T>> where
    Q: Into<QueCtx<'o>>, 

Creates a buffer linked to a previously created OpenGL buffer object.

[UNTESTED]

Errors

Don't forget to .cmd().gl_acquire().enq() before using it and .cmd().gl_release().enq() after.

See the BufferCmd docs for more info.

pub fn cmd<'c>(&'c self) -> BufferCmd<'c, T>

Returns a command builder used to read, write, copy, etc.

Call .enq() to enqueue the command.

See the command builder documentation for more details.

pub fn read<'c, 'd, R>(&'c self, dst: R) -> BufferReadCmd<'c, 'd, T> where
    'd: 'c,
    R: Into<ReadDst<'d, T>>, 

Returns a command builder used to read data.

Call .enq() to enqueue the command.

See the command builder documentation for more details.

pub fn write<'c, 'd, W>(&'c self, src: W) -> BufferWriteCmd<'c, 'd, T> where
    'd: 'c,
    W: Into<WriteSrc<'d, T>>, 

Returns a command builder used to write data.

Call .enq() to enqueue the command.

See the command builder documentation for more details.

pub fn map<'c>(&'c self) -> BufferMapCmd<'c, T>

Returns a command builder used to map data for reading or writing.

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.

Call .enq() to enqueue the command.

More Information

See the command builder documentation or official SDK for more details.

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

Specifies that this command will be a copy operation.

Call .enq() to enqueue the command.

See the command builder documentation for more details.

pub fn offset(&self) -> Option<usize>

Returns the offset of the sub-buffer within its buffer if this is a sub-buffer.

pub fn len(&self) -> usize

Returns the length of the buffer.

pub fn is_sub_buffer(&self) -> bool

Returns true if this is a sub-buffer.

pub fn mem_info(&self, info_kind: MemInfo) -> OclCoreResult<MemInfoResult>

Returns info about the underlying memory object.

pub fn set_default_queue<'a>(&'a mut self, queue: Queue) -> &'a mut Buffer<T>

Changes the default queue used by this buffer for all subsequent command enqueue operations (reads, writes, etc.).

The default queue is the queue which will be used when enqueuing commands if no queue is specified.

Without a default queue:

buffer.read(data).queue(&queue).enq()?;

With a default queue:

buffer.set_default_queue(queue.clone());
buffer.read(data).enq()?;

The default queue can also be set when creating a buffer by using the BufferBuilder::queue method.

This method returns a mutable reference for optional chaining i.e.:

buffer.set_default_queue(queue).read(....)...;

pub fn default_queue(&self) -> Option<&Queue>

Returns a reference to the default queue.

The default queue is the queue which will be used when enqueuing commands if no queue is specified.

pub fn as_core(&self) -> &MemCore

Returns a reference to the core pointer wrapper, usable by functions in the core module.

pub fn flags(&self) -> OclResult<MemFlags>

Returns the memory flags used during the creation of this buffer.

pub fn create_sub_buffer<Do, Dl>(
    &self,
    flags_opt: Option<MemFlags>,
    offset: Do,
    len: Dl
) -> OclResult<Buffer<T>> where
    Do: Into<SpatialDims>,
    Dl: Into<SpatialDims>, 

Creates a new sub-buffer from a region of this buffer.

Flags (adapted from SDK)

[NOTE]: Flags described below can be found in the ocl::flags module or within the MemFlags type (example: [MemFlags::new().read_write()]).

flags: A bit-field that is used to specify allocation and usage information about the sub-buffer memory object being created and is described in the table below. If the MEM_READ_WRITE, MEM_READ_ONLY or MEM_WRITE_ONLY values are not specified in flags, they are inherited from the corresponding memory access qualifers associated with buffer. The MEM_USE_HOST_PTR, MEM_ALLOC_HOST_PTR and MEM_COPY_HOST_PTR values cannot be specified in flags but are inherited from the corresponding memory access qualifiers associated with buffer. If MEM_COPY_HOST_PTR is specified in the memory access qualifier values associated with buffer it does not imply any additional copies when the sub-buffer is created from buffer. If the MEM_HOST_WRITE_ONLY, MEM_HOST_READ_ONLY or MEM_HOST_NO_ACCESS values are not specified in flags, they are inherited from the corresponding memory access qualifiers associated with buffer.

Offset and Dimensions

offset and len set up the region of the sub-buffer within the original buffer and must not fall beyond the boundaries of it.

offset must be a multiple of the DeviceInfo::MemBaseAddrAlign otherwise you will get a CL_MISALIGNED_SUB_BUFFER_OFFSET error. To determine, use Device::mem_base_addr_align for the device associated with the queue which will be use with this sub-buffer.

[MemFlags::new().read_write()] flags/struct.MemFlags.html#method.read_write

Methods from Deref<Target = MemCore>

pub fn as_ptr(&self) -> *mut c_void

Returns a pointer, do not store it.

Trait Implementations

impl<T: OclPrm> AsRef<Mem> for Buffer<T>

fn as_ref(&self) -> &MemCore

Performs the conversion.

impl<T: OclPrm> AsMut<Mem> for Buffer<T>

fn as_mut(&mut self) -> &mut MemCore

Performs the conversion.

impl<T: Clone + OclPrm> Clone for Buffer<T>

fn clone(&self) -> Buffer<T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: OclPrm> Display for Buffer<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: Debug + OclPrm> Debug for Buffer<T>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: OclPrm> Deref for Buffer<T>

type Target = MemCore

The resulting type after dereferencing.

fn deref(&self) -> &MemCore

Dereferences the value.

impl<T: OclPrm> DerefMut for Buffer<T>

fn deref_mut(&mut self) -> &mut MemCore

Mutably dereferences the value.

impl<T: OclPrm> AsMem<T> for Buffer<T>

fn as_mem(&self) -> &MemCore

impl<'a, T> MemCmdRw for Buffer<T> where
    T: OclPrm, 

impl<'a, T> MemCmdRw for &'a Buffer<T> where
    T: OclPrm, 

impl<'a, T> MemCmdRw for &'a mut Buffer<T> where
    T: OclPrm, 

impl<'a, T> MemCmdAll for Buffer<T> where
    T: OclPrm, 

impl<'a, T> MemCmdAll for &'a Buffer<T> where
    T: OclPrm, 

impl<'a, T> MemCmdAll for &'a mut Buffer<T> where
    T: OclPrm,