From 61776befc3f88c373e47ccbdf8c75e2ca0f4e987 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 9 Dec 2021 00:55:11 +1100 Subject: Cleanup: move public doc-strings into headers for 'editors' Ref T92709 --- source/blender/editors/include/ED_object.h | 161 +++++++++++++++++++++++++++-- 1 file changed, 155 insertions(+), 6 deletions(-) (limited to 'source/blender/editors/include/ED_object.h') diff --git a/source/blender/editors/include/ED_object.h b/source/blender/editors/include/ED_object.h index 2a557f1abd3..576c6f51362 100644 --- a/source/blender/editors/include/ED_object.h +++ b/source/blender/editors/include/ED_object.h @@ -56,12 +56,24 @@ struct wmOperator; struct wmOperatorType; /* object_edit.c */ -/* context.object */ + +/** `context.object` */ struct Object *ED_object_context(const struct bContext *C); -/* context.object or context.active_object */ +/** + * Find the correct active object per context (`context.object` or `context.active_object`) + * \note context can be NULL when called from a enum with #PROP_ENUM_NO_CONTEXT. + */ struct Object *ED_object_active_context(const struct bContext *C); void ED_collection_hide_menu_draw(const struct bContext *C, struct uiLayout *layout); +/** + * Return an array of objects: + * - When in the property space, return the pinned or active object. + * - When in edit-mode/pose-mode, return an array of objects in the mode. + * - Otherwise return selected objects, + * the callers \a filter_fn needs to check of they are editable + * (assuming they need to be modified). + */ Object **ED_object_array_in_mode_or_selected(struct bContext *C, bool (*filter_fn)(const struct Object *ob, void *user_data), @@ -81,6 +93,10 @@ bool ED_object_calc_active_center(struct Object *ob, const bool select_only, flo struct XFormObjectData_Container; struct XFormObjectData_Container *ED_object_data_xform_container_create(void); void ED_object_data_xform_container_destroy(struct XFormObjectData_Container *xds); +/** + * This may be called multiple times with the same data. + * Each time, the original transformations are re-applied, instead of accumulating the changes. + */ void ED_object_data_xform_container_update_all(struct XFormObjectData_Container *xds, struct Main *bmain, struct Depsgraph *depsgraph); @@ -130,6 +146,7 @@ void ED_operatormacros_object(void); void ED_keymap_object(struct wmKeyConfig *keyconf); /* object_relations.c */ + typedef enum eParentType { PAR_OBJECT, PAR_ARMATURE, @@ -163,7 +180,9 @@ extern struct EnumPropertyItem prop_clear_parent_types[]; extern struct EnumPropertyItem prop_make_parent_types[]; #endif -/* Set the object's parent, return true if successful. */ +/** + * Set the object's parent, return true if successful. + */ bool ED_object_parent_set(struct ReportList *reports, const struct bContext *C, struct Scene *scene, @@ -175,13 +194,35 @@ bool ED_object_parent_set(struct ReportList *reports, const int vert_par[3]); void ED_object_parent_clear(struct Object *ob, const int type); +/** + * Simple API for object selection, rather than just using the flag + * this takes into account the 'restrict selection in 3d view' flag. + * deselect works always, the restriction just prevents selection + * + * \note Caller must send a `NC_SCENE | ND_OB_SELECT` notifier + * (or a `NC_SCENE | ND_OB_VISIBLE` in case of visibility toggling). + */ void ED_object_base_select(struct Base *base, eObjectSelect_Mode mode); +/** + * Change active base, it includes the notifier + */ void ED_object_base_activate(struct bContext *C, struct Base *base); void ED_object_base_activate_with_mode_exit_if_needed(struct bContext *C, struct Base *base); +/** + * Call when the active base has changed. + */ void ED_object_base_active_refresh(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer); +/** + * Remove base from a specific scene. + * \note now unlinks constraints as well. + */ void ED_object_base_free_and_unlink(struct Main *bmain, struct Scene *scene, struct Object *ob); +/** + * Remove base from a specific scene. + * `ob` must not be indirectly used. + */ void ED_object_base_free_and_unlink_no_indirect_check(struct Main *bmain, struct Scene *scene, struct Object *ob); @@ -191,7 +232,13 @@ bool ED_object_base_deselect_all_ex(struct ViewLayer *view_layer, bool *r_any_visible); bool ED_object_base_deselect_all(struct ViewLayer *view_layer, struct View3D *v3d, int action); -/* single object duplicate, if (dupflag == 0), fully linked, else it uses the flags given */ +/** + * Single object duplicate, if `dupflag == 0`, fully linked, else it uses the flags given. + * Leaves selection of base/object unaltered. + * \note don't call this within a loop since clear_* funcs loop over the entire database. + * \note caller must do `DAG_relations_tag_update(bmain);` + * this is not done automatic since we may duplicate many objects in a batch. + */ struct Base *ED_object_add_duplicate(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, @@ -211,12 +258,21 @@ enum { EM_FREEDATA = (1 << 0), EM_NO_CONTEXT = (1 << 1), }; +/** + * \param flag: + * - If #EM_FREEDATA isn't in the flag, use ED_object_editmode_load directly. + */ bool ED_object_editmode_exit_ex(struct Main *bmain, struct Scene *scene, struct Object *obedit, int flag); bool ED_object_editmode_exit(struct bContext *C, int flag); +/** + * Support freeing edit-mode data without flushing it back to the object. + * + * \return true if data was freed. + */ bool ED_object_editmode_free_ex(struct Main *bmain, struct Object *obedit); bool ED_object_editmode_exit_multi_ex(struct Main *bmain, @@ -284,6 +340,10 @@ void ED_object_rotation_from_view(struct bContext *C, float rot[3], const char a void ED_object_base_init_transform_on_add(struct Object *object, const float loc[3], const float rot[3]); +/** + * Uses context to figure out transform for primitive. + * Returns standard diameter. + */ float ED_object_new_primitive_matrix(struct bContext *C, struct Object *obedit, const float loc[3], @@ -291,8 +351,9 @@ float ED_object_new_primitive_matrix(struct bContext *C, const float scale[3], float primmat[4][4]); -/* Avoid allowing too much insane values even by typing - * (typos can hang/crash Blender otherwise). */ +/** + * Avoid allowing too much insane values even by typing (typos can hang/crash Blender otherwise). + */ #define OBJECT_ADD_SIZE_MAXF 1.0e12f void ED_object_add_unit_props_size(struct wmOperatorType *ot); @@ -310,6 +371,12 @@ bool ED_object_add_generic_get_opts(struct bContext *C, unsigned short *r_local_view_bits, bool *r_is_view_aligned); +/** + * For object add primitive operators, or for object creation when `obdata != NULL`. + * \param obdata: Assigned to #Object.data, with increased user count. + * + * \note Do not call undo push in this function (users of this function have to). + */ struct Object *ED_object_add_type_with_obdata(struct bContext *C, const int type, const char *name, @@ -327,9 +394,16 @@ struct Object *ED_object_add_type(struct bContext *C, const unsigned short local_view_bits) ATTR_NONNULL(1) ATTR_RETURNS_NONNULL; +/** + * Not an especially efficient function, only added so the single user button can be functional. + */ void ED_object_single_user(struct Main *bmain, struct Scene *scene, struct Object *ob); /* object motion paths */ + +/** + * Clear motion paths for all objects. + */ void ED_objects_clear_paths(struct bContext *C, bool only_selected); /* Corresponds to eAnimvizCalcRange. */ @@ -339,6 +413,12 @@ typedef enum eObjectPathCalcRange { OBJECT_PATH_CALC_RANGE_FULL, } eObjectPathCalcRange; +/** + * For the objects with animation: update paths for those that have got them + * This should selectively update paths that exist. + * + * To be called from various tools that do incremental updates + */ void ED_objects_recalculate_paths(struct bContext *C, struct Scene *scene, eObjectPathCalcRange range, @@ -353,11 +433,26 @@ void ED_objects_recalculate_paths_visible(struct bContext *C, eObjectPathCalcRange range); /* constraints */ +/** + * If object is in pose-mode, return active bone constraints, else object constraints. + * No constraints are returned for a bone on an inactive bone-layer. + */ struct ListBase *ED_object_constraint_active_list(struct Object *ob); +/** + * Get the constraints for the active pose bone. Bone may be on an inactive bone-layer + * (unlike #ED_object_constraint_active_list, such constraints are not excluded here). + */ struct ListBase *ED_object_pose_constraint_list(const struct bContext *C); +/** + * Find the list that a given constraint belongs to, + * and/or also get the posechannel this is from (if applicable). + */ struct ListBase *ED_object_constraint_list_from_constraint(struct Object *ob, struct bConstraint *con, struct bPoseChannel **r_pchan); +/** + * Single constraint. + */ struct bConstraint *ED_object_constraint_active_get(struct Object *ob); void object_test_constraints(struct Main *bmain, struct Object *ob); @@ -389,7 +484,17 @@ void ED_object_constraint_copy_for_pose(struct Main *bmain, struct bConstraint *con); /* object_modes.c */ + +/** + * Checks the mode to be set is compatible with the object + * should be made into a generic function + */ bool ED_object_mode_compat_test(const struct Object *ob, eObjectMode mode); +/** + * Sets the mode to a compatible state (use before entering the mode). + * + * This is so each mode's exec function can call + */ bool ED_object_mode_compat_set(struct bContext *C, struct Object *ob, eObjectMode mode, @@ -412,11 +517,18 @@ void ED_object_posemode_set_for_weight_paint(struct bContext *C, const bool is_mode_set); /* object_modifier.c */ + enum { MODIFIER_APPLY_DATA = 1, MODIFIER_APPLY_SHAPE, }; +/** + * Add a modifier to given object, including relevant extra processing needed by some physics types + * (particles, simulations...). + * + * \param scene: is only used to set current frame in some cases, and may be NULL. + */ struct ModifierData *ED_object_modifier_add(struct ReportList *reports, struct Main *bmain, struct Scene *scene, @@ -465,12 +577,25 @@ void ED_object_modifier_copy_to_object(struct bContext *C, struct Object *ob_src, struct ModifierData *md); +/** + * If the object data of 'orig_ob' has other users, run 'callback' on + * each of them. + * + * If include_orig is true, the callback will run on 'orig_ob' too. + * + * If the callback ever returns true, iteration will stop and the + * function value will be true. Otherwise the function returns false. + */ bool ED_object_iter_other(struct Main *bmain, struct Object *orig_ob, const bool include_orig, bool (*callback)(struct Object *ob, void *callback_data), void *callback_data); +/** + * Use with #ED_object_iter_other(). Sets the total number of levels + * for any multi-res modifiers on the object to the int pointed to by callback_data. + */ bool ED_object_multires_update_totlevels_cb(struct Object *ob, void *totlevel_v); /* object_greasepencil_modifier.c */ @@ -546,16 +671,40 @@ void ED_object_check_force_modifiers(struct Main *bmain, struct Scene *scene, struct Object *object); +/** + * If id is not already an Object, try to find an object that uses it as data. + * Prefers active, then selected, then visible/selectable. + */ struct Base *ED_object_find_first_by_data_id(struct ViewLayer *view_layer, struct ID *id); +/** + * Select and make the target object active in the view layer. + * If already selected, selection isn't changed. + * + * \returns false if not found in current view layer + */ bool ED_object_jump_to_object(struct bContext *C, struct Object *ob, const bool reveal_hidden); +/** + * Select and make the target object and bone active. + * Switches to Pose mode if in Object mode so the selection is visible. + * Un-hides the target bone and bone layer if necessary. + * + * \returns false if object not in layer, bone not found, or other error + */ bool ED_object_jump_to_bone(struct bContext *C, struct Object *ob, const char *bone_name, const bool reveal_hidden); /* object_facemap_ops.c */ + +/** + * Called while not in edit-mode. + */ void ED_object_facemap_face_add(struct Object *ob, struct bFaceMap *fmap, int facenum); +/** + * Called while not in edit-mode. + */ void ED_object_facemap_face_remove(struct Object *ob, struct bFaceMap *fmap, int facenum); /* object_data_transform.c */ -- cgit v1.2.3