LibOverrides: fix handling of hierarchy root in complex cases.

This affects essentially the Outliner 'create hierarchy' tool currenlty.
Previously code did not handle properly hierarchy root in case overrides
where created from a non-root ID (e.g. an object inside of a linked
collection), and in case additional partial overrides were added to an
existing partially overrided hierarchy.

Also did some renaming on the go to avoid using 'reference' in override
context for anything else but the reference linked IDs.

3 files changed, 87 insertions, 31 deletions

diff --git a/source/blender/blenkernel/BKE_lib_override.h b/source/blender/blenkernel/BKE_lib_override.h
index 858bc2f5625..98301ca7a70 100644
--- a/source/blender/blenkernel/BKE_lib_override.h
+++ b/source/blender/blenkernel/BKE_lib_override.h
@@ -92,7 +92,13 @@ struct ID *BKE_lib_override_library_create_from_id(struct Main *bmain,
  *
  * \param id_hierarchy_root: the override ID that is the root of the hierarchy. May be NULL, in
  * which case it is assumed that the given `id_root_reference` is tagged for override, and its
- * newly created override will be used as hierarchy root.
+ * newly created override will be used as hierarchy root. Must be NULL if
+ * `id_hierarchy_root_reference` is not NULL.
+ *
+ * \param id_hierarchy_root_reference: the linked ID that is the root of the hierarchy. Must be
+ * tagged for override. May be NULL, in which case it is assumed that the given `id_root_reference`
+ * is tagged for override, and its newly created override will be used as hierarchy root. Must be
+ * NULL if `id_hierarchy_root` is not NULL.
  *
  * \param do_no_main: Create the new override data outside of Main database.
  * Used for resyncing of linked overrides.
@@ -103,6 +109,7 @@ bool BKE_lib_override_library_create_from_tag(struct Main *bmain,
                                               struct Library *owner_library,
                                               const struct ID *id_root_reference,
                                               struct ID *id_hierarchy_root,
+                                              const struct ID *id_hierarchy_root_reference,
                                               bool do_no_main);
 /**
  * Advanced 'smart' function to create fully functional overrides.
@@ -119,11 +126,18 @@ bool BKE_lib_override_library_create_from_tag(struct Main *bmain,
  * \param owner_library: the library in which the overrides should be created. Besides versioning
  * and resync code path, this should always be NULL (i.e. the local .blend file).
  *
- * \param id_root: The root ID to create an override from.
+ * \param id_root_reference: The linked root ID to create an override from. May be a sub-root of
+ * the overall hierarchy, in which case calling code is expected to have already tagged required
+ * 'path' of IDs leading from the given `id_hierarchy_root` to the given `id_root`.
+ *
+ * \param id_hierarchy_root_reference: The ID to be used a hierarchy root of the overrides to be
+ * created. Can be either the linked root ID of the whole override hierarchy, (typically the same
+ * as `id_root`, unless a sub-part only of the hierarchy is overridden), or the already existing
+ * override hierarchy root if part of the hierarchy is already overridden.
  *
- * \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 id_instance_hint: Some ID used as hint/reference 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.
  *
@@ -133,8 +147,9 @@ bool BKE_lib_override_library_create(struct Main *bmain,
                                      struct Scene *scene,
                                      struct ViewLayer *view_layer,
                                      struct Library *owner_library,
-                                     struct ID *id_root,
-                                     struct ID *id_reference,
+                                     struct ID *id_root_reference,
+                                     struct ID *id_hierarchy_root_reference,
+                                     struct ID *id_instance_hint,
                                      struct ID **r_id_root_override);
 /**
  * Create a library override template.
diff --git a/source/blender/blenkernel/intern/lib_override.c b/source/blender/blenkernel/intern/lib_override.c
index d9418d7ec03..922c1beda38 100644
--- a/source/blender/blenkernel/intern/lib_override.c
+++ b/source/blender/blenkernel/intern/lib_override.c
@@ -321,17 +321,36 @@ ID *BKE_lib_override_library_create_from_id(Main *bmain,
   return local_id;
 }
 
+/* TODO: Make this static local function instead? API is becoming complex, and it's not used
+ * outside of this file anyway. */
 bool BKE_lib_override_library_create_from_tag(Main *bmain,
                                               Library *owner_library,
                                               const ID *id_root_reference,
                                               ID *id_hierarchy_root,
+                                              const ID *id_hierarchy_root_reference,
                                               const bool do_no_main)
 {
-  BLI_assert(id_root_reference != NULL);
-  BLI_assert(id_hierarchy_root != NULL || (id_root_reference->tag & LIB_TAG_DOIT) != 0);
-  BLI_assert(id_hierarchy_root == NULL ||
-             (ID_IS_OVERRIDE_LIBRARY_REAL(id_hierarchy_root) &&
-              id_hierarchy_root->override_library->reference == id_root_reference));
+  BLI_assert(id_root_reference != NULL && ID_IS_LINKED(id_root_reference));
+  /* If we do not have any hierarchy root given, then the root reference must be tagged for
+   * override. */
+  BLI_assert(id_hierarchy_root != NULL || id_hierarchy_root_reference != NULL ||
+             (id_root_reference->tag & LIB_TAG_DOIT) != 0);
+  /* At least one of the hierarchy root pointers must be NULL, passing both is useless and can
+   * create confusion. */
+  BLI_assert(ELEM(NULL, id_hierarchy_root, id_hierarchy_root_reference));
+
+  if (id_hierarchy_root != NULL) {
+    /* If the hierarchy root is given, it must be a valid existing override (used during partial
+     * resync process mainly). */
+    BLI_assert((ID_IS_OVERRIDE_LIBRARY_REAL(id_hierarchy_root) &&
+                id_hierarchy_root->override_library->reference->lib == id_root_reference->lib));
+  }
+  if (!ELEM(id_hierarchy_root_reference, NULL, id_root_reference)) {
+    /* If the reference hierarchy root is given, it must be from the same library as the reference
+     * root, and also tagged for override. */
+    BLI_assert((id_hierarchy_root_reference->lib == id_root_reference->lib &&
+                (id_hierarchy_root_reference->tag & LIB_TAG_DOIT) != 0));
+  }
 
   const Library *reference_library = id_root_reference->lib;
 
@@ -387,7 +406,12 @@ bool BKE_lib_override_library_create_from_tag(Main *bmain,
   /* Only remap new local ID's pointers, we don't want to force our new overrides onto our whole
    * existing linked IDs usages. */
   if (success) {
-    if (id_root_reference->newid != NULL) {
+    if (id_hierarchy_root_reference != NULL) {
+      id_hierarchy_root = id_hierarchy_root_reference->newid;
+    }
+    else if (id_root_reference->newid != NULL &&
+             (id_hierarchy_root == NULL ||
+              id_hierarchy_root->override_library->reference == id_root_reference)) {
       id_hierarchy_root = id_root_reference->newid;
     }
     BLI_assert(id_hierarchy_root != NULL);
@@ -887,12 +911,13 @@ static void lib_override_overrides_group_tag(LibOverrideGroupTagData *data)
 static bool lib_override_library_create_do(Main *bmain,
                                            Scene *scene,
                                            Library *owner_library,
-                                           ID *id_root)
+                                           ID *id_root_reference,
+                                           ID *id_hierarchy_root_reference)
 {
   BKE_main_relations_create(bmain, 0);
   LibOverrideGroupTagData data = {.bmain = bmain,
                                   .scene = scene,
-                                  .id_root = id_root,
+                                  .id_root = id_root_reference,
                                   .tag = LIB_TAG_DOIT,
                                   .missing_tag = LIB_TAG_MISSING,
                                   .is_override = false,
@@ -906,8 +931,18 @@ static bool lib_override_library_create_do(Main *bmain,
   BKE_main_relations_free(bmain);
   lib_override_group_tag_data_clear(&data);
 
-  const bool success = BKE_lib_override_library_create_from_tag(
-      bmain, owner_library, id_root, NULL, false);
+  bool success = false;
+  if (id_hierarchy_root_reference->lib != id_root_reference->lib) {
+    BLI_assert(ID_IS_OVERRIDE_LIBRARY_REAL(id_hierarchy_root_reference));
+    BLI_assert(id_hierarchy_root_reference->override_library->reference->lib ==
+               id_root_reference->lib);
+    success = BKE_lib_override_library_create_from_tag(
+        bmain, owner_library, id_root_reference, id_hierarchy_root_reference, NULL, false);
+  }
+  else {
+    success = BKE_lib_override_library_create_from_tag(
+        bmain, owner_library, id_root_reference, NULL, id_hierarchy_root_reference, false);
+  }
 
   return success;
 }
@@ -917,7 +952,7 @@ static void lib_override_library_create_post_process(Main *bmain,
                                                      ViewLayer *view_layer,
                                                      const Library *owner_library,
                                                      ID *id_root,
-                                                     ID *id_reference,
+                                                     ID *id_instance_hint,
                                                      Collection *residual_storage,
                                                      const bool is_resync)
 {
@@ -941,8 +976,8 @@ static void lib_override_library_create_post_process(Main *bmain,
       (!ID_IS_LINKED(id_root->newid) || id_root->newid->lib == owner_library)) {
     switch (GS(id_root->name)) {
       case ID_GR: {
-        Object *ob_reference = id_reference != NULL && GS(id_reference->name) == ID_OB ?
-                                   (Object *)id_reference :
+        Object *ob_reference = id_instance_hint != NULL && GS(id_instance_hint->name) == ID_OB ?
+                                   (Object *)id_instance_hint :
                                    NULL;
         Collection *collection_new = ((Collection *)id_root->newid);
         if (is_resync && BKE_collection_is_in_scene(collection_new)) {
@@ -951,10 +986,10 @@ static void lib_override_library_create_post_process(Main *bmain,
         if (ob_reference != NULL) {
           BKE_collection_add_from_object(bmain, scene, ob_reference, collection_new);
         }
-        else if (id_reference != NULL) {
-          BLI_assert(GS(id_reference->name) == ID_GR);
+        else if (id_instance_hint != NULL) {
+          BLI_assert(GS(id_instance_hint->name) == ID_GR);
           BKE_collection_add_from_collection(
-              bmain, scene, ((Collection *)id_reference), collection_new);
+              bmain, scene, ((Collection *)id_instance_hint), collection_new);
         }
         else {
           BKE_collection_add_from_collection(
@@ -1047,26 +1082,32 @@ bool BKE_lib_override_library_create(Main *bmain,
                                      Scene *scene,
                                      ViewLayer *view_layer,
                                      Library *owner_library,
-                                     ID *id_root,
-                                     ID *id_reference,
+                                     ID *id_root_reference,
+                                     ID *id_hierarchy_root_reference,
+                                     ID *id_instance_hint,
                                      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, scene, owner_library, id_root);
+  if (id_hierarchy_root_reference == NULL) {
+    id_hierarchy_root_reference = id_root_reference;
+  }
+
+  const bool success = lib_override_library_create_do(
+      bmain, scene, owner_library, id_root_reference, id_hierarchy_root_reference);
 
   if (!success) {
     return success;
   }
 
   if (r_id_root_override != NULL) {
-    *r_id_root_override = id_root->newid;
+    *r_id_root_override = id_root_reference->newid;
   }
 
   lib_override_library_create_post_process(
-      bmain, scene, view_layer, owner_library, id_root, id_reference, NULL, false);
+      bmain, scene, view_layer, owner_library, id_root_reference, id_instance_hint, NULL, false);
 
   /* Cleanup. */
   BKE_main_id_newptr_and_tag_clear(bmain);
@@ -1527,7 +1568,7 @@ static bool lib_override_library_resync(Main *bmain,
    * override IDs (including within the old overrides themselves, since those are tagged too
    * above). */
   const bool success = BKE_lib_override_library_create_from_tag(
-      bmain, NULL, id_root_reference, id_root->override_library->hierarchy_root, true);
+      bmain, NULL, id_root_reference, id_root->override_library->hierarchy_root, NULL, true);
 
   if (!success) {
     BLI_ghash_free(linkedref_to_old_override, NULL, NULL);
diff --git a/source/blender/blenkernel/intern/lib_override_proxy_conversion.c b/source/blender/blenkernel/intern/lib_override_proxy_conversion.c
index 809235ad24c..dc164313788 100644
--- a/source/blender/blenkernel/intern/lib_override_proxy_conversion.c
+++ b/source/blender/blenkernel/intern/lib_override_proxy_conversion.c
@@ -42,7 +42,7 @@ bool BKE_lib_override_library_proxy_convert(Main *bmain,
   const bool is_override_instancing_object = ob_proxy_group != NULL;
   ID *id_root = is_override_instancing_object ? &ob_proxy_group->instance_collection->id :
                                                 &ob_proxy->proxy->id;
-  ID *id_reference = is_override_instancing_object ? &ob_proxy_group->id : &ob_proxy->id;
+  ID *id_instance_hint = is_override_instancing_object ? &ob_proxy_group->id : &ob_proxy->id;
 
   /* In some cases the instance collection of a proxy object may be local (see e.g. T83875). Not
    * sure this is a valid state, but for now just abort the overriding process. */
@@ -81,7 +81,7 @@ bool BKE_lib_override_library_proxy_convert(Main *bmain,
   FOREACH_MAIN_ID_END;
 
   return BKE_lib_override_library_create(
-      bmain, scene, view_layer, ob_proxy->id.lib, id_root, id_reference, NULL);
+      bmain, scene, view_layer, ob_proxy->id.lib, id_root, id_root, id_instance_hint, NULL);
 }
 
 static void lib_override_library_proxy_convert_do(Main *bmain,