# Struct ocl::Buffer [−] [src]

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

#### `pub fn builder<'a>() -> BufferBuilder<'a, T>`
[src]

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

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

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

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

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

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

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

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

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

#### `pub fn len(&self) -> usize`
[src]

Returns the length of the buffer.

#### `pub fn is_sub_buffer(&self) -> bool`
[src]

Returns true if this is a sub-buffer.

#### `pub fn mem_info(&self, info_kind: MemInfo) -> OclCoreResult<MemInfoResult>`
[src]

Returns info about the underlying memory object.

#### `pub fn set_default_queue<'a>(&'a mut self, queue: Queue) -> &'a mut Buffer<T>`
[src]

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:

ⓘThis example is not tested

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

With a default queue:

ⓘThis example is not tested

    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.:

ⓘThis example is not tested

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

#### `pub fn default_queue(&self) -> Option<&Queue>`
[src]

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

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

#### `pub fn flags(&self) -> OclResult<MemFlags>`
[src]

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

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

Returns a pointer, do not store it.

## Trait Implementations

### `impl<T: Debug + OclPrm> Debug for Buffer<T>`
[src]

#### `fn fmt(&self, __arg_0: &mut Formatter) -> Result`
[src]

Formats the value using the given formatter. Read more

### `impl<T: Clone + OclPrm> Clone for Buffer<T>`
[src]

#### `fn clone(&self) -> Buffer<T>`
[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`
1.0.0
[src]

Performs copy-assignment from `source`. Read more

### `impl<T: OclPrm> Deref for Buffer<T>`
[src]

#### `type Target = MemCore`

The resulting type after dereferencing.

#### `fn deref(&self) -> &MemCore`
[src]

Dereferences the value.

### `impl<T: OclPrm> DerefMut for Buffer<T>`
[src]

#### `fn deref_mut(&mut self) -> &mut MemCore`
[src]

Mutably dereferences the value.

### `impl<T: OclPrm> AsRef<MemCore> for Buffer<T>`
[src]

#### `fn as_ref(&self) -> &MemCore`
[src]

Performs the conversion.

### `impl<T: OclPrm> AsMut<MemCore> for Buffer<T>`
[src]

#### `fn as_mut(&mut self) -> &mut MemCore`
[src]

Performs the conversion.

### `impl<T: OclPrm> AsMem<T> for Buffer<T>`
[src]

#### `fn as_mem(&self) -> &MemCore`
[src]

### `impl<T: OclPrm> Display for Buffer<T>`
[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`
[src]

Formats the value using the given formatter. Read more

### `impl<'a, T> MemCmdRw for Buffer<T> where
T: OclPrm,`
[src]

### `impl<'a, T> MemCmdRw for &'a Buffer<T> where
T: OclPrm,`
[src]

### `impl<'a, T> MemCmdRw for &'a mut Buffer<T> where
T: OclPrm,`
[src]

### `impl<'a, T> MemCmdAll for Buffer<T> where
T: OclPrm,`
[src]

### `impl<'a, T> MemCmdAll for &'a Buffer<T> where
T: OclPrm,`
[src]

### `impl<'a, T> MemCmdAll for &'a mut Buffer<T> where
T: OclPrm,`
[src]

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