diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d3dccda31..6ba8660e40 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,6 +52,7 @@ Bottom level categories: - Document feature requirements for `DEPTH32FLOAT_STENCIL8` by @ErichDonGubler in [#3734](https://github.com/gfx-rs/wgpu/pull/3734). - Flesh out docs. for `AdapterInfo::{device,vendor}` by @ErichDonGubler in [#3763](https://github.com/gfx-rs/wgpu/pull/3763). +- Spell out which sizes are in bytes. By @jimblandy in [#3773](https://github.com/gfx-rs/wgpu/pull/3773). ### Bug Fixes diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs index 445931a6e9..3b6a10cd3d 100644 --- a/wgpu-types/src/lib.rs +++ b/wgpu-types/src/lib.rs @@ -4276,7 +4276,7 @@ impl_bitflags!(BufferUsages); pub struct BufferDescriptor { /// Debug label of a buffer. This will show up in graphics debuggers for easy identification. pub label: L, - /// Size of a buffer. + /// Size of a buffer, in bytes. pub size: BufferAddress, /// Usages of a buffer. If the buffer is used in any way that isn't specified here, the operation /// will panic. @@ -5531,18 +5531,41 @@ pub enum BindingType { Buffer { /// Sub-type of the buffer binding. ty: BufferBindingType, + /// Indicates that the binding has a dynamic offset. /// - /// One offset must be passed to [`RenderPass::set_bind_group`][RPsbg] for each dynamic - /// binding in increasing order of binding number. + /// One offset must be passed to [`RenderPass::set_bind_group`][RPsbg] + /// for each dynamic binding in increasing order of binding number. /// /// [RPsbg]: ../wgpu/struct.RenderPass.html#method.set_bind_group #[cfg_attr(any(feature = "trace", feature = "replay"), serde(default))] has_dynamic_offset: bool, - /// Minimum size of the corresponding `BufferBinding` required to match this entry. - /// When pipeline is created, the size has to cover at least the corresponding structure in the shader - /// plus one element of the unbound array, which can only be last in the structure. - /// If `None`, the check is performed at draw call time instead of pipeline and bind group creation. + + /// The minimum size for a [`BufferBinding`] matching this entry, in bytes. + /// + /// If this is `Some(size)`: + /// + /// - When calling [`create_bind_group`], the resource at this bind point + /// must be a [`BindingResource::Buffer`] whose effective size is at + /// least `size`. + /// + /// - When calling [`create_render_pipeline`] or [`create_compute_pipeline`], + /// `size` must be at least the [minimum buffer binding size] for the + /// shader module global at this bind point: large enough to hold the + /// global's value, along with one element of a trailing runtime-sized + /// array, if present. + /// + /// If this is `None`: + /// + /// - Each draw or dispatch command checks that the buffer range at this + /// bind point satisfies the [minimum buffer binding size]. + /// + /// [`BufferBinding`]: ../wgpu/struct.BufferBinding.html + /// [`create_bind_group`]: ../wgpu/struct.Device.html#method.create_bind_group + /// [`BindingResource::Buffer`]: ../wgpu/enum.BindingResource.html#variant.Buffer + /// [minimum buffer binding size]: https://www.w3.org/TR/webgpu/#minimum-buffer-binding-size + /// [`create_render_pipeline`]: ../wgpu/struct.Device.html#method.create_render_pipeline + /// [`create_compute_pipeline`]: ../wgpu/struct.Device.html#method.create_compute_pipeline #[cfg_attr(any(feature = "trace", feature = "replay"), serde(default))] min_binding_size: Option, }, diff --git a/wgpu/src/lib.rs b/wgpu/src/lib.rs index ea26098916..1ba1315072 100644 --- a/wgpu/src/lib.rs +++ b/wgpu/src/lib.rs @@ -772,13 +772,25 @@ static_assertions::assert_impl_all!(BindingResource: Send, Sync); pub struct BufferBinding<'a> { /// The buffer to bind. pub buffer: &'a Buffer, - /// Base offset of the buffer. For bindings with `dynamic == true`, this offset - /// will be added to the dynamic offset provided in [`RenderPass::set_bind_group`]. + + /// Base offset of the buffer, in bytes. /// - /// The offset has to be aligned to [`Limits::min_uniform_buffer_offset_alignment`] - /// or [`Limits::min_storage_buffer_offset_alignment`] appropriately. + /// If the [`has_dynamic_offset`] field of this buffer's layout entry is + /// `true`, the offset here will be added to the dynamic offset passed to + /// [`RenderPass::set_bind_group`] or [`ComputePass::set_bind_group`]. + /// + /// If the buffer was created with [`BufferUsages::UNIFORM`], then this + /// offset must be a multiple of + /// [`Limits::min_uniform_buffer_offset_alignment`]. + /// + /// If the buffer was created with [`BufferUsages::STORAGE`], then this + /// offset must be a multiple of + /// [`Limits::min_storage_buffer_offset_alignment`]. + /// + /// [`has_dynamic_offset`]: BindingType::Buffer::has_dynamic_offset pub offset: BufferAddress, - /// Size of the binding, or `None` for using the rest of the buffer. + + /// Size of the binding in bytes, or `None` for using the rest of the buffer. pub size: Option, } static_assertions::assert_impl_all!(BufferBinding: Send, Sync);