Merge branch 'master' into soc-2021-uv-edge-select-supportsoc-2021-uv-edge-select-support

1 files changed, 182 insertions, 269 deletions

diff --git a/source/blender/blenkernel/intern/object.cc b/source/blender/blenkernel/intern/object.cc
index d650003afe2..7fec91ed65a 100644
--- a/source/blender/blenkernel/intern/object.cc
+++ b/source/blender/blenkernel/intern/object.cc
@@ -83,6 +83,7 @@
 #include "BKE_animsys.h"
 #include "BKE_armature.h"
 #include "BKE_asset.h"
+#include "BKE_bpath.h"
 #include "BKE_camera.h"
 #include "BKE_collection.h"
 #include "BKE_constraint.h"
@@ -548,6 +549,67 @@ static void object_foreach_id(ID *id, LibraryForeachIDData *data)
   }
 }
 
+static void object_foreach_path_pointcache(ListBase *ptcache_list,
+                                           BPathForeachPathData *bpath_data)
+{
+  for (PointCache *cache = (PointCache *)ptcache_list->first; cache != nullptr;
+       cache = cache->next) {
+    if (cache->flag & PTCACHE_DISK_CACHE) {
+      BKE_bpath_foreach_path_fixed_process(bpath_data, cache->path);
+    }
+  }
+}
+
+static void object_foreach_path(ID *id, BPathForeachPathData *bpath_data)
+{
+  Object *ob = reinterpret_cast<Object *>(id);
+
+  LISTBASE_FOREACH (ModifierData *, md, &ob->modifiers) {
+    /* TODO: Move that to #ModifierTypeInfo. */
+    switch (md->type) {
+      case eModifierType_Fluidsim: {
+        FluidsimModifierData *fluidmd = reinterpret_cast<FluidsimModifierData *>(md);
+        if (fluidmd->fss) {
+          BKE_bpath_foreach_path_fixed_process(bpath_data, fluidmd->fss->surfdataPath);
+        }
+        break;
+      }
+      case eModifierType_Fluid: {
+        FluidModifierData *fmd = reinterpret_cast<FluidModifierData *>(md);
+        if (fmd->type & MOD_FLUID_TYPE_DOMAIN && fmd->domain) {
+          BKE_bpath_foreach_path_fixed_process(bpath_data, fmd->domain->cache_directory);
+        }
+        break;
+      }
+      case eModifierType_Cloth: {
+        ClothModifierData *clmd = reinterpret_cast<ClothModifierData *>(md);
+        object_foreach_path_pointcache(&clmd->ptcaches, bpath_data);
+        break;
+      }
+      case eModifierType_Ocean: {
+        OceanModifierData *omd = reinterpret_cast<OceanModifierData *>(md);
+        BKE_bpath_foreach_path_fixed_process(bpath_data, omd->cachepath);
+        break;
+      }
+      case eModifierType_MeshCache: {
+        MeshCacheModifierData *mcmd = reinterpret_cast<MeshCacheModifierData *>(md);
+        BKE_bpath_foreach_path_fixed_process(bpath_data, mcmd->filepath);
+        break;
+      }
+      default:
+        break;
+    }
+  }
+
+  if (ob->soft != nullptr) {
+    object_foreach_path_pointcache(&ob->soft->shared->ptcaches, bpath_data);
+  }
+
+  LISTBASE_FOREACH (ParticleSystem *, psys, &ob->particlesystem) {
+    object_foreach_path_pointcache(&psys->ptcaches, bpath_data);
+  }
+}
+
 static void write_fmaps(BlendWriter *writer, ListBase *fbase)
 {
   LISTBASE_FOREACH (bFaceMap *, fmap, fbase) {
@@ -1258,6 +1320,7 @@ IDTypeInfo IDType_ID_OB = {
     /* name_plural */ "objects",
     /* translation_context */ BLT_I18NCONTEXT_ID_OBJECT,
     /* flags */ 0,
+    /* asset_type_info */ &AssetType_OB,
 
     /* init_data */ object_init_data,
     /* copy_data */ object_copy_data,
@@ -1265,6 +1328,7 @@ IDTypeInfo IDType_ID_OB = {
     /* make_local */ object_make_local,
     /* foreach_id */ object_foreach_id,
     /* foreach_cache */ nullptr,
+    /* foreach_path */ object_foreach_path,
     /* owner_get */ nullptr,
 
     /* blend_write */ object_blend_write,
@@ -1275,8 +1339,6 @@ IDTypeInfo IDType_ID_OB = {
     /* blend_read_undo_preserve */ nullptr,
 
     /* lib_override_apply_post */ object_lib_override_apply_post,
-
-    /* asset_type_info */ &AssetType_OB,
 };
 
 void BKE_object_workob_clear(Object *workob)
@@ -1394,12 +1456,6 @@ void BKE_object_modifier_gpencil_hook_reset(Object *ob, HookGpencilModifierData
   }
 }
 
-/**
- * Set the object's active modifier.
- *
- * \param md: If nullptr, only clear the active modifier, otherwise
- * it must be in the #Object.modifiers list.
- */
 void BKE_object_modifier_set_active(Object *ob, ModifierData *md)
 {
   LISTBASE_FOREACH (ModifierData *, md_iter, &ob->modifiers) {
@@ -1434,9 +1490,6 @@ ModifierData *BKE_object_active_modifier(const Object *ob)
   return nullptr;
 }
 
-/**
- * \return True if the object's type supports regular modifiers (not grease pencil modifiers).
- */
 bool BKE_object_supports_modifiers(const Object *ob)
 {
   return (
@@ -1514,17 +1567,6 @@ static ParticleSystem *object_copy_modifier_particle_system_ensure(Main *bmain,
   return psys_dst;
 }
 
-/**
- * Copy a single modifier.
- *
- * \note **Do not** use this function to copy a whole modifier stack (see note below too). Use
- * `BKE_object_modifier_stack_copy` instead.
- *
- * \note Complex modifiers relaying on other data (like e.g. dynamic paint or fluid using particle
- * systems) are not always 100% 'correctly' copied here, since we have to use heuristics to decide
- * which particle system to use or add in `ob_dst`, and it's placement in the stack, etc. If used
- * more than once, this function should preferably be called in stack order.
- */
 bool BKE_object_copy_modifier(
     Main *bmain, Scene *scene, Object *ob_dst, const Object *ob_src, ModifierData *md_src)
 {
@@ -1624,12 +1666,6 @@ bool BKE_object_copy_modifier(
   return true;
 }
 
-/**
- * Copy a single GPencil modifier.
- *
- * \note **Do not** use this function to copy a whole modifier stack. Use
- * `BKE_object_modifier_stack_copy` instead.
- */
 bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, GpencilModifierData *gmd_src)
 {
   BLI_assert(ob_dst->type == OB_GPENCIL);
@@ -1647,15 +1683,6 @@ bool BKE_object_copy_gpencil_modifier(struct Object *ob_dst, GpencilModifierData
   return true;
 }
 
-/**
- * Copy the whole stack of modifiers from one object into another.
- *
- * \warning **Does not** clear modifier stack and related data (particle systems, soft-body,
- * etc.) in `ob_dst`, if needed calling code must do it.
- *
- * \param do_copy_all: If true, even modifiers that should not support copying (like Hook one)
- * will be duplicated.
- */
 bool BKE_object_modifier_stack_copy(Object *ob_dst,
                                     const Object *ob_src,
                                     const bool do_copy_all,
@@ -1804,9 +1831,6 @@ static void object_update_from_subsurf_ccg(Object *object)
   subdiv_ccg->dirty.hidden = false;
 }
 
-/**
- * Assign #Object.data after modifier stack evaluation.
- */
 void BKE_object_eval_assign_data(Object *object_eval, ID *data_eval, bool is_owned)
 {
   BLI_assert(object_eval->id.tag & LIB_TAG_COPIED_ON_WRITE);
@@ -1836,9 +1860,6 @@ void BKE_object_eval_assign_data(Object *object_eval, ID *data_eval, bool is_own
   object_eval->runtime.geometry_set_eval = nullptr;
 }
 
-/**
- * Free data derived from mesh, called when mesh changes or is freed.
- */
 void BKE_object_free_derived_caches(Object *ob)
 {
   MEM_SAFE_FREE(ob->runtime.bb);
@@ -1933,9 +1954,6 @@ void BKE_object_free_caches(Object *object)
   }
 }
 
-/**
- * Actual check for internal data, not context or flags.
- */
 bool BKE_object_is_in_editmode(const Object *ob)
 {
   if (ob->data == nullptr) {
@@ -2085,9 +2103,6 @@ bool BKE_object_is_mode_compat(const struct Object *ob, eObjectMode object_mode)
   return ((ob->mode == object_mode) || (ob->mode & object_mode) != 0);
 }
 
-/**
- * Return which parts of the object are visible, as evaluated by depsgraph
- */
 int BKE_object_visibility(const Object *ob, const int dag_eval_mode)
 {
   if ((ob->base_flag & BASE_VISIBLE_DEPSGRAPH) == 0) {
@@ -2255,9 +2270,6 @@ void *BKE_object_obdata_add_from_type(Main *bmain, int type, const char *name)
   }
 }
 
-/**
- * Return -1 on failure.
- */
 int BKE_object_obdata_to_type(const ID *id)
 {
   /* Keep in sync with #OB_DATA_SUPPORT_ID macro. */
@@ -2293,9 +2305,6 @@ int BKE_object_obdata_to_type(const ID *id)
   }
 }
 
-/**
- * More general add: creates minimum required data, but without vertices etc.
- */
 Object *BKE_object_add_only_object(Main *bmain, int type, const char *name)
 {
   if (!name) {
@@ -2325,14 +2334,6 @@ static Object *object_add_common(Main *bmain, ViewLayer *view_layer, int type, c
   return ob;
 }
 
-/**
- * General add: to scene, with layer from area and default name
- *
- * Object is added to the active #Collection.
- * If there is no linked collection to the active #ViewLayer we create a new one.
- *
- * \note Creates minimum required data, but without vertices etc.
- */
 Object *BKE_object_add(Main *bmain, ViewLayer *view_layer, int type, const char *name)
 {
   Object *ob = object_add_common(bmain, view_layer, type, name);
@@ -2346,11 +2347,6 @@ Object *BKE_object_add(Main *bmain, ViewLayer *view_layer, int type, const char
   return ob;
 }
 
-/**
- * Add a new object, using another one as a reference
- *
- * \param ob_src: object to use to determine the collections of the new object.
- */
 Object *BKE_object_add_from(
     Main *bmain, Scene *scene, ViewLayer *view_layer, int type, const char *name, Object *ob_src)
 {
@@ -2363,15 +2359,6 @@ Object *BKE_object_add_from(
   return ob;
 }
 
-/**
- * Add a new object, but assign the given data-block as the `ob->data`
- * for the newly created object.
- *
- * \param data: The data-block to assign as `ob->data` for the new object.
- * This is assumed to be of the correct type.
- * \param do_id_user: If true, #id_us_plus() will be called on data when
- * assigning it to the object.
- */
 Object *BKE_object_add_for_data(
     Main *bmain, ViewLayer *view_layer, int type, const char *name, ID *data, bool do_id_user)
 {
@@ -2623,9 +2610,6 @@ Object *BKE_object_pose_armature_get_visible(Object *ob, ViewLayer *view_layer,
   return nullptr;
 }
 
-/**
- * Access pose array with special check to get pose object when in weight paint mode.
- */
 Object **BKE_object_pose_array_get_ex(ViewLayer *view_layer,
                                       View3D *v3d,
                                       uint *r_objects_len,
@@ -2720,17 +2704,6 @@ void BKE_object_transform_copy(Object *ob_tar, const Object *ob_src)
   copy_v3_v3(ob_tar->scale, ob_src->scale);
 }
 
-/**
- * Perform deep-copy of object and its 'children' data-blocks (obdata, materials, actions, etc.).
- *
- * \param dupflag: Controls which sub-data are also duplicated
- * (see #eDupli_ID_Flags in DNA_userdef_types.h).
- *
- * \note This function does not do any remapping to new IDs, caller must do it
- * (\a #BKE_libblock_relink_to_newid()).
- * \note Caller MUST free \a newid pointers itself (#BKE_main_id_newptr_and_tag_clear()) and call
- * updates of DEG too (#DAG_relations_tag_update()).
- */
 Object *BKE_object_duplicate(Main *bmain, Object *ob, uint dupflag, uint duplicate_options)
 {
   const bool is_subprocess = (duplicate_options & LIB_ID_DUPLICATE_IS_SUBPROCESS) != 0;
@@ -2900,17 +2873,11 @@ Object *BKE_object_duplicate(Main *bmain, Object *ob, uint dupflag, uint duplica
   return obn;
 }
 
-/**
- * Returns true if the Object is from an external blend file (libdata).
- */
 bool BKE_object_is_libdata(const Object *ob)
 {
   return (ob && ID_IS_LINKED(ob));
 }
 
-/**
- * Returns true if the Object data is from an external blend file (libdata).
- */
 bool BKE_object_obdata_is_libdata(const Object *ob)
 {
   /* Linked objects with local obdata are forbidden! */
@@ -2974,12 +2941,6 @@ void BKE_object_copy_proxy_drivers(Object *ob, Object *target)
   }
 }
 
-/**
- * Proxy rule:
- * - lib_object->proxy_from == the one we borrow from, set temporally while object_update.
- * - local_object->proxy == pointer to library object, saved in files and read.
- * - local_object->proxy_group == pointer to collection dupli-object, saved in files and read.
- */
 void BKE_object_make_proxy(Main *bmain, Object *ob, Object *target, Object *cob)
 {
   /* paranoia checks */
@@ -3079,10 +3040,6 @@ void BKE_object_make_proxy(Main *bmain, Object *ob, Object *target, Object *cob)
   ob->dt = target->dt;
 }
 
-/**
- * Use with newly created objects to set their size
- * (used to apply scene-scale).
- */
 void BKE_object_obdata_size_init(struct Object *ob, const float size)
 {
   /* apply radius as a scale to types that support it */
@@ -3721,12 +3678,6 @@ void BKE_object_where_is_calc_time(Depsgraph *depsgraph, Scene *scene, Object *o
   object_where_is_calc_ex(depsgraph, scene, ob, ctime, nullptr, nullptr);
 }
 
-/**
- * Calculate object transformation matrix without recalculating dependencies and
- * constraints -- assume dependencies are already solved by depsgraph.
- * No changes to object and its parent would be done.
- * Used for bundles orientation in 3d space relative to parented blender camera.
- */
 void BKE_object_where_is_calc_mat4(Object *ob, float r_obmat[4][4])
 {
   if (ob->parent) {
@@ -3750,14 +3701,6 @@ void BKE_object_where_is_calc(Depsgraph *depsgraph, Scene *scene, Object *ob)
   object_where_is_calc_ex(depsgraph, scene, ob, ctime, nullptr, nullptr);
 }
 
-/**
- * For calculation of the inverse parent transform, only used for editor.
- *
- * It assumes the object parent is already in the depsgraph.
- * Otherwise, after changing ob->parent you need to call:
- * - #DEG_relations_tag_update(bmain);
- * - #BKE_scene_graph_update_tagged(depsgraph, bmain);
- */
 void BKE_object_workob_calc_parent(Depsgraph *depsgraph, Scene *scene, Object *ob, Object *workob)
 {
   BKE_object_workob_clear(workob);
@@ -3789,16 +3732,6 @@ void BKE_object_workob_calc_parent(Depsgraph *depsgraph, Scene *scene, Object *o
   BKE_object_where_is_calc(depsgraph, scene, workob);
 }
 
-/**
- * Applies the global transformation \a mat to the \a ob using a relative parent space if
- * supplied.
- *
- * \param mat: the global transformation mat that the object should be set object to.
- * \param parent: the parent space in which this object will be set relative to
- * (should probably always be parent_eval).
- * \param use_compat: true to ensure that rotations are set using the
- * min difference between the old and new orientation.
- */
 void BKE_object_apply_mat4_ex(Object *ob,
                               const float mat[4][4],
                               Object *parent,
@@ -3842,9 +3775,6 @@ void BKE_object_apply_mat4_ex(Object *ob,
   /* BKE_object_mat3_to_rot handles delta rotations */
 }
 
-/**
- * XXX: should be removed after COW operators port to use BKE_object_apply_mat4_ex directly.
- */
 void BKE_object_apply_mat4(Object *ob,
                            const float mat[4][4],
                            const bool use_compat,
@@ -3859,7 +3789,7 @@ void BKE_object_apply_mat4(Object *ob,
 /** \name Object Bounding Box API
  * \{ */
 
-BoundBox *BKE_boundbox_alloc_unit(void)
+BoundBox *BKE_boundbox_alloc_unit()
 {
   const float min[3] = {-1.0f, -1.0f, -1.0f}, max[3] = {1.0f, 1.0f, 1.0f};
 
@@ -3948,9 +3878,6 @@ BoundBox *BKE_object_boundbox_get(Object *ob)
   return bb;
 }
 
-/**
- * Use this to temporally disable/enable bound-box.
- */
 void BKE_object_boundbox_flag(Object *ob, int flag, const bool set)
 {
   BoundBox *bb = BKE_object_boundbox_get(ob);
@@ -3984,6 +3911,37 @@ void BKE_object_boundbox_calc_from_mesh(Object *ob, const Mesh *me_eval)
   ob->runtime.bb->flag &= ~BOUNDBOX_DIRTY;
 }
 
+bool BKE_object_boundbox_calc_from_evaluated_geometry(Object *ob)
+{
+  blender::float3 min, max;
+  INIT_MINMAX(min, max);
+
+  if (ob->runtime.geometry_set_eval) {
+    ob->runtime.geometry_set_eval->compute_boundbox_without_instances(&min, &max);
+  }
+  else if (const Mesh *mesh_eval = BKE_object_get_evaluated_mesh(ob)) {
+    if (!BKE_mesh_wrapper_minmax(mesh_eval, min, max)) {
+      return false;
+    }
+  }
+  else if (ob->runtime.curve_cache) {
+    BKE_displist_minmax(&ob->runtime.curve_cache->disp, min, max);
+  }
+  else {
+    return false;
+  }
+
+  if (ob->runtime.bb == nullptr) {
+    ob->runtime.bb = (BoundBox *)MEM_callocN(sizeof(BoundBox), __func__);
+  }
+
+  BKE_boundbox_init_from_minmax(ob->runtime.bb, min, max);
+
+  ob->runtime.bb->flag &= ~BOUNDBOX_DIRTY;
+
+  return true;
+}
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
@@ -4009,14 +3967,6 @@ void BKE_object_dimensions_get(Object *ob, float r_vec[3])
   }
 }
 
-/**
- * The original scale and object matrix can be passed in so any difference
- * of the objects matrix and the final matrix can be accounted for,
- * typically this caused by parenting, constraints or delta-scale.
- *
- * Re-using these values from the object causes a feedback loop
- * when multiple values are modified at once in some situations. see: T69536.
- */
 void BKE_object_dimensions_set_ex(Object *ob,
                                   const float value[3],
                                   int axis_mask,
@@ -4341,6 +4291,12 @@ void BKE_scene_foreach_display_point(Depsgraph *depsgraph,
   DEG_OBJECT_ITER_END;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Transform Channels (Backup/Restore)
+ * \{ */
+
 /**
  * See struct members from #Object in DNA_object_types.h
  */
@@ -4401,17 +4357,11 @@ void BKE_object_tfm_restore(Object *ob, void *obtfm_pt)
   copy_m4_m4(ob->imat, obtfm->imat);
 }
 
-bool BKE_object_parent_loop_check(const Object *par, const Object *ob)
-{
-  /* test if 'ob' is a parent somewhere in par's parents */
-  if (par == nullptr) {
-    return false;
-  }
-  if (ob == par) {
-    return true;
-  }
-  return BKE_object_parent_loop_check(par->parent, ob);
-}
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Evaluation/Update API
+ * \{ */
 
 static void object_handle_update_proxy(Depsgraph *depsgraph,
                                        Scene *scene,
@@ -4435,19 +4385,6 @@ static void object_handle_update_proxy(Depsgraph *depsgraph,
   }
 }
 
-/**
- * Proxy rule:
- * - lib_object->proxy_from == the one we borrow from, only set temporal and cleared here.
- * - local_object->proxy    == pointer to library object, saved in files and read.
- *
- * Function below is polluted with proxy exceptions, cleanup will follow!
- *
- * The main object update call, for object matrix, constraints, keys and displist (modifiers)
- * requires flags to be set!
- *
- * Ideally we shouldn't have to pass the rigid body world,
- * but need bigger restructuring to avoid id.
- */
 void BKE_object_handle_update_ex(Depsgraph *depsgraph,
                                  Scene *scene,
                                  Object *ob,
@@ -4502,13 +4439,6 @@ void BKE_object_handle_update_ex(Depsgraph *depsgraph,
   object_handle_update_proxy(depsgraph, scene, ob, do_proxy_update);
 }
 
-/**
- * \warning "scene" here may not be the scene object actually resides in.
- * When dealing with background-sets, "scene" is actually the active scene.
- * e.g. "scene" <-- set 1 <-- set 2 ("ob" lives here) <-- set 3 <-- ... <-- set n
- * rigid bodies depend on their world so use #BKE_object_handle_update_ex()
- * to also pass along the current rigid body world.
- */
 void BKE_object_handle_update(Depsgraph *depsgraph, Scene *scene, Object *ob)
 {
   BKE_object_handle_update_ex(depsgraph, scene, ob, nullptr, true);
@@ -4521,7 +4451,7 @@ void BKE_object_sculpt_data_create(Object *ob)
   ob->sculpt->mode_type = (eObjectMode)ob->mode;
 }
 
-bool BKE_object_obdata_texspace_get(Object *ob, short **r_texflag, float **r_loc, float **r_size)
+bool BKE_object_obdata_texspace_get(Object *ob, char **r_texflag, float **r_loc, float **r_size)
 {
 
   if (ob->data == nullptr) {
@@ -4566,17 +4496,17 @@ bool BKE_object_obdata_texspace_get(Object *ob, short **r_texflag, float **r_loc
   return true;
 }
 
-/** Get evaluated mesh for given object. */
 Mesh *BKE_object_get_evaluated_mesh(const Object *object)
 {
   /* First attempt to retrieve the evaluated mesh from the evaluated geometry set. Most
    * object types either store it there or add a reference to it if it's owned elsewhere. */
   GeometrySet *geometry_set_eval = object->runtime.geometry_set_eval;
   if (geometry_set_eval) {
-    /* Some areas expect to be able to modify the evaluated mesh. Theoretically this should be
-     * avoided, or at least protected with a lock, so a const mesh could be returned from this
-     * function. */
-    Mesh *mesh = geometry_set_eval->get_mesh_for_write();
+    /* Some areas expect to be able to modify the evaluated mesh in limited ways. Theoretically
+     * this should be avoided, or at least protected with a lock, so a const mesh could be returned
+     * from this function. We use a const_cast instead of #get_mesh_for_write, because that might
+     * result in a copy of the mesh when it is shared. */
+    Mesh *mesh = const_cast<Mesh *>(geometry_set_eval->get_mesh_for_read());
     if (mesh) {
       return mesh;
     }
@@ -4593,13 +4523,6 @@ Mesh *BKE_object_get_evaluated_mesh(const Object *object)
   return nullptr;
 }
 
-/**
- * Get mesh which is not affected by modifiers:
- * - For original objects it will be same as `object->data`, and it is a mesh
- *   which is in the corresponding #Main.
- * - For copied-on-write objects it will give pointer to a copied-on-write
- *   mesh which corresponds to original object's mesh.
- */
 Mesh *BKE_object_get_pre_modified_mesh(const Object *object)
 {
   if (object->type == OB_MESH && object->runtime.data_orig != nullptr) {
@@ -4615,12 +4538,6 @@ Mesh *BKE_object_get_pre_modified_mesh(const Object *object)
   return (Mesh *)object->data;
 }
 
-/**
- * Get a mesh which corresponds to the very original mesh from #Main.
- * - For original objects it will be object->data.
- * - For evaluated objects it will be same mesh as corresponding original
- *   object uses as data.
- */
 Mesh *BKE_object_get_original_mesh(const Object *object)
 {
   Mesh *result = nullptr;
@@ -4669,6 +4586,12 @@ Lattice *BKE_object_get_evaluated_lattice(const Object *object)
   return lt_eval;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Point Cache
+ * \{ */
+
 static int pc_cmp(const void *a, const void *b)
 {
   const LinkData *ad = (const LinkData *)a, *bd = (const LinkData *)b;
@@ -4733,6 +4656,8 @@ void BKE_object_delete_ptcache(Object *ob, int index)
   BLI_freelinkN(&ob->pc_ids, link);
 }
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name Object Data Shape Key Insert
  * \{ */
@@ -4971,6 +4896,22 @@ bool BKE_object_shapekey_remove(Main *bmain, Object *ob, KeyBlock *kb)
 
 /** \} */
 
+/* -------------------------------------------------------------------- */
+/** \name Object Query API
+ * \{ */
+
+bool BKE_object_parent_loop_check(const Object *par, const Object *ob)
+{
+  /* test if 'ob' is a parent somewhere in par's parents */
+  if (par == nullptr) {
+    return false;
+  }
+  if (ob == par) {
+    return true;
+  }
+  return BKE_object_parent_loop_check(par->parent, ob);
+}
+
 bool BKE_object_flag_test_recursive(const Object *ob, short flag)
 {
   if (ob->flag & flag) {
@@ -4993,10 +4934,6 @@ bool BKE_object_is_child_recursive(const Object *ob_parent, const Object *ob_chi
   return false;
 }
 
-/**
- * Most important if this is modified it should _always_ return true, in certain
- * cases false positives are hard to avoid (shape keys for example).
- */
 int BKE_object_is_modified(Scene *scene, Object *ob)
 {
   /* Always test on original object since evaluated object may no longer
@@ -5030,21 +4967,6 @@ int BKE_object_is_modified(Scene *scene, Object *ob)
   return flag;
 }
 
-/**
- * Check of objects moves in time.
- *
- * \note This function is currently optimized for usage in combination
- * with modifier deformation checks (#eModifierTypeType_OnlyDeform),
- * so modifiers can quickly check if their target objects moves
- * (causing deformation motion blur) or not.
- *
- * This makes it possible to give some degree of false-positives here,
- * but it's currently an acceptable tradeoff between complexity and check
- * speed. In combination with checks of modifier stack and real life usage
- * percentage of false-positives shouldn't be that high.
- *
- * \note This function does not consider physics systems.
- */
 bool BKE_object_moves_in_time(const Object *object, bool recurse_parent)
 {
   /* If object has any sort of animation data assume it is moving. */
@@ -5140,11 +5062,6 @@ static bool modifiers_has_animation_check(const Object *ob)
   return false;
 }
 
-/**
- * Test if object is affected by deforming modifiers (for motion blur). again
- * most important is to avoid false positives, this is to skip computations
- * and we can still if there was actual deformation afterwards.
- */
 int BKE_object_is_deform_modified(Scene *scene, Object *ob)
 {
   /* Always test on original object since evaluated object may no longer
@@ -5194,7 +5111,6 @@ int BKE_object_is_deform_modified(Scene *scene, Object *ob)
   return flag;
 }
 
-/** Return the number of scenes using (instantiating) that object in their collections. */
 int BKE_object_scenes_users_get(Main *bmain, Object *ob)
 {
   int num_scenes = 0;
@@ -5234,14 +5150,31 @@ MovieClip *BKE_object_movieclip_get(Scene *scene, Object *ob, bool use_default)
   return clip;
 }
 
+bool BKE_object_supports_material_slots(struct Object *ob)
+{
+  return ELEM(ob->type,
+              OB_MESH,
+              OB_CURVE,
+              OB_SURF,
+              OB_FONT,
+              OB_MBALL,
+              OB_HAIR,
+              OB_POINTCLOUD,
+              OB_VOLUME,
+              OB_GPENCIL);
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Runtime
+ * \{ */
+
 void BKE_object_runtime_reset(Object *object)
 {
   memset(&object->runtime, 0, sizeof(object->runtime));
 }
 
-/**
- * Reset all pointers which we don't want to be shared when copying the object.
- */
 void BKE_object_runtime_reset_on_copy(Object *object, const int UNUSED(flag))
 {
   Object_Runtime *runtime = &object->runtime;
@@ -5254,12 +5187,6 @@ void BKE_object_runtime_reset_on_copy(Object *object, const int UNUSED(flag))
   runtime->geometry_set_eval = nullptr;
 }
 
-/**
- * The function frees memory used by the runtime data, but not the runtime field itself.
- *
- * All runtime data is cleared to ensure it's not used again,
- * in keeping with other `_free_data(..)` functions.
- */
 void BKE_object_runtime_free_data(Object *object)
 {
   /* Currently this is all that's needed. */
@@ -5268,6 +5195,12 @@ void BKE_object_runtime_free_data(Object *object)
   BKE_object_runtime_reset(object);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Relationships
+ * \{ */
+
 /**
  * Find an associated armature object.
  */
@@ -5301,13 +5234,6 @@ static void obrel_list_add(LinkNode **links, Object *ob)
   ob->id.tag |= LIB_TAG_DOIT;
 }
 
-/**
- * Iterates over all objects of the given scene layer.
- * Depending on the #eObjectSet flag:
- * collect either #OB_SET_ALL, #OB_SET_VISIBLE or #OB_SET_SELECTED objects.
- * If #OB_SET_VISIBLE or#OB_SET_SELECTED are collected,
- * then also add related objects according to the given \a includeFilter.
- */
 LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer,
                                          eObjectSet objectSet,
                                          eObRelationTypes includeFilter)
@@ -5385,9 +5311,6 @@ LinkNode *BKE_object_relational_superset(struct ViewLayer *view_layer,
   return links;
 }
 
-/**
- * return all groups this object is a part of, caller must free.
- */
 struct LinkNode *BKE_object_groups(Main *bmain, Scene *scene, Object *ob)
 {
   LinkNode *collection_linknode = nullptr;
@@ -5408,15 +5331,12 @@ void BKE_object_groups_clear(Main *bmain, Scene *scene, Object *ob)
   }
 }
 
-/**
- * Return a KDTree_3d from the deformed object (in world-space).
- *
- * \note Only mesh objects currently support deforming, others are TODO.
- *
- * \param ob:
- * \param r_tot:
- * \return The kdtree or nullptr if it can't be created.
- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object KD-Tree
+ * \{ */
+
 KDTree_3d *BKE_object_as_kdtree(Object *ob, int *r_tot)
 {
   KDTree_3d *tree = nullptr;
@@ -5534,6 +5454,12 @@ KDTree_3d *BKE_object_as_kdtree(Object *ob, int *r_tot)
   return tree;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Modifier Utilities
+ * \{ */
+
 bool BKE_object_modifier_use_time(Scene *scene,
                                   Object *ob,
                                   ModifierData *md,
@@ -5679,10 +5605,6 @@ static void object_cacheIgnoreClear(Object *ob, int state)
   BLI_freelistN(&pidlist);
 }
 
-/**
- * \note this function should eventually be replaced by depsgraph functionality.
- * Avoid calling this in new code unless there is a very good reason for it!
- */
 bool BKE_object_modifier_update_subframe(Depsgraph *depsgraph,
                                          Scene *scene,
                                          Object *ob,
@@ -5786,9 +5708,6 @@ bool BKE_object_modifier_update_subframe(Depsgraph *depsgraph,
   return false;
 }
 
-/**
- * Updates select_id of all objects in the given \a bmain.
- */
 void BKE_object_update_select_id(struct Main *bmain)
 {
   Object *ob = (Object *)bmain->objects.first;
@@ -5799,6 +5718,12 @@ void BKE_object_update_select_id(struct Main *bmain)
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Conversion
+ * \{ */
+
 Mesh *BKE_object_to_mesh(Depsgraph *depsgraph, Object *object, bool preserve_all_data_layers)
 {
   BKE_object_to_mesh_clear(object);
@@ -5866,16 +5791,4 @@ void BKE_object_replace_data_on_shallow_copy(Object *ob, ID *new_data)
   ob->id.py_instance = nullptr;
 }
 
-bool BKE_object_supports_material_slots(struct Object *ob)
-{
-  return ELEM(ob->type,
-              OB_MESH,
-              OB_CURVE,
-              OB_SURF,
-              OB_FONT,
-              OB_MBALL,
-              OB_HAIR,
-              OB_POINTCLOUD,
-              OB_VOLUME,
-              OB_GPENCIL);
-}
+/** \} */