Struct 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>

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

Returns a new buffer builder.

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

fn new<'e, 'o, D, Q, En>(
    que_ctx: Q,
    flags_opt: Option<MemFlags>,
    dims: D,
    host_data: Option<&[T]>,
    fill_val: Option<(T, Option<En>)>
) -> OclResult<Buffer<T>> where
    D: Into<SpatialDims>,
    Q: Into<QueCtx<'o>>,
    En: Into<ClNullEventPtrEnum<'e>>, 

Creates a new buffer. [NOTE]: Use ::builder instead now.

See the BufferBuilder and SDK documentation for argument details.

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

fn from_gl_buffer<'o, D, Q>(
    que_ctx: Q,
    flags_opt: Option<MemFlags>,
    dims: D,
    gl_object: cl_GLuint
) -> OclResult<Buffer<T>> where
    D: Into<SpatialDims>,
    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.

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.

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.

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.

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

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

Call .enq() to enqueue the command.

See the command builder documentation for more details.

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.

fn origin(&self) -> Option<&SpatialDims>

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

fn dims(&self) -> &SpatialDims

Returns the dimensions of the buffer.

fn len(&self) -> usize

Returns the length of the buffer.

Equivalent to ::dims().to_len().

fn is_sub_buffer(&self) -> bool

Returns true if this is a sub-buffer.

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

Returns info about the underlying memory object.

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

Changes the default queue used by this Buffer for reads and writes, etc.

Returns a mutable reference for optional chaining i.e.:

Example

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

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

Returns a reference to the default queue.

fn core_as_ref(&self) -> &MemCore

Deprecated since 0.13.0

: Use ::core instead.

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

fn core(&self) -> &MemCore

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

fn flags(&self) -> MemFlags

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

Saves the cost of having to look them up using ::mem_info.

fn create_sub_buffer<Do, Ds>(
    &self,
    flags_opt: Option<MemFlags>,
    origin: Do,
    dims: Ds
) -> OclResult<Buffer<T>> where
    Do: Into<SpatialDims>,
    Ds: Into<SpatialDims>, 

Creates a new sub-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

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

origin 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()] struct.MemFlags.html#method.read_write

Methods from Deref<Target = MemCore>

fn as_ptr(&self) -> *mut c_void

Returns a pointer, do not store it.

Trait Implementations

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

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

Formats the value using the given formatter.

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> Deref for Buffer<T>

type Target = MemCore

The resulting type after dereferencing

fn deref(&self) -> &MemCore

The method called to dereference a value

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

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

The method called to mutably dereference a value

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

fn as_ref(&self) -> &MemCore

Performs the conversion.

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

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

Performs the conversion.

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

fn as_mem(&self) -> &MemCore

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

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

Formats the value using the given formatter.

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,