From ec98ef403ebad9c9b2b5385ae91fa524baba09ea Mon Sep 17 00:00:00 2001 From: Andy Leiserson Date: Mon, 27 Jul 2026 18:21:36 -0700 Subject: [PATCH] docs(hal): Details of buffer and binding sizes (cherry picked from commit 377370d52ba8f84525e8204c232316f6abc6f867) --- wgpu-hal/src/lib.rs | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/wgpu-hal/src/lib.rs b/wgpu-hal/src/lib.rs index 9f3e6ef2a..7fd507068 100644 --- a/wgpu-hal/src/lib.rs +++ b/wgpu-hal/src/lib.rs @@ -884,6 +884,18 @@ pub trait Device: WasmNotSendSync { /// Creates a new buffer. /// /// The initial usage is `wgt::BufferUses::empty()`. + /// + /// `wgpu_hal` may adjust the size in `desc` to a larger value if required + /// by the platform. On success, it returns a tuple of the buffer itself + /// and its actual allocated size. `wgpu-core` is responsible for + /// initializing any portion of the buffer that may be accessed, including + /// any padding added by `create_buffer`. + /// + /// Platform-dependent padding is currently required for uniform buffers on + /// dx12. Support for zero-size vertex and index bindings is also platform + /// dependent, but presently, `wgpu-core` adds padding to the end of all + /// buffers with vertex or index usage, and redirects all zero-size bindings + /// to that padding region, regardless of platform. unsafe fn create_buffer( &self, desc: &BufferDescriptor, @@ -1611,11 +1623,39 @@ pub trait CommandEncoder: WasmNotSendSync + fmt::Debug { unsafe fn set_render_pipeline(&mut self, pipeline: &::RenderPipeline); + /// Register an index buffer binding. + /// + /// The binding offset must be 4B-aligned and strictly less than the buffer + /// size. On some backends, the binding size is ignored. This means that + /// zero-size bindings must be simulated by binding a region of zeros + /// spanning from the provided offset to the end of the buffer. See + /// [`CommandEncoder::set_vertex_buffer`] for more detail. unsafe fn set_index_buffer<'a>( &mut self, binding: BufferBinding<'a, ::Buffer, wgt::BufferAddress>, format: wgt::IndexFormat, ); + /// Register a vertex buffer binding. + /// + /// The binding offset must be 4B-aligned and strictly less than the buffer + /// size. On some backends, the binding size is ignored. This means that + /// zero-size bindings must be simulated by binding a region of zeros + /// spanning from the provided offset to the end of the buffer. + /// + /// These restrictions arise from Vulkan's `vkCmdBindVertexBuffers` and + /// `vkCmdBindIndexBuffer`, which: + /// + /// 1. Do not support specifying the size of the binding. + /// 2. Require that the binding offset is strictly less than the buffer size. + /// + /// A read at any offset from a zero-size binding is out-of-bounds, and + /// should return zero. Because the binding size is not respected, this + /// means there may not be non-zero data between the binding offset and + /// the end of the buffer. + /// + /// Because the binding offset must be strictly less than the buffer size, + /// supporting zero-size bindings requires zero padding at the end of the + /// buffer. unsafe fn set_vertex_buffer<'a>( &mut self, index: u32,