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

    #[must_use = "builders do nothing unless \'::build\' is called"]
    pub struct BufferBuilder<'a, T> where
        T: OclPrm,  { /* fields omitted */ }

A buffer builder.

## Methods

### `impl<'a, T> BufferBuilder<'a, T> where
T: 'a + OclPrm,`
[src]

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

Returns a new buffer builder.

#### `pub fn context<'o>(self, context: &'o Context) -> BufferBuilder<'a, T> where
'o: 'a,`
[src]

Sets the context with which to associate the buffer.

May not be used in conjunction with `::queue` (use one or the other).

#### `pub fn queue<'b>(self, default_queue: Queue) -> BufferBuilder<'a, T>`
[src]

Specifies the default queue used to be used by the buffer for all 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.read(data).enq()?;

If this is set, the context associated with the `default_queue` will be used when creating the buffer. Attempting to specify the context separately (by calling `::context`) will cause a panic.

#### `pub fn flags<'b>(self, flags: MemFlags) -> BufferBuilder<'a, T>`
[src]

Sets the flags used when creating the buffer.

Defaults to `flags::MEM_READ_WRITE` aka. `MemFlags::new().read_write()` if this is not set. See the SDK Docs for more information about flags. Note that the names of all flags in this library have the `CL_` prefix removed for brevity.

### Panics

Due to its unsafety, setting the `MEM_USE_HOST_PTR`/`MemFlags::new()::use_host_ptr()` flag will cause a panic. Use the `::use_host_slice` method instead.

#### `pub unsafe fn use_host_slice<'d>(
self,
host_slice: &'d [T]
) -> BufferBuilder<'a, T> where
'd: 'a,`
[src]

Specifies a region of host memory to use as storage for the buffer.

OpenCL implementations are allowed to cache the buffer contents pointed to by `host_slice` in device memory. This cached copy can be used when kernels are executed on a device.

The result of OpenCL commands that operate on multiple buffer objects created with the same `host_slice` or overlapping host regions is considered to be undefined

Refer to the description of the alignment rules for `host_slice` for memory objects (buffer and images) created using this method.

Automatically sets the `flags::MEM_USE_HOST_PTR` aka. `MemFlags::new().use_host_ptr()` flag.

### Panics

`::copy_host_slice` or `::use_host_slice` must not have already been called.

### Safety

The caller must ensure that `host_slice` lives until the buffer is destroyed. The caller must also ensure that only one buffer uses `host_slice` and that it is not tampered with inappropriately.

#### `pub fn copy_host_slice<'d>(self, host_slice: &'d [T]) -> BufferBuilder<'a, T> where
'd: 'a,`
[src]

Specifies a region of memory to copy into the buffer upon creation.

Automatically sets the `flags::MEM_COPY_HOST_PTR` aka. `MemFlags::new().copy_host_ptr()` flag.

### Panics

`::copy_host_slice` or `::use_host_slice` must not have already been called.

#### `pub fn len<'b, D>(self, len: D) -> BufferBuilder<'a, T> where
D: Into<SpatialDims>,`
[src]

Sets the length for this buffer.

Note that although sizes in the standard OpenCL API are expressed in bytes, sizes, lengths, and dimensions in this library are always specified in `bytes / sizeof(T)` (like everything else in Rust) unless otherwise noted.

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

Allows the caller to automatically fill the buffer with a value (such as zero) immediately after creation.

Use `::fill_event` to set an event associated with the completion of the fill command if you want it to execute asynchronously (it will otherwise block the calling thread).

Platforms that have trouble with `clEnqueueFillBuffer` such as pocl should not use this option and should handle initializing buffers manually (using a kernel or copy host data flag).

### Examples

- TODO: Provide examples once this stabilizes.

[UNSTABLE]: May be changed or removed.

#### `pub fn fill_event<'b, 'e, En>(self, enew: En) -> BufferBuilder<'a, T> where
'e: 'a,
En: Into<ClNullEventPtrEnum<'e>>,`
[src]

Specifies the (empty) event to use for association with the completion of the fill command.

`enew` specifies an empty event (generally a `&mut Event`) to be associated with the fill command which will be enqueued after creation and just before returning the new buffer. It is up to the caller to ensure that the command has completed before performing any other operations on the buffer. Failure to do so may cause the fill command to run after subsequently queued commands if multiple or out-of-order queues are being used.

Not calling this method at all will cause the fill command to block before returning the new buffer and is the safe option if you don't want to worry about it.

#### `pub fn build(self) -> OclResult<Buffer<T>>`
[src]

Creates a buffer and returns it.

Dimensions and either a context or default queue must be specified before calling `::build`.

## Trait Implementations

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

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

Formats the value using the given formatter. Read more

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