LibOverride: Add `override_hierarchy_create`to ID's RNA API.

5 files changed, 60 insertions, 7 deletions

diff --git a/source/blender/blenkernel/BKE_lib_override.h b/source/blender/blenkernel/BKE_lib_override.h
index 0275c2c235c..4dc99e64cf2 100644
--- a/source/blender/blenkernel/BKE_lib_override.h
+++ b/source/blender/blenkernel/BKE_lib_override.h
@@ -76,7 +76,8 @@ bool BKE_lib_override_library_create(struct Main *bmain,
                                      struct Scene *scene,
                                      struct ViewLayer *view_layer,
                                      struct ID *id_root,
-                                     struct ID *id_reference);
+                                     struct ID *id_reference,
+                                     struct ID **r_id_root_override);
 bool BKE_lib_override_library_template_create(struct ID *id);
 bool BKE_lib_override_library_proxy_convert(struct Main *bmain,
                                             struct Scene *scene,
diff --git a/source/blender/blenkernel/intern/lib_override.c b/source/blender/blenkernel/intern/lib_override.c
index 6718c6ab79f..b76e1b10ed5 100644
--- a/source/blender/blenkernel/intern/lib_override.c
+++ b/source/blender/blenkernel/intern/lib_override.c
@@ -838,7 +838,7 @@ static void lib_override_library_create_post_process(Main *bmain,
 /**
  * Advanced 'smart' function to create fully functional overrides.
  *
- * \note Currently it only does special things if given \a id_root is an object of collection, more
+ * \note Currently it only does special things if given \a id_root is an object or collection, more
  * specific behaviors may be added in the future for other ID types.
  *
  * \note It will override all IDs tagged with \a LIB_TAG_DOIT, and it does not clear that tag at
@@ -848,17 +848,30 @@ static void lib_override_library_create_post_process(Main *bmain,
  * \param id_reference: Some reference ID used to do some post-processing after overrides have been
  * created, may be NULL. Typically, the Empty object instantiating the linked collection we
  * override, currently.
+ * \param r_id_root_override if not NULL, the override generated for the given \a id_root.
  * \return true if override was successfully created.
  */
-bool BKE_lib_override_library_create(
-    Main *bmain, Scene *scene, ViewLayer *view_layer, ID *id_root, ID *id_reference)
+bool BKE_lib_override_library_create(Main *bmain,
+                                     Scene *scene,
+                                     ViewLayer *view_layer,
+                                     ID *id_root,
+                                     ID *id_reference,
+                                     ID **r_id_root_override)
 {
+  if (r_id_root_override != NULL) {
+    *r_id_root_override = NULL;
+  }
+
   const bool success = lib_override_library_create_do(bmain, id_root);
 
   if (!success) {
     return success;
   }
 
+  if (r_id_root_override != NULL) {
+    *r_id_root_override = id_root->newid;
+  }
+
   lib_override_library_create_post_process(
       bmain, scene, view_layer, id_root, id_reference, NULL, false);
 
@@ -928,7 +941,7 @@ bool BKE_lib_override_library_proxy_convert(Main *bmain,
 
   DEG_id_tag_update(&ob_proxy->id, ID_RECALC_COPY_ON_WRITE);
 
-  return BKE_lib_override_library_create(bmain, scene, view_layer, id_root, id_reference);
+  return BKE_lib_override_library_create(bmain, scene, view_layer, id_root, id_reference, NULL);
 }
 
 /**
diff --git a/source/blender/editors/object/object_relations.c b/source/blender/editors/object/object_relations.c
index 127d8681d3c..2c188e310db 100644
--- a/source/blender/editors/object/object_relations.c
+++ b/source/blender/editors/object/object_relations.c
@@ -2454,7 +2454,7 @@ static int make_override_library_exec(bContext *C, wmOperator *op)
   BKE_main_id_tag_all(bmain, LIB_TAG_DOIT, false);
 
   const bool success = BKE_lib_override_library_create(
-      bmain, scene, view_layer, id_root, &obact->id);
+      bmain, scene, view_layer, id_root, &obact->id, NULL);
 
   /* Remove the instance empty from this scene, the items now have an overridden collection
    * instead. */
diff --git a/source/blender/editors/space_outliner/outliner_tools.c b/source/blender/editors/space_outliner/outliner_tools.c
index da47fd29549..f809bb13b42 100644
--- a/source/blender/editors/space_outliner/outliner_tools.c
+++ b/source/blender/editors/space_outliner/outliner_tools.c
@@ -846,7 +846,7 @@ static void id_override_library_create_fn(bContext *C,
         te->store_elem->id->tag |= LIB_TAG_DOIT;
       }
       success = BKE_lib_override_library_create(
-          bmain, CTX_data_scene(C), CTX_data_view_layer(C), id_root, id_reference);
+          bmain, CTX_data_scene(C), CTX_data_view_layer(C), id_root, id_reference, NULL);
     }
     else if (ID_IS_OVERRIDABLE_LIBRARY(id_root)) {
       success = BKE_lib_override_library_create_from_id(bmain, id_root, true) != NULL;
diff --git a/source/blender/makesrna/intern/rna_ID.c b/source/blender/makesrna/intern/rna_ID.c
index 2818f251085..17c79a2f5dc 100644
--- a/source/blender/makesrna/intern/rna_ID.c
+++ b/source/blender/makesrna/intern/rna_ID.c
@@ -611,6 +611,21 @@ static ID *rna_ID_override_create(ID *id, Main *bmain, bool remap_local_usages)
   return local_id;
 }
 
+static ID *rna_ID_override_hierarchy_create(
+    ID *id, Main *bmain, Scene *scene, ViewLayer *view_layer, ID *id_reference)
+{
+  if (!ID_IS_OVERRIDABLE_LIBRARY(id)) {
+    return NULL;
+  }
+
+  BKE_main_id_tag_all(bmain, LIB_TAG_DOIT, false);
+
+  ID *id_root_override = NULL;
+  BKE_lib_override_library_create(bmain, scene, view_layer, id, id_reference, &id_root_override);
+
+  return id_root_override;
+}
+
 static void rna_ID_override_template_create(ID *id, ReportList *reports)
 {
   if (!U.experimental.use_override_templates) {
@@ -1760,6 +1775,30 @@ static void rna_def_ID(BlenderRNA *brna)
                   "Whether local usages of the linked ID should be remapped to the new "
                   "library override of it");
 
+  func = RNA_def_function(srna, "override_hierarchy_create", "rna_ID_override_hierarchy_create");
+  RNA_def_function_ui_description(
+      func,
+      "Create an overridden local copy of this linked data-block, and most of its dependencies "
+      "when it is a Collection or and Object");
+  RNA_def_function_flag(func, FUNC_USE_MAIN);
+  parm = RNA_def_pointer(func, "id", "ID", "", "New overridden local copy of the root ID");
+  RNA_def_function_return(func, parm);
+  parm = RNA_def_pointer(
+      func, "scene", "Scene", "", "In which scene the new overrides should be instantiated");
+  RNA_def_parameter_flags(parm, PROP_NEVER_NULL, PARM_REQUIRED);
+  parm = RNA_def_pointer(func,
+                         "view_layer",
+                         "ViewLayer",
+                         "",
+                         "In which view layer the new overrides should be instantiated");
+  RNA_def_parameter_flags(parm, PROP_NEVER_NULL, PARM_REQUIRED);
+  RNA_def_pointer(func,
+                  "reference",
+                  "ID",
+                  "",
+                  "Another ID (usually an Object or Collection) used to decide where to "
+                  "instantiate the new overrides");
+
   func = RNA_def_function(srna, "override_template_create", "rna_ID_override_template_create");
   RNA_def_function_ui_description(func, "Create an override template for this ID");
   RNA_def_function_flag(func, FUNC_USE_REPORTS);