Cycles: add support for volume motion blur

This adds support for rendering motion blur for volumes, using their
velocity field. This works for fluid simulations and imported VDB
volumes. For the latter, the name of the velocity field can be set per
volume object, with automatic detection of velocity fields that are
split into 3 scalar grids.

A new parameter is also added to scale velocity for more artistic control.

Like for Alembic and USD caches, a parameter to set the unit of time in
which the velocity vectors are expressed is also added. For Blender gas
simulations, the velocity unit should always be in seconds, so this is
only exposed for volume objects which may come from external OpenVDB
files.

These parameters are available under the `Render` panels for the fluid
domain and the volume object data properties respectively.

Credits: kernel advection code from Tangent Animation's Blackbird based
on earlier work by Geraldine Chua

Differential Revision: https://developer.blender.org/D14629

3 files changed, 70 insertions, 0 deletions

diff --git a/source/blender/blenkernel/BKE_volume.h b/source/blender/blenkernel/BKE_volume.h
index 77f01e7919d..8791469360a 100644
--- a/source/blender/blenkernel/BKE_volume.h
+++ b/source/blender/blenkernel/BKE_volume.h
@@ -77,6 +77,11 @@ const VolumeGrid *BKE_volume_grid_active_get_for_read(const struct Volume *volum
 /* Tries to find a grid with the given name. Make sure that the volume has been loaded. */
 const VolumeGrid *BKE_volume_grid_find_for_read(const struct Volume *volume, const char *name);
 
+/* Tries to set the name of the velocity field. If no such grid exists with the given base name,
+ * this will try common postfixes in order to detect velocity fields split into multiple grids.
+ * Return false if neither finding with the base name nor with the postfixes succeeded. */
+bool BKE_volume_set_velocity_grid_by_name(struct Volume *volume, const char *base_name);
+
 /* Grid
  *
  * By default only grid metadata is loaded, for access to the tree and voxels
diff --git a/source/blender/blenkernel/intern/fluid.c b/source/blender/blenkernel/intern/fluid.c
index 81e73b6cf2c..efb33294efd 100644
--- a/source/blender/blenkernel/intern/fluid.c
+++ b/source/blender/blenkernel/intern/fluid.c
@@ -5071,6 +5071,9 @@ void BKE_fluid_modifier_copy(const struct FluidModifierData *fmd,
     tfds->openvdb_compression = fds->openvdb_compression;
     tfds->clipping = fds->clipping;
     tfds->openvdb_data_depth = fds->openvdb_data_depth;
+
+    /* Render options. */
+    tfds->velocity_scale = fds->velocity_scale;
   }
   else if (tfmd->flow) {
     FluidFlowSettings *tffs = tfmd->flow;
diff --git a/source/blender/blenkernel/intern/volume.cc b/source/blender/blenkernel/intern/volume.cc
index 0c131863edd..307466d7dc9 100644
--- a/source/blender/blenkernel/intern/volume.cc
+++ b/source/blender/blenkernel/intern/volume.cc
@@ -60,6 +60,7 @@ using blender::float3;
 using blender::float4x4;
 using blender::IndexRange;
 using blender::StringRef;
+using blender::StringRefNull;
 
 #ifdef WITH_OPENVDB
 #  include <atomic>
@@ -517,6 +518,8 @@ static void volume_init_data(ID *id)
   MEMCPY_STRUCT_AFTER(volume, DNA_struct_default_get(Volume), id);
 
   BKE_volume_init_grids(volume);
+
+  BLI_strncpy(volume->velocity_grid, "velocity", sizeof(volume->velocity_grid));
 }
 
 static void volume_copy_data(Main *UNUSED(bmain),
@@ -794,6 +797,57 @@ bool BKE_volume_is_loaded(const Volume *volume)
 #endif
 }
 
+bool BKE_volume_set_velocity_grid_by_name(Volume *volume, const char *base_name)
+{
+  const StringRefNull ref_base_name = base_name;
+
+  if (BKE_volume_grid_find_for_read(volume, base_name)) {
+    BLI_strncpy(volume->velocity_grid, base_name, sizeof(volume->velocity_grid));
+    volume->runtime.velocity_x_grid[0] = '\0';
+    volume->runtime.velocity_y_grid[0] = '\0';
+    volume->runtime.velocity_z_grid[0] = '\0';
+    return true;
+  }
+
+  /* It could be that the velocity grid is split in multiple grids, try with known postfixes. */
+  const StringRefNull postfixes[][3] = {{"x", "y", "z"}, {".x", ".y", ".z"}, {"_x", "_y", "_z"}};
+
+  for (const StringRefNull *postfix : postfixes) {
+    bool found = true;
+    for (int i = 0; i < 3; i++) {
+      std::string post_fixed_name = ref_base_name + postfix[i];
+      if (!BKE_volume_grid_find_for_read(volume, post_fixed_name.c_str())) {
+        found = false;
+        break;
+      }
+    }
+
+    if (!found) {
+      continue;
+    }
+
+    /* Save the base name as well. */
+    BLI_strncpy(volume->velocity_grid, base_name, sizeof(volume->velocity_grid));
+    BLI_strncpy(volume->runtime.velocity_x_grid,
+                (ref_base_name + postfix[0]).c_str(),
+                sizeof(volume->runtime.velocity_x_grid));
+    BLI_strncpy(volume->runtime.velocity_y_grid,
+                (ref_base_name + postfix[1]).c_str(),
+                sizeof(volume->runtime.velocity_y_grid));
+    BLI_strncpy(volume->runtime.velocity_z_grid,
+                (ref_base_name + postfix[2]).c_str(),
+                sizeof(volume->runtime.velocity_z_grid));
+    return true;
+  }
+
+  /* Reset to avoid potential issues. */
+  volume->velocity_grid[0] = '\0';
+  volume->runtime.velocity_x_grid[0] = '\0';
+  volume->runtime.velocity_y_grid[0] = '\0';
+  volume->runtime.velocity_z_grid[0] = '\0';
+  return false;
+}
+
 bool BKE_volume_load(const Volume *volume, const Main *bmain)
 {
 #ifdef WITH_OPENVDB
@@ -857,6 +911,14 @@ bool BKE_volume_load(const Volume *volume, const Main *bmain)
     }
   }
 
+  /* Try to detect the velocity grid. */
+  const char *common_velocity_names[] = {"velocity", "vel", "v"};
+  for (const char *common_velocity_name : common_velocity_names) {
+    if (BKE_volume_set_velocity_grid_by_name(const_cast<Volume *>(volume), common_velocity_name)) {
+      break;
+    }
+  }
+
   BLI_strncpy(grids.filepath, filepath, FILE_MAX);
 
   return grids.error_msg.empty();