pub struct BufferSlice<'a> {
pub(crate) buffer: &'a Buffer,
pub(crate) offset: BufferAddress,
pub(crate) size: BufferSize,
}
Expand description
A slice of a Buffer
, to be mapped, used for vertex or index data, or the like.
You can create a BufferSlice
by calling Buffer::slice
:
let slice = buffer.slice(10..20);
This returns a slice referring to the second ten bytes of buffer
. To get a
slice of the entire Buffer
:
let whole_buffer_slice = buffer.slice(..);
You can pass buffer slices to methods like RenderPass::set_vertex_buffer
and RenderPass::set_index_buffer
to indicate which portion of the buffer
a draw call should consult. You can also convert it to a BufferBinding
with .into()
.
To access the slice’s contents on the CPU, you must first map the buffer,
and then call BufferSlice::get_mapped_range
or
BufferSlice::get_mapped_range_mut
to obtain a view of the slice’s
contents. See the documentation on mapping for more details,
including example code.
Unlike a Rust shared slice &[T]
, whose existence guarantees that
nobody else is modifying the T
values to which it refers, a
BufferSlice
doesn’t guarantee that the buffer’s contents aren’t
changing. You can still record and submit commands operating on the
buffer while holding a BufferSlice
. A BufferSlice
simply
represents a certain range of the buffer’s bytes.
The BufferSlice
type is unique to the Rust API of wgpu
. In the WebGPU
specification, an offset and size are specified as arguments to each call
working with the Buffer
, instead.
Fields§
§buffer: &'a Buffer
§offset: BufferAddress
§size: BufferSize
Implementations§
Source§impl<'a> BufferSlice<'a>
impl<'a> BufferSlice<'a>
Sourcepub fn slice<S: RangeBounds<BufferAddress>>(&self, bounds: S) -> BufferSlice<'a>
pub fn slice<S: RangeBounds<BufferAddress>>(&self, bounds: S) -> BufferSlice<'a>
Return another BufferSlice
referring to the portion of self
’s contents
indicated by bounds
.
The range
argument can be half or fully unbounded: for example,
buffer.slice(..)
refers to the entire buffer, and buffer.slice(n..)
refers to the portion starting at the n
th byte and extending to the
end of the buffer.
§Panics
- If
bounds
is outside of the bounds ofself
. - If
bounds
has a length less than 1.
Sourcepub fn map_async(
&self,
mode: MapMode,
callback: impl FnOnce(Result<(), BufferAsyncError>) + WasmNotSend + 'static,
)
pub fn map_async( &self, mode: MapMode, callback: impl FnOnce(Result<(), BufferAsyncError>) + WasmNotSend + 'static, )
Map the buffer to host (CPU) memory, making it available for reading or writing via
get_mapped_range()
. The buffer becomes accessible once the
callback
is invoked with Ok
.
Use this when you want to map the buffer immediately. If you need to submit GPU work that
uses the buffer before mapping it, use map_buffer_on_submit
on
CommandEncoder
, CommandBuffer
, RenderPass
, or
ComputePass
to schedule the mapping after submission. This avoids extra calls to
Buffer::map_async()
or BufferSlice::map_async()
and lets you initiate mapping from a
more convenient place.
For the callback to run, either queue.submit(..)
, instance.poll_all(..)
,
or device.poll(..)
must be called elsewhere in the runtime, possibly integrated into
an event loop or run on a separate thread.
The callback runs on the thread that first calls one of the above functions after the GPU work completes. There are no restrictions on the code you can run in the callback; however, on native the polling call will not return until the callback finishes, so keep callbacks short (set flags, send messages, etc.).
While a buffer is mapped, it cannot be used by other commands; at any time, either the GPU or the CPU has exclusive access to the buffer’s contents.
This can also be performed using Buffer::map_async()
.
§Panics
- If the buffer is already mapped.
- If the buffer’s
BufferUsages
do not allow the requestedMapMode
. - If the endpoints of this slice are not aligned to
MAP_ALIGNMENT
within the buffer.
Sourcepub fn get_mapped_range(&self) -> BufferView
pub fn get_mapped_range(&self) -> BufferView
Gain read-only access to the bytes of a mapped Buffer
.
Returns a BufferView
referring to the buffer range represented by
self
. See the documentation for BufferView
for details.
Multiple views may be obtained and used simultaneously as long as they are from non-overlapping slices.
This can also be performed using Buffer::get_mapped_range()
.
§Panics
- If the endpoints of this slice are not aligned to
MAP_ALIGNMENT
within the buffer. - If the buffer to which
self
refers is not currently mapped. - If you try to create a view which overlaps an existing
BufferViewMut
.
Sourcepub fn get_mapped_range_mut(&self) -> BufferViewMut
pub fn get_mapped_range_mut(&self) -> BufferViewMut
Gain write access to the bytes of a mapped Buffer
.
Returns a BufferViewMut
referring to the buffer range represented by
self
. See the documentation for BufferViewMut
for more details.
Multiple views may be obtained and used simultaneously as long as they are from non-overlapping slices.
This can also be performed using Buffer::get_mapped_range_mut()
.
§Panics
- If the endpoints of this slice are not aligned to
MAP_ALIGNMENT
. - If the buffer to which
self
refers is not currently mapped. - If you try to create a view which overlaps an existing
BufferView
orBufferViewMut
.
Sourcepub fn buffer(&self) -> &'a Buffer
pub fn buffer(&self) -> &'a Buffer
Returns the buffer this is a slice of.
You should usually not need to call this, and if you received the buffer from code you do not control, you should refrain from accessing the buffer outside the bounds of the slice. Nevertheless, it’s possible to get this access, so this method makes it simple.
Sourcepub fn offset(&self) -> BufferAddress
pub fn offset(&self) -> BufferAddress
Returns the offset in Self::buffer()
this slice starts at.
Sourcepub fn size(&self) -> BufferSize
pub fn size(&self) -> BufferSize
Returns the size of this slice.
Trait Implementations§
Source§impl<'a> Clone for BufferSlice<'a>
impl<'a> Clone for BufferSlice<'a>
Source§fn clone(&self) -> BufferSlice<'a>
fn clone(&self) -> BufferSlice<'a>
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreSource§impl<'a> Debug for BufferSlice<'a>
impl<'a> Debug for BufferSlice<'a>
Source§impl<'a> From<BufferSlice<'a>> for BindingResource<'a>
impl<'a> From<BufferSlice<'a>> for BindingResource<'a>
Source§fn from(value: BufferSlice<'a>) -> Self
fn from(value: BufferSlice<'a>) -> Self
Convert a BufferSlice
to an equivalent BindingResource::Buffer
,
provided that it will be used without a dynamic offset.
Source§impl<'a> From<BufferSlice<'a>> for BufferBinding<'a>
impl<'a> From<BufferSlice<'a>> for BufferBinding<'a>
Source§fn from(value: BufferSlice<'a>) -> Self
fn from(value: BufferSlice<'a>) -> Self
Convert a BufferSlice
to an equivalent BufferBinding
,
provided that it will be used without a dynamic offset.