diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:19:15 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:38:48 +0300 |
commit | ffc4c126f5416b04a01653e7a03451797b98aba4 (patch) | |
tree | ac63d70d33aae5ab1666c9c2f62058c9c1eebd5c /source/blender/blenkernel/intern/object.cc | |
parent | f159d49f56cedccd509ee93f5a5fb51f4f39eeb8 (diff) |
Cleanup: move public doc-strings into headers for 'blenkernel'
- Added space below non doc-string comments to make it clear
these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.
Ref T92709
Diffstat (limited to 'source/blender/blenkernel/intern/object.cc')
-rw-r--r-- | source/blender/blenkernel/intern/object.cc | 234 |
1 files changed, 0 insertions, 234 deletions
diff --git a/source/blender/blenkernel/intern/object.cc b/source/blender/blenkernel/intern/object.cc index a73a8a75127..4327e7357d7 100644 --- a/source/blender/blenkernel/intern/object.cc +++ b/source/blender/blenkernel/intern/object.cc @@ -1456,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) { @@ -1496,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 ( @@ -1576,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) { @@ -1686,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); @@ -1709,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, @@ -1866,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); @@ -1898,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); @@ -1995,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) { @@ -2147,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) { @@ -2317,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. */ @@ -2355,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) { @@ -2387,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); @@ -2408,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) { @@ -2425,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) { @@ -2685,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, @@ -2782,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; @@ -2962,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! */ @@ -3036,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 */ @@ -3141,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 */ @@ -3783,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) { @@ -3812,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); @@ -3851,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, @@ -4010,9 +3881,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); @@ -4102,14 +3970,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, @@ -4528,19 +4388,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, @@ -4595,13 +4442,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); @@ -4659,7 +4499,6 @@ 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 @@ -4687,13 +4526,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) { @@ -4709,12 +4541,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; @@ -5087,10 +4913,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 @@ -5124,21 +4946,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. */ @@ -5234,11 +5041,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 @@ -5288,7 +5090,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; @@ -5333,9 +5134,6 @@ 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; @@ -5348,12 +5146,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. */ @@ -5395,13 +5187,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) @@ -5479,9 +5264,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; @@ -5502,15 +5284,6 @@ 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. - */ KDTree_3d *BKE_object_as_kdtree(Object *ob, int *r_tot) { KDTree_3d *tree = nullptr; @@ -5773,10 +5546,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, @@ -5880,9 +5649,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; |