From 11727c5dbbeba80380ce4d8ff58b71e73f4ea920 Mon Sep 17 00:00:00 2001 From: Brian Merchant Date: Thu, 5 May 2022 20:12:37 -0700 Subject: [PATCH 1/6] Documenting `BufferVec`. --- .../src/render_resource/buffer_vec.rs | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/crates/bevy_render/src/render_resource/buffer_vec.rs b/crates/bevy_render/src/render_resource/buffer_vec.rs index ad8f5ff2adfe1..2e17544741cd5 100644 --- a/crates/bevy_render/src/render_resource/buffer_vec.rs +++ b/crates/bevy_render/src/render_resource/buffer_vec.rs @@ -6,6 +6,18 @@ use bevy_core::{cast_slice, Pod}; use copyless::VecHelper; use wgpu::BufferUsages; +/// A structure for storing raw bytes that have already been properly formatted +/// for the [`RenderDevice`](crate::renderer::RenderDevice). +/// +/// "Properly formatted" means data that is [`#[repr(C)]`](https://doc.rust-lang.org/reference/type-layout.html#the-c-representation), [`Pod`] +/// and `Zeroable`. Unlike the [`DynamicUniformVec`](crate::render_resource::DynamicUniformVec), +/// [`UniformVec`](crate::render_resource::UniformVec) and [`StorageBuffer`](crate::render_resource::StorageBuffer) structures, +/// `BufferVec` does not provide padding or alignment between items, or within items. +/// +/// The data is stored on the host, calling [`reserve`](crate::render_resource::BufferVec::reserve) +/// allocates memory on the [`RenderDevice`](crate::renderer::RenderDevice). +/// [`write_buffer`](crate::render_resource::BufferVec::write_buffer) queues copying of the data +/// from the host to the [`RenderDevice`](crate::renderer::RenderDevice). pub struct BufferVec { values: Vec, buffer: Option, @@ -60,6 +72,17 @@ impl BufferVec { index } + /// Creates a [`Buffer`](crate::render_resource::Buffer) on the [`RenderDevice`](crate::renderer::RenderDevice) with size + /// at least `std::mem::size_of::() * capacity`, unless a such a buffer already exists. + /// + /// If a [`Buffer`](crate::render_resource::Buffer) exists, but is too small, references to it will be discarded, + /// and a new [`Buffer`](crate::render_resource::Buffer) will be created. Any previously created [`Buffer`](crate::render_resource::Buffer)s + /// that are no longer referenced will be deleted by the [`RenderDevice`](crate::renderer::RenderDevice) + /// once it is done using them (typically 1-2 frames). + /// + /// In addition to any [`BufferUsages`](crate::render_resource::BufferUsages) provided when + /// the `BufferVec` was created, the buffer on the [`RenderDevice`](crate::renderer::RenderDevice) + /// is marked as [`BufferUsages::COPY_DST`](crate::render_resource::BufferUsages). pub fn reserve(&mut self, capacity: usize, device: &RenderDevice) { if capacity > self.capacity { self.capacity = capacity; @@ -73,6 +96,11 @@ impl BufferVec { } } + /// Queues writing of memory from the host to [`RenderDevice`](crate::renderer::RenderDevice) using + /// the provided [`RenderQueue`](crate::renderer::RenderQueue). + /// + /// Before queueing the write, a [`reserve`](crate::render_resource::BufferVec::reserve) operation + /// is executed. pub fn write_buffer(&mut self, device: &RenderDevice, queue: &RenderQueue) { if self.values.is_empty() { return; From 9ef6d24c986dfcee92edf335faf18dafeb72e0a8 Mon Sep 17 00:00:00 2001 From: Brian Merchant Date: Tue, 21 Jun 2022 09:33:53 -0700 Subject: [PATCH 2/6] Replace RenderDevice by GPU. Co-authored-by: Robert Swain --- crates/bevy_render/src/render_resource/buffer_vec.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_render/src/render_resource/buffer_vec.rs b/crates/bevy_render/src/render_resource/buffer_vec.rs index 2e17544741cd5..f78dc8f2e25bb 100644 --- a/crates/bevy_render/src/render_resource/buffer_vec.rs +++ b/crates/bevy_render/src/render_resource/buffer_vec.rs @@ -7,7 +7,7 @@ use copyless::VecHelper; use wgpu::BufferUsages; /// A structure for storing raw bytes that have already been properly formatted -/// for the [`RenderDevice`](crate::renderer::RenderDevice). +/// for use by the GPU. /// /// "Properly formatted" means data that is [`#[repr(C)]`](https://doc.rust-lang.org/reference/type-layout.html#the-c-representation), [`Pod`] /// and `Zeroable`. Unlike the [`DynamicUniformVec`](crate::render_resource::DynamicUniformVec), From 5ffd5800f7d9c867a5dc1dff3996a057fb9abfa5 Mon Sep 17 00:00:00 2001 From: Brian Merchant Date: Tue, 21 Jun 2022 09:35:40 -0700 Subject: [PATCH 3/6] State Pod as the direct requirement; and reflect reality of encase now being merged. Co-authored-by: Robert Swain --- .../src/render_resource/buffer_vec.rs | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/crates/bevy_render/src/render_resource/buffer_vec.rs b/crates/bevy_render/src/render_resource/buffer_vec.rs index f78dc8f2e25bb..af2be8e79826b 100644 --- a/crates/bevy_render/src/render_resource/buffer_vec.rs +++ b/crates/bevy_render/src/render_resource/buffer_vec.rs @@ -9,15 +9,26 @@ use wgpu::BufferUsages; /// A structure for storing raw bytes that have already been properly formatted /// for use by the GPU. /// -/// "Properly formatted" means data that is [`#[repr(C)]`](https://doc.rust-lang.org/reference/type-layout.html#the-c-representation), [`Pod`] -/// and `Zeroable`. Unlike the [`DynamicUniformVec`](crate::render_resource::DynamicUniformVec), -/// [`UniformVec`](crate::render_resource::UniformVec) and [`StorageBuffer`](crate::render_resource::StorageBuffer) structures, -/// `BufferVec` does not provide padding or alignment between items, or within items. +/// "Properly formatted" means data that item data already meets the alignment and padding +/// requirements for how it will be used on the GPU. +/// +/// Index, vertex, and instance-rate vertex buffers have no alignment nor padding requirements and +/// so this helper type is a good choice for them. Uniform buffers must adhere to std140 +/// alignment/padding requirements, and storage buffers to std430. There are helper types for such +/// buffers: +/// - Uniform buffers +/// - Plain: [`UniformBuffer`](crate::render_resource::UniformBuffer) +/// - Dynamic offsets: [`DynamicUniformBuffer`](crate::render_resource::DynamicUniformBuffer) +/// - Storage buffers +/// - Plain: [`StorageBuffer`](crate::render_resource::StorageBuffer) +/// - Dynamic offsets: [`DynamicStorageBuffer`](crate::render_resource::DynamicStorageBuffer) +/// +/// The item type must implement [`Pod`] for its data representation to be directly copyable. /// -/// The data is stored on the host, calling [`reserve`](crate::render_resource::BufferVec::reserve) -/// allocates memory on the [`RenderDevice`](crate::renderer::RenderDevice). +/// The contained data is stored in system RAM. Calling [`reserve`](crate::render_resource::BufferVec::reserve) +/// allocates VRAM from the [`RenderDevice`](crate::renderer::RenderDevice). /// [`write_buffer`](crate::render_resource::BufferVec::write_buffer) queues copying of the data -/// from the host to the [`RenderDevice`](crate::renderer::RenderDevice). +/// from system RAM to VRAM. pub struct BufferVec { values: Vec, buffer: Option, From da1f666d1ab473476f28751e491cd6fd6a3886fc Mon Sep 17 00:00:00 2001 From: Brian Merchant Date: Tue, 21 Jun 2022 09:36:43 -0700 Subject: [PATCH 4/6] Say "system RAM" instead of "host memory" and "VRAM" instead of "device memory" Co-authored-by: Robert Swain --- crates/bevy_render/src/render_resource/buffer_vec.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/bevy_render/src/render_resource/buffer_vec.rs b/crates/bevy_render/src/render_resource/buffer_vec.rs index af2be8e79826b..7ea8f6ccde272 100644 --- a/crates/bevy_render/src/render_resource/buffer_vec.rs +++ b/crates/bevy_render/src/render_resource/buffer_vec.rs @@ -107,10 +107,10 @@ impl BufferVec { } } - /// Queues writing of memory from the host to [`RenderDevice`](crate::renderer::RenderDevice) using - /// the provided [`RenderQueue`](crate::renderer::RenderQueue). + /// Queues writing of data from system RAM to VRAM using the [`RenderDevice`](crate::renderer::RenderDevice) + /// and the provided [`RenderQueue`](crate::renderer::RenderQueue). /// - /// Before queueing the write, a [`reserve`](crate::render_resource::BufferVec::reserve) operation + /// Before queuing the write, a [`reserve`](crate::render_resource::BufferVec::reserve) operation /// is executed. pub fn write_buffer(&mut self, device: &RenderDevice, queue: &RenderQueue) { if self.values.is_empty() { From e407b97532d09febf611da69120a6a4f631cb322 Mon Sep 17 00:00:00 2001 From: Brian Merchant Date: Tue, 21 Jun 2022 14:06:31 -0700 Subject: [PATCH 5/6] remove repetition of "data" Co-authored-by: Robert Swain --- crates/bevy_render/src/render_resource/buffer_vec.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_render/src/render_resource/buffer_vec.rs b/crates/bevy_render/src/render_resource/buffer_vec.rs index 7ea8f6ccde272..4648a6f8072b1 100644 --- a/crates/bevy_render/src/render_resource/buffer_vec.rs +++ b/crates/bevy_render/src/render_resource/buffer_vec.rs @@ -9,7 +9,7 @@ use wgpu::BufferUsages; /// A structure for storing raw bytes that have already been properly formatted /// for use by the GPU. /// -/// "Properly formatted" means data that item data already meets the alignment and padding +/// "Properly formatted" means that item data already meets the alignment and padding /// requirements for how it will be used on the GPU. /// /// Index, vertex, and instance-rate vertex buffers have no alignment nor padding requirements and From c50f80c4deae90a4c148f05d23d3f33bfa070a96 Mon Sep 17 00:00:00 2001 From: Brian Merchant Date: Mon, 27 Jun 2022 10:01:40 -0700 Subject: [PATCH 6/6] run cargo fmt --- crates/bevy_render/src/render_resource/buffer_vec.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/bevy_render/src/render_resource/buffer_vec.rs b/crates/bevy_render/src/render_resource/buffer_vec.rs index 4648a6f8072b1..b42802470af0b 100644 --- a/crates/bevy_render/src/render_resource/buffer_vec.rs +++ b/crates/bevy_render/src/render_resource/buffer_vec.rs @@ -11,7 +11,7 @@ use wgpu::BufferUsages; /// /// "Properly formatted" means that item data already meets the alignment and padding /// requirements for how it will be used on the GPU. -/// +/// /// Index, vertex, and instance-rate vertex buffers have no alignment nor padding requirements and /// so this helper type is a good choice for them. Uniform buffers must adhere to std140 /// alignment/padding requirements, and storage buffers to std430. There are helper types for such @@ -22,7 +22,7 @@ use wgpu::BufferUsages; /// - Storage buffers /// - Plain: [`StorageBuffer`](crate::render_resource::StorageBuffer) /// - Dynamic offsets: [`DynamicStorageBuffer`](crate::render_resource::DynamicStorageBuffer) -/// +/// /// The item type must implement [`Pod`] for its data representation to be directly copyable. /// /// The contained data is stored in system RAM. Calling [`reserve`](crate::render_resource::BufferVec::reserve)