Alembic: add support for reading override layers

Override layers are a standard feature of Alembic, where archives can override
data from other archives, provided that the hierarchies match.

This is useful for modifying a UV map, updating an animation, or even creating
some sort of LOD system where low resolution meshes are swapped by high resolution
versions.

It is possible to add UV maps and vertex colors using this system, however, they
will only appear in the spreadsheet editor when viewing evaluated data, as the UV
map and Vertex color UI only show data present on the original mesh.

Implementation wise, this adds a `CacheFileLayer` data structure to the `CacheFile`
DNA, as well as some operators and UI to present and manage the layers. For both
the Alembic importer and the Cycles procedural, the main change is creating an
archive from a list of filepaths, instead of a single one.

After importing the base file through the regular import operator, layers can be added
to or removed from the `CacheFile` via the UI list under the `Override Layers` panel
located in the Mesh Sequence Cache modifier. Layers can also be moved around or
hidden.

See differential page for tests files and demos.

Reviewed by: brecht, sybren

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

1 files changed, 167 insertions, 0 deletions

diff --git a/source/blender/makesrna/intern/rna_cachefile.c b/source/blender/makesrna/intern/rna_cachefile.c
index 74d924b8937..2f8fc004d85 100644
--- a/source/blender/makesrna/intern/rna_cachefile.c
+++ b/source/blender/makesrna/intern/rna_cachefile.c
@@ -32,6 +32,7 @@
 
 #ifdef RNA_RUNTIME
 
+#  include "BLI_math.h"
 #  include "BLI_string.h"
 
 #  include "BKE_cachefile.h"
@@ -54,6 +55,14 @@ static void rna_CacheFile_update(Main *UNUSED(bmain), Scene *UNUSED(scene), Poin
   WM_main_add_notifier(NC_OBJECT | ND_DRAW, NULL);
 }
 
+static void rna_CacheFileLayer_update(Main *UNUSED(bmain), Scene *UNUSED(scene), PointerRNA *ptr)
+{
+  CacheFile *cache_file = (CacheFile *)ptr->owner_id;
+
+  DEG_id_tag_update(&cache_file->id, ID_RECALC_COPY_ON_WRITE);
+  WM_main_add_notifier(NC_OBJECT | ND_DRAW, NULL);
+}
+
 static void rna_CacheFile_dependency_update(Main *bmain, Scene *scene, PointerRNA *ptr)
 {
   rna_CacheFile_update(bmain, scene, ptr);
@@ -66,6 +75,91 @@ static void rna_CacheFile_object_paths_begin(CollectionPropertyIterator *iter, P
   rna_iterator_listbase_begin(iter, &cache_file->object_paths, NULL);
 }
 
+static PointerRNA rna_CacheFile_active_layer_get(PointerRNA *ptr)
+{
+  CacheFile *cache_file = (CacheFile *)ptr->owner_id;
+  return rna_pointer_inherit_refine(
+      ptr, &RNA_CacheFileLayer, BKE_cachefile_get_active_layer(cache_file));
+}
+
+static void rna_CacheFile_active_layer_set(PointerRNA *ptr,
+                                           PointerRNA value,
+                                           struct ReportList *reports)
+{
+  CacheFile *cache_file = (CacheFile *)ptr->owner_id;
+  int index = BLI_findindex(&cache_file->layers, value.data);
+  if (index == -1) {
+    BKE_reportf(reports,
+                RPT_ERROR,
+                "Layer '%s' not found in object '%s'",
+                ((CacheFileLayer *)value.data)->filepath,
+                cache_file->id.name + 2);
+    return;
+  }
+
+  cache_file->active_layer = index + 1;
+}
+
+static int rna_CacheFile_active_layer_index_get(PointerRNA *ptr)
+{
+  CacheFile *cache_file = (CacheFile *)ptr->owner_id;
+  return cache_file->active_layer - 1;
+}
+
+static void rna_CacheFile_active_layer_index_set(PointerRNA *ptr, int value)
+{
+  CacheFile *cache_file = (CacheFile *)ptr->owner_id;
+  cache_file->active_layer = value + 1;
+}
+
+static void rna_CacheFile_active_layer_index_range(
+    PointerRNA *ptr, int *min, int *max, int *UNUSED(softmin), int *UNUSED(softmax))
+{
+  CacheFile *cache_file = (CacheFile *)ptr->owner_id;
+
+  *min = 0;
+  *max = max_ii(0, BLI_listbase_count(&cache_file->layers) - 1);
+}
+
+static void rna_CacheFileLayer_hidden_flag_set(PointerRNA *ptr, const bool value)
+{
+  CacheFileLayer *layer = (CacheFileLayer *)ptr->data;
+
+  if (value) {
+    layer->flag |= CACHEFILE_LAYER_HIDDEN;
+  }
+  else {
+    layer->flag &= ~CACHEFILE_LAYER_HIDDEN;
+  }
+}
+
+static CacheFileLayer *rna_CacheFile_layer_new(CacheFile *cache_file,
+                                               bContext *C,
+                                               ReportList *reports,
+                                               const char *filepath)
+{
+  CacheFileLayer *layer = BKE_cachefile_add_layer(cache_file, filepath);
+  if (layer == NULL) {
+    BKE_reportf(
+        reports, RPT_ERROR, "Cannot add a layer to CacheFile '%s'", cache_file->id.name + 2);
+    return NULL;
+  }
+
+  Depsgraph *depsgraph = CTX_data_ensure_evaluated_depsgraph(C);
+  BKE_cachefile_reload(depsgraph, cache_file);
+  WM_main_add_notifier(NC_OBJECT | ND_DRAW, NULL);
+  return layer;
+}
+
+static void rna_CacheFile_layer_remove(CacheFile *cache_file, bContext *C, PointerRNA *layer_ptr)
+{
+  CacheFileLayer *layer = layer_ptr->data;
+  BKE_cachefile_remove_layer(cache_file, layer);
+  Depsgraph *depsgraph = CTX_data_ensure_evaluated_depsgraph(C);
+  BKE_cachefile_reload(depsgraph, cache_file);
+  WM_main_add_notifier(NC_OBJECT | ND_DRAW, NULL);
+}
+
 #else
 
 /* cachefile.object_paths */
@@ -94,6 +188,61 @@ static void rna_def_cachefile_object_paths(BlenderRNA *brna, PropertyRNA *cprop)
   RNA_def_struct_ui_text(srna, "Object Paths", "Collection of object paths");
 }
 
+static void rna_def_cachefile_layer(BlenderRNA *brna)
+{
+  StructRNA *srna = RNA_def_struct(brna, "CacheFileLayer", NULL);
+  RNA_def_struct_sdna(srna, "CacheFileLayer");
+  RNA_def_struct_ui_text(
+      srna,
+      "Cache Layer",
+      "Layer of the cache, used to load or override data from the first the first layer");
+
+  PropertyRNA *prop = RNA_def_property(srna, "filepath", PROP_STRING, PROP_FILEPATH);
+  RNA_def_property_ui_text(prop, "File Path", "Path to the archive");
+  RNA_def_property_update(prop, 0, "rna_CacheFileLayer_update");
+
+  prop = RNA_def_property(srna, "hide_layer", PROP_BOOLEAN, PROP_NONE);
+  RNA_def_property_boolean_sdna(prop, NULL, "flag", CACHEFILE_LAYER_HIDDEN);
+  RNA_def_property_boolean_funcs(prop, NULL, "rna_CacheFileLayer_hidden_flag_set");
+  RNA_def_property_ui_icon(prop, ICON_HIDE_OFF, -1);
+  RNA_def_property_ui_text(prop, "Hide Layer", "Do not load data from this layer");
+  RNA_def_property_update(prop, 0, "rna_CacheFileLayer_update");
+}
+
+static void rna_def_cachefile_layers(BlenderRNA *brna, PropertyRNA *cprop)
+{
+  RNA_def_property_srna(cprop, "CacheFileLayers");
+  StructRNA *srna = RNA_def_struct(brna, "CacheFileLayers", NULL);
+  RNA_def_struct_sdna(srna, "CacheFile");
+  RNA_def_struct_ui_text(srna, "Cache Layers", "Collection of cache layers");
+
+  PropertyRNA *prop = RNA_def_property(srna, "active", PROP_POINTER, PROP_NONE);
+  RNA_def_property_struct_type(prop, "CacheFileLayer");
+  RNA_def_property_pointer_funcs(
+      prop, "rna_CacheFile_active_layer_get", "rna_CacheFile_active_layer_set", NULL, NULL);
+  RNA_def_property_flag(prop, PROP_EDITABLE);
+  RNA_def_property_ui_text(prop, "Active Layer", "Active layer of the CacheFile");
+
+  /* Add a layer. */
+  FunctionRNA *func = RNA_def_function(srna, "new", "rna_CacheFile_layer_new");
+  RNA_def_function_flag(func, FUNC_USE_REPORTS | FUNC_USE_CONTEXT);
+  RNA_def_function_ui_description(func, "Add a new layer");
+  PropertyRNA *parm = RNA_def_string(
+      func, "filepath", "File Path", 0, "", "File path to the archive used as a layer");
+  RNA_def_parameter_flags(parm, 0, PARM_REQUIRED);
+  /* Return type. */
+  parm = RNA_def_pointer(func, "layer", "CacheFileLayer", "", "Newly created layer");
+  RNA_def_function_return(func, parm);
+
+  /* Remove a layer. */
+  func = RNA_def_function(srna, "remove", "rna_CacheFile_layer_remove");
+  RNA_def_function_flag(func, FUNC_USE_CONTEXT);
+  RNA_def_function_ui_description(func, "Remove an existing layer from the cache file");
+  parm = RNA_def_pointer(func, "layer", "CacheFileLayer", "", "Layer to remove");
+  RNA_def_parameter_flags(parm, PROP_NEVER_NULL, PARM_REQUIRED | PARM_RNAPTR);
+  RNA_def_parameter_clear_flags(parm, PROP_THICK_WRAP, 0);
+}
+
 static void rna_def_cachefile(BlenderRNA *brna)
 {
   StructRNA *srna = RNA_def_struct(brna, "CacheFile", "ID");
@@ -234,6 +383,23 @@ static void rna_def_cachefile(BlenderRNA *brna)
   RNA_def_property_update(prop, 0, "rna_CacheFile_update");
   RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
 
+  /* ----------------- Alembic Layers ----------------- */
+
+  prop = RNA_def_property(srna, "layers", PROP_COLLECTION, PROP_NONE);
+  RNA_def_property_collection_sdna(prop, NULL, "layers", NULL);
+  RNA_def_property_struct_type(prop, "CacheFileLayer");
+  RNA_def_property_override_clear_flag(prop, PROPOVERRIDE_OVERRIDABLE_LIBRARY);
+  RNA_def_property_ui_text(prop, "Cache Layers", "Layers of the cache");
+  rna_def_cachefile_layers(brna, prop);
+
+  prop = RNA_def_property(srna, "active_index", PROP_INT, PROP_UNSIGNED);
+  RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
+  RNA_def_property_int_sdna(prop, NULL, "active_layer");
+  RNA_def_property_int_funcs(prop,
+                             "rna_CacheFile_active_layer_index_get",
+                             "rna_CacheFile_active_layer_index_set",
+                             "rna_CacheFile_active_layer_index_range");
+
   RNA_define_lib_overridable(false);
 
   rna_def_cachefile_object_paths(brna, prop);
@@ -245,6 +411,7 @@ void RNA_def_cachefile(BlenderRNA *brna)
 {
   rna_def_cachefile(brna);
   rna_def_alembic_object_path(brna);
+  rna_def_cachefile_layer(brna);
 }
 
 #endif