Struct BufferBinding 

pub struct BufferBinding<'a, B: DynBuffer + ?Sized, S> {
    pub(crate) buffer: &'a B,
    pub offset: BufferAddress,
    pub size: S,
}

A region of a buffer made visible to shaders via a BindGroup.

Construction

The recommended way to construct a BufferBinding is using the binding method on a wgpu-core Buffer, which will validate the binding size against the buffer size. A new_unchecked constructor is also provided for cases where direct construction is necessary.

Accessible region

wgpu_hal guarantees that shaders compiled with ShaderModuleDescriptor::runtime_checks set to true cannot read or write data via this binding outside the accessible region of a buffer:

• The accessible region starts at offset.

• For Storage bindings, the size of the accessible region is size, which must be a multiple of 4.

• For Uniform bindings, the size of the accessible region is size rounded up to the next multiple of Alignments::uniform_bounds_check_alignment.

Note that this guarantee is stricter than WGSL’s requirements for out-of-bounds accesses, as WGSL allows them to return values from elsewhere in the buffer. But this guarantee is necessary anyway, to permit wgpu-core to avoid clearing uninitialized regions of buffers that will never be read by the application before they are overwritten. This optimization consults bind group buffer binding regions to determine which parts of which buffers shaders might observe. This optimization is only sound if shader access is bounds-checked.

Zero-length bindings

Some platform APIs do not accept zero-length regions; for example, see VUID-VkDescriptorBufferInfo-offset-00340, VUID-VkDescriptorBufferInfo-range-00341, or the documentation for GLES’s glBindBufferRange. For VUID-VkCmdBindVertexBuffers-pOffsets-00626, no size is specified, the binding extends from the offset to the end of the buffer, and the offset must be strictly less than the buffer size.

WebGPU does not allow zero-length storage/uniform buffer bindings, but does allow zero-length vertex/index buffer bindings. wgpu-core ensures that buffers supporting vertex/index usage have 4B of naturally-aligned padding at the end, to enable simulating a zero-length binding at the end of the buffer.

Fields

buffer: &'a B

The buffer being bound.

This is not fully pub to prevent direct construction of BufferBindings, while still allowing public read access to the offset and size properties. Read access to the buffer is available via Self::buffer.

offset: BufferAddress

The offset at which the bound region starts.

This must be less or equal to the size of the buffer.

size: S

The size of the region bound, in bytes.

Implementations

impl<'a, S> BufferBinding<'a, dyn DynBuffer, S>

pub fn expect_downcast<B: DynBuffer>(self) -> BufferBinding<'a, B, S>

impl<'a, B: DynBuffer + ?Sized, S> BufferBinding<'a, B, S>

pub fn new_unchecked(buffer: &'a B, offset: BufferAddress, size: S) -> Self

Construct a BufferBinding with the given contents.

When possible, use the binding method on a wgpu-core Buffer instead of this method. Buffer::binding validates the size of the binding against the size of the buffer.

It is more difficult to provide a validating constructor here, due to not having direct access to the size of a DynBuffer.

SAFETY: The caller is responsible for ensuring that a binding of size bytes starting at offset is contained within the buffer. size may be zero only for vertex/index buffer bindings.

pub fn buffer(&self) -> &'a B

The buffer being bound.

Trait Implementations

impl<B: DynBuffer + ?Sized, S: Copy> Clone for BufferBinding<'_, B, S>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, B: Debug + DynBuffer + ?Sized, S: Debug> Debug for BufferBinding<'a, B, S>

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

Formats the value using the given formatter.