Struct BufferBinding

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

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 back ends cannot tolerate zero-length regions; for example, see VUID-VkDescriptorBufferInfo-offset-00340 and VUID-VkDescriptorBufferInfo-range-00341, or the documentation for GLES’s glBindBufferRange. This documentation previously stated that a BufferBinding must have offset strictly less than the size of the buffer, but this restriction was not honored elsewhere in the code, so has been removed. However, it remains the case that some backends do not support zero-length bindings, so additional logic is needed somewhere to handle this properly. See #3170.

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.

offset: BufferAddress

The offset at which the bound region starts.

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

size: Option<BufferSize>

The size of the region bound, in bytes.

If None, the region extends from offset to the end of the buffer. Given the restrictions on offset, this means that the size is always greater than zero.

Implementations

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

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

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

pub fn new_unchecked<S: Into<Option<NonZeroU64>>>( 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.

The S type parameter is a temporary convenience to allow callers to pass a zero size. When the zero-size binding issue is resolved, the argument should just match the type of the member. TODO(https://github.com/gfx-rs/wgpu/issues/3170): remove the parameter

Trait Implementations

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

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.