pub struct Buffer<T: OclPrm> { /* private fields */ }Expand description
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.
Implementations§
Source§impl<T: OclPrm> Buffer<T>
impl<T: OclPrm> Buffer<T>
Sourcepub fn builder<'a>() -> BufferBuilder<'a, 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.
Sourcepub unsafe fn new<'e, 'o, Q, D>(
que_ctx: Q,
flags: MemFlags,
len: D,
host_slice: Option<&[T]>,
) -> OclResult<Buffer<T>>
pub unsafe fn new<'e, 'o, Q, D>( que_ctx: Q, flags: MemFlags, len: D, host_slice: Option<&[T]>, ) -> OclResult<Buffer<T>>
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.
Sourcepub 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>>,
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
Remember to specify the GL context when creating the CL context,
using .properties(ocl_interop::get_properties_list())
Don’t forget to .cmd().gl_acquire().enq() before using it and
.cmd().gl_release().enq() after.
See the BufferCmd docs
for more info.
Sourcepub fn from_d3d11_buffer<'o, Q>(
que_ctx: Q,
flags_opt: Option<MemFlags>,
object: cl_id3d11_buffer,
) -> OclResult<Buffer<T>>where
Q: Into<QueCtx<'o>>,
pub fn from_d3d11_buffer<'o, Q>(
que_ctx: Q,
flags_opt: Option<MemFlags>,
object: cl_id3d11_buffer,
) -> OclResult<Buffer<T>>where
Q: Into<QueCtx<'o>>,
Creates a buffer linked to a previously created D3D11 buffer object.
[UNTESTED]
§Errors
Remember to specify the D3D11 device when creating the CL context,
using .properties() and .set_property_value(ContextPropertyValue::D3d11DeviceKhr(<pointer to ID3D11Device>))
Don’t forget to .cmd().d3d11_acquire().enq() before using it and
.cmd().d3d11_release().enq() after.
See the BufferCmd docs
for more info.
Sourcepub fn cmd<'c>(&'c self) -> BufferCmd<'c, T>
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.
Sourcepub fn read<'c, 'd, R>(&'c self, dst: R) -> BufferReadCmd<'c, 'd, T>where
R: Into<ReadDst<'d, T>>,
'd: 'c,
pub fn read<'c, 'd, R>(&'c self, dst: R) -> BufferReadCmd<'c, 'd, T>where
R: Into<ReadDst<'d, T>>,
'd: 'c,
Returns a command builder used to read data.
Call .enq() to enqueue the command.
See the command builder documentation for more details.
Sourcepub fn write<'c, 'd, W>(&'c self, src: W) -> BufferWriteCmd<'c, 'd, T>
pub fn write<'c, 'd, W>(&'c self, src: W) -> BufferWriteCmd<'c, 'd, T>
Returns a command builder used to write data.
Call .enq() to enqueue the command.
See the command builder documentation for more details.
Sourcepub fn map<'c>(&'c self) -> BufferMapCmd<'c, T>
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.
Sourcepub fn copy<'c, M>(
&'c self,
dst_buffer: &'c M,
dst_offset: Option<usize>,
len: Option<usize>,
) -> BufferCmd<'c, T>where
M: AsMem<T>,
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.
Sourcepub fn offset(&self) -> Option<usize>
pub fn offset(&self) -> Option<usize>
Returns the offset of the sub-buffer within its buffer if this is a sub-buffer.
Sourcepub fn is_sub_buffer(&self) -> bool
pub fn is_sub_buffer(&self) -> bool
Returns true if this is a sub-buffer.
Sourcepub fn mem_info(&self, info_kind: MemInfo) -> OclCoreResult<MemInfoResult>
pub fn mem_info(&self, info_kind: MemInfo) -> OclCoreResult<MemInfoResult>
Returns info about the underlying memory object.
Sourcepub fn set_default_queue<'a>(&'a mut self, queue: Queue) -> &'a mut Buffer<T>
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(....)...;Sourcepub fn default_queue(&self) -> Option<&Queue>
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.
Sourcepub fn as_core(&self) -> &MemCore
pub fn as_core(&self) -> &MemCore
Returns a reference to the core pointer wrapper, usable by functions in
the core module.
Sourcepub fn flags(&self) -> OclResult<MemFlags>
pub fn flags(&self) -> OclResult<MemFlags>
Returns the memory flags used during the creation of this buffer.
Sourcepub fn create_sub_buffer<Do, Dl>(
&self,
flags_opt: Option<MemFlags>,
offset: Do,
len: Dl,
) -> OclResult<Buffer<T>>
pub fn create_sub_buffer<Do, Dl>( &self, flags_opt: Option<MemFlags>, offset: Do, len: Dl, ) -> OclResult<Buffer<T>>
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