Rename 'buffers' -> 'workspace'; add API docs

CHANGELOG.md

@@ -85,6 +85,8 @@ This section may not be all-inclusive; sorry!  I _did_ warn you that
 - Similarly, make `ShapeColorBuffers` not store GPU objects, so it can be
   constructed independently through `ShapeColorBuffers::new` (and shared between
   threads).
+- Rename the workspace buffer objects from `Buffers` to `Workspace` (e.g.
+  `fidget::wgpu::voxel::Buffers`) to more clearly reflect their usage.
 
 # 0.5.0
 This is a large release with a bunch of small features, reorganization, and one

demos/cli/src/main.rs

@@ -396,11 +396,11 @@ fn run3d_wgpu(
     };
     let mut image = Default::default();
     let start = std::time::Instant::now();
-    let mut buffers = ctx.buffers();
-    let mut out = gpu.read_buffer_for(buffers.output());
+    let mut workspace = ctx.workspace();
+    let mut out = gpu.read_buffer_for(workspace.output());
     let shape = fidget::wgpu::RenderShape::new(&shape)?;
     for _ in 0..settings.n {
-        image = ctx.run(&shape, &mut buffers, &mut out, cfg)?;
+        image = ctx.run(&shape, &mut workspace, &mut out, cfg)?;
     }
     let _ = image;
     info!(
@@ -410,16 +410,16 @@ fn run3d_wgpu(
     );
 
     let effects = fidget::wgpu::voxel::effects::Context::new(&gpu);
-    let mut merge_buf = effects.merge_buffers();
-    let mut ssao_buf = effects.ssao_buffers();
-    let mut shade_buf = effects.shade_buffers();
+    let mut merge_buf = effects.merge_workspace();
+    let mut ssao_buf = effects.ssao_workspace();
+    let mut shade_buf = effects.shade_workspace();
 
     let start = std::time::Instant::now();
     use fidget::wgpu::voxel::effects::MergeSettings;
     let out_bytes = match mode {
         RenderMode3D::Heightmap => {
             effects.submit_merge(
-                buffers.output(),
+                workspace.output(),
                 MergeSettings {
                     denoise: false,
                     z_scale: zflatten,
@@ -434,7 +434,7 @@ fn run3d_wgpu(
         }
         RenderMode3D::BlurredOcclusion { denoise } => {
             effects.submit_merge(
-                buffers.output(),
+                workspace.output(),
                 MergeSettings {
                     denoise,
                     z_scale: zflatten,
@@ -447,7 +447,7 @@ fn run3d_wgpu(
         }
         RenderMode3D::RawOcclusion { denoise } => {
             effects.submit_merge(
-                buffers.output(),
+                workspace.output(),
                 MergeSettings {
                     denoise,
                     z_scale: zflatten,
@@ -460,7 +460,7 @@ fn run3d_wgpu(
         }
         RenderMode3D::Shaded { denoise, ssao } => {
             effects.submit_merge(
-                buffers.output(),
+                workspace.output(),
                 MergeSettings {
                     denoise,
                     z_scale: zflatten,
@@ -688,7 +688,7 @@ fn run2d_wgpu(
     };
     let mut image = Default::default();
     let start = std::time::Instant::now();
-    let mut buffers = ctx.buffers();
+    let mut buffers = ctx.workspace();
     let mut out = gpu.read_buffer_for(buffers.output());
     let shape = fidget::wgpu::RenderShape::new(&shape)?;
     let mut postprocess_time = std::time::Duration::ZERO;

fidget-wgpu/src/lib.rs

@@ -1,4 +1,66 @@
 //! Shader generation and WGPU-based image rendering
+//!
+//! # API design
+//! Using GPUs is complicated<sup>[citation needed]</sup>.  The APIs in this
+//! crate try to strike a balance between ease of use and efficiency.  As
+//! always, feel free to open an issue or discussion if the APIs don't work for
+//! you; they were codesigned along with
+//! [Halfspace](https://github.com/mkeeter/halfspace), and may not yet be
+//! suitable for every use case.
+//!
+//! ## Object types
+//! All of the modules use similar patterns of objects:
+//!
+//! - The [`Gpu`] object is passed around to provide device and queues
+//! - A `Context` object contains pipelines
+//! - A `Workspace` object contains buffers used when rendering
+//! - An output buffer can be read back to the CPU or passed to a subsequent
+//!   render pipeline
+//!
+//! ### Context objects
+//! A context object contains GPU pipelines and allow users to dispatch work to
+//! the GPU.  Voxel and pixel rendering are managed by [`voxel::Context`] and
+//! [`pixel::Context`] respectively.  Post-processing is done by
+//! [`voxel::effects::Context`] and [`pixel::effects::Context`].
+//!
+//! Users are expected to create one (of each) context object per thread or
+//! worker, since GPU resources can't be shared.
+//!
+//! Context objects have two flavors of functions.  At the highest level, `run`
+//! and `run_async` functions perform rendering and copy data back to the CPU
+//! (e.g. [`voxel::Context::run`] and [`run_async`](voxel::Context::run_async)).
+//! To simply submit work to the GPU, use a `submit` function (e.g.
+//! [`voxel::Context::submit`]).
+//!
+//! ### Workspace objects
+//! Workspace objects contain all of the buffers that are used when dispatching
+//! work to the GPU.  They are also per-thread (or per-worker).  You may have
+//! more than one per thread if you want to dispatch multiple jobs
+//! simultaneously; it's your computer.
+//!
+//! Workspaces resize themselves automatically when used in rendering.  They
+//! typically have [`size()`](voxel::Workspace::size) (active bytes) and
+//! [`capacity()`](voxel::Workspace::capacity) (total allocated bytes)
+//! functions; users may want to check for overly large ratios and recreate
+//! workspaces.
+//!
+//! Workspaces are stateful; after they are used in a `submit` function, they
+//! will contain data in a GPU buffer.  The output buffer is typically accessed
+//! with the `output()` function, e.g. [`voxel::Workspace::output`].
+//!
+//! ### Reading data from buffers
+//! The output of a workspace is a [`FlexBuffer`](crate::buf::FlexBuffer)
+//! (indeed, they are used pervasively throughout this crate).  Output buffers
+//! are created with `STORAGE | COPY_SRC`.  Reading data back to the CPU is a
+//! three-part process:
+//!
+//! - Create a CPU-readable buffer with [`Gpu::read_buffer_for`]
+//! - Copy data with [`Gpu::copy`]
+//! - Map the readable buffer with [`Gpu::map`] or [`Gpu::map_async`]
+//!
+//! For quick debugging, [`Gpu::read_vec`] does all of these steps.  You
+//! wouldn't want to use in a tight loop, since it allocates a GPU buffer on
+//! each call.
 #![warn(missing_docs)]
 
 use fidget_bytecode::{Bytecode, ReservedRegister};

fidget-wgpu/src/pixel/effects/mod.rs

@@ -12,9 +12,9 @@
 //! image to be completed) would simply be blurry; with distance interpolation,
 //! it remains sharper (though not pixel-perfect).
 //!
-//! Output is stored in the [`MergeBuffers`] object, and may be accessed with
-//! [`output_distance`](MergeBuffers::output_distance) and
-//! [`output_color`](MergeBuffers::output_color).
+//! Output is stored in the [`MergeWorkspace`] object, and may be accessed with
+//! [`output_distance`](MergeWorkspace::output_distance) and
+//! [`output_color`](MergeWorkspace::output_color).
 //! Note that if color has not been computed, `output_color` will return `None`.
 use crate::{
     CopyVarsError, Gpu, RegPipeline,
@@ -97,7 +97,7 @@ tag!(
 );
 
 /// Handle to a set of buffers used when merging images
-pub struct MergeBuffers {
+pub struct MergeWorkspace {
     config: wgpu::Buffer,
     distance: FlexBuffer<PixelDistanceBufferTag>,
     color: FlexBuffer<PixelColorBufferTag>,
@@ -112,7 +112,7 @@ pub struct MergeBuffers {
     has_color: bool,
 }
 
-impl MergeBuffers {
+impl MergeWorkspace {
     /// Resets the merge buffer
     ///
     /// The next call to [`Context::submit_merge`] will clear the buffer and
@@ -222,14 +222,14 @@ impl Context {
 
     /// Submits a set of merge operations to accumulate a single image
     ///
-    /// [`MergeBuffers::reset`] should be called before the first call to
+    /// [`MergeWorkspace::reset`] should be called before the first call to
     /// `submit_merge`. For the first merge after a reset, the output buffer is
     /// resized to fit the images; subsequent merges must be of the same size.
     pub fn submit_merge(
         &self,
         image: &FlexBuffer<PixelBufferTag>,
         remove_nans: bool,
-        buf: &mut MergeBuffers,
+        buf: &mut MergeWorkspace,
     ) -> Result<(), MergeError> {
         let size = image.size();
         if buf.image_count > 0 {
@@ -320,8 +320,8 @@ impl Context {
         Ok(())
     }
 
-    /// Builds a new set of [`MergeBuffers`] for the given image size
-    pub fn merge_buffers(&self) -> MergeBuffers {
+    /// Builds a new set of [`MergeWorkspace`] for the given image size
+    pub fn merge_workspace(&self) -> MergeWorkspace {
         let config = self.gpu.device.create_buffer(&wgpu::BufferDescriptor {
             label: Some("config"),
             size: std::mem::size_of::<MergeConfig>() as u64,
@@ -337,7 +337,7 @@ impl Context {
         let color =
             FlexBuffer::new(&self.gpu.device, "pixel merge color", 64.into())
                 .unwrap();
-        MergeBuffers {
+        MergeWorkspace {
             config,
             distance,
             color,
@@ -348,12 +348,12 @@ impl Context {
 
     /// Submits a color evaluation pass
     ///
-    /// Image size is set from the `MergeBuffers`; the transform matrix is
+    /// Image size is set from the `MergeWorkspace`; the transform matrix is
     /// provided separately (but should be the same one used for image
     /// evaluation).
     pub fn submit_color(
         &self,
-        merge: &mut MergeBuffers,
+        merge: &mut MergeWorkspace,
         settings: ColorSettings,
         shape: &ShapeColorBuffers,
         bufs: &mut ColorWorkspace,
@@ -369,12 +369,12 @@ impl Context {
 
     /// Submits a color evaluation pass with auxiliary variables
     ///
-    /// Image size is set from the `MergeBuffers`; the transform matrix is
+    /// Image size is set from the `MergeWorkspace`; the transform matrix is
     /// provided separately (but should be the same one used for image
     /// evaluation).
     pub fn submit_color_with_vars(
         &self,
-        merge: &mut MergeBuffers,
+        merge: &mut MergeWorkspace,
         settings: ColorSettings,
         shape: &ShapeColorBuffers,
         bufs: &mut ColorWorkspace,
@@ -501,7 +501,7 @@ impl ColorContext {
 
     fn submit(
         &self,
-        image: &mut MergeBuffers,
+        image: &mut MergeWorkspace,
         settings: ColorSettings,
         shape: &ShapeColorBuffers,
         bufs: &mut ColorWorkspace,