diff options
Diffstat (limited to 'source/blender/editors/include')
47 files changed, 3729 insertions, 423 deletions
diff --git a/source/blender/editors/include/BIF_glutil.h b/source/blender/editors/include/BIF_glutil.h index 0a1cf643f37..8f2a189e35e 100644 --- a/source/blender/editors/include/BIF_glutil.h +++ b/source/blender/editors/include/BIF_glutil.h @@ -46,6 +46,12 @@ typedef struct IMMDrawPixelsTexState { /* To be used before calling immDrawPixelsTex * Default shader is GPU_SHADER_2D_IMAGE_COLOR * Returns a shader to be able to set uniforms */ +/** + * To be used before calling #immDrawPixelsTex + * Default shader is #GPU_SHADER_2D_IMAGE_COLOR + * You can still set uniforms with: + * `GPU_shader_uniform_int(shader, GPU_shader_get_uniform(shader, "name"), 0);` + */ IMMDrawPixelsTexState immDrawPixelsTexSetup(int builtin); /** @@ -101,6 +107,20 @@ void immDrawPixelsTexScaled(IMMDrawPixelsTexState *state, float xzoom, float yzoom, const float color[4]); +/** + * Use the currently bound shader. + * + * Use #immDrawPixelsTexSetup to bind the shader you + * want before calling #immDrawPixelsTex. + * + * If using a special shader double check it uses the same + * attributes "pos" "texCoord" and uniform "image". + * + * If color is NULL then use white by default + * + * Be also aware that this function unbinds the shader when + * it's finished. + */ void immDrawPixelsTexScaled_clipping(IMMDrawPixelsTexState *state, float x, float y, @@ -135,6 +155,9 @@ void ED_draw_imbuf(struct ImBuf *ibuf, struct ColorManagedDisplaySettings *display_settings, float zoom_x, float zoom_y); +/** + * Draw given image buffer on a screen using GLSL for display transform. + */ void ED_draw_imbuf_clipping(struct ImBuf *ibuf, float x, float y, @@ -169,6 +192,9 @@ void ED_draw_imbuf_ctx_clipping(const struct bContext *C, int ED_draw_imbuf_method(struct ImBuf *ibuf); +/** + * Don't move to `GPU_immediate_util.h` because this uses user-prefs and isn't very low level. + */ void immDrawBorderCorners(unsigned int pos, const struct rcti *border, float zoomx, float zoomy); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_anim_api.h b/source/blender/editors/include/ED_anim_api.h index e9601220f2e..3294316f880 100644 --- a/source/blender/editors/include/ED_anim_api.h +++ b/source/blender/editors/include/ED_anim_api.h @@ -63,7 +63,9 @@ struct PropertyRNA; /* ANIMATION CHANNEL FILTERING */ /* anim_filter.c */ -/* --------------- Context --------------------- */ +/* -------------------------------------------------------------------- */ +/** \name Context + * \{ */ /* This struct defines a structure used for animation-specific * 'context' information @@ -126,7 +128,11 @@ typedef enum eAnimCont_Types { ANIMCONT_TIMELINE = 10, /* "timeline" editor (bDopeSheet) */ } eAnimCont_Types; -/* --------------- Channels -------------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Channels + * \{ */ /* This struct defines a structure used for quick and uniform access for * channels of animation data @@ -281,7 +287,11 @@ typedef enum eAnim_Update_Flags { #define ANIM_UPDATE_DEFAULT (ANIM_UPDATE_DEPS | ANIM_UPDATE_ORDER | ANIM_UPDATE_HANDLES) #define ANIM_UPDATE_DEFAULT_NOHANDLES (ANIM_UPDATE_DEFAULT & ~ANIM_UPDATE_HANDLES) -/* ----------------- Filtering -------------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Filtering + * \{ */ /* filtering flags - under what circumstances should a channel be returned */ typedef enum eAnimFilter_Flags { @@ -334,7 +344,12 @@ typedef enum eAnimFilter_Flags { ANIMFILTER_TMP_IGNORE_ONLYSEL = (1u << 31), } eAnimFilter_Flags; -/* ---------- Flag Checking Macros ------------ */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Flag Checking Macros + * \{ */ + /* XXX check on all of these flags again. */ /* Dopesheet only */ @@ -421,7 +436,11 @@ typedef enum eAnimFilter_Flags { /* AnimData - NLA mostly... */ #define SEL_ANIMDATA(adt) (adt->flag & ADT_UI_SELECTED) -/* -------------- Channel Defines -------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Channel Defines + * \{ */ /* channel heights */ #define ACHANNEL_FIRST_TOP(ac) \ @@ -439,7 +458,11 @@ typedef enum eAnimFilter_Flags { /* channel toggle-buttons */ #define ACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit) -/* -------------- NLA Channel Defines -------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name NLA Channel Defines + * \{ */ /* NLA channel heights */ #define NLACHANNEL_FIRST_TOP(ac) \ @@ -459,10 +482,19 @@ typedef enum eAnimFilter_Flags { /* channel toggle-buttons */ #define NLACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit) -/* ---------------- API -------------------- */ +/** \} */ -/* Obtain list of filtered Animation channels to operate on. - * Returns the number of channels in the list +/* -------------------------------------------------------------------- */ +/** \name Public API + * \{ */ + +/** + * This function filters the active data source to leave only animation channels suitable for + * usage by the caller. It will return the length of the list + * + * \param anim_data: Is a pointer to a #ListBase, + * to which the filtered animation channels will be placed for use. + * \param filter_mode: how should the data be filtered - bit-mapping accessed flags. */ size_t ANIM_animdata_filter(bAnimContext *ac, ListBase *anim_data, @@ -470,18 +502,27 @@ size_t ANIM_animdata_filter(bAnimContext *ac, void *data, eAnimCont_Types datatype); -/* Obtain current anim-data context from Blender Context info. - * Returns whether the operation was successful. +/** + * Obtain current anim-data context from Blender Context info + * - AnimContext to write to is provided as pointer to var on stack so that we don't have + * allocation/freeing costs (which are not that avoidable with channels). + * - Clears data and sets the information from Blender Context which is useful + * \return whether the operation was successful. */ bool ANIM_animdata_get_context(const struct bContext *C, bAnimContext *ac); -/* Obtain current anim-data context (from Animation Editor) given - * that Blender Context info has already been set. - * Returns whether the operation was successful. +/** + * Obtain current anim-data context, + * given that context info from Blender context has already been set: + * - AnimContext to write to is provided as pointer to var on stack so that we don't have + * allocation/freeing costs (which are not that avoidable with channels). + * \return whether the operation was successful. */ bool ANIM_animdata_context_getdata(bAnimContext *ac); -/* Acts on bAnimListElem eAnim_Update_Flags */ +/** + * Acts on bAnimListElem eAnim_Update_Flags. + */ void ANIM_animdata_update(bAnimContext *ac, ListBase *anim_data); void ANIM_animdata_freelist(ListBase *anim_data); @@ -490,7 +531,11 @@ void ANIM_animdata_freelist(ListBase *anim_data); /* ANIMATION CHANNELS LIST */ /* anim_channels_*.c */ -/* ------------------------ Drawing TypeInfo -------------------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Drawing TypeInfo + * \{ */ /* role or level of animchannel in the hierarchy */ typedef enum eAnimChannel_Role { @@ -569,18 +614,35 @@ typedef struct bAnimChannelType { void *(*setting_ptr)(bAnimListElem *ale, eAnimChannel_Settings setting, short *type); } bAnimChannelType; -/* ------------------------ Drawing API -------------------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Drawing API + * \{ */ -/* Get typeinfo for the given channel */ +/** + * Get type info from given channel type. + */ const bAnimChannelType *ANIM_channel_get_typeinfo(bAnimListElem *ale); -/* Print debugging info about a given channel */ +/** + * Print debug info string for the given channel. + */ void ANIM_channel_debug_print_info(bAnimListElem *ale, short indent_level); -/* Draw the given channel */ +/** + * Retrieves the Action associated with this animation channel. + */ +bAction *ANIM_channel_action_get(const bAnimListElem *ale); + +/** + * Draw the given channel. + */ void ANIM_channel_draw( bAnimContext *ac, bAnimListElem *ale, float yminc, float ymaxc, size_t channel_index); -/* Draw the widgets for the given channel */ +/** + * Draw UI widgets the given channel. + */ void ANIM_channel_draw_widgets(const struct bContext *C, bAnimContext *ac, bAnimListElem *ale, @@ -588,27 +650,30 @@ void ANIM_channel_draw_widgets(const struct bContext *C, rctf *rect, size_t channel_index); -/* ------------------------ Editing API -------------------------- */ +/** \} */ -/* Check if some setting for a channel is enabled - * Returns: 1 = On, 0 = Off, -1 = Invalid - * - * - setting: eAnimChannel_Settings +/* -------------------------------------------------------------------- */ +/** \name Editing API + * \{ */ + +/** + * Check if some setting for a channel is enabled + * Returns: 1 = On, 0 = Off, -1 = Invalid. */ short ANIM_channel_setting_get(bAnimContext *ac, bAnimListElem *ale, eAnimChannel_Settings setting); -/* Change value of some setting for a channel - * - setting: eAnimChannel_Settings - * - mode: eAnimChannels_SetFlag +/** + * Change value of some setting for a channel. */ void ANIM_channel_setting_set(bAnimContext *ac, bAnimListElem *ale, eAnimChannel_Settings setting, eAnimChannels_SetFlag mode); -/* Flush visibility (for Graph Editor) changes up/down hierarchy for changes in the given setting +/** + * Flush visibility (for Graph Editor) changes up/down hierarchy for changes in the given setting * - anim_data: list of the all the anim channels that can be chosen * -> filtered using ANIMFILTER_CHANNELS only, since if we took VISIBLE too, * then the channels under closed expanders get ignored... @@ -623,13 +688,19 @@ void ANIM_flush_setting_anim_channels(bAnimContext *ac, eAnimChannel_Settings setting, eAnimChannels_SetFlag mode); -/* Select or deselect animation channels */ +/** + * Set selection state of all animation channels in the context. + */ void ANIM_anim_channels_select_set(bAnimContext *ac, eAnimChannels_SetFlag sel); -/* Toggle selection of animation channels */ +/** + * Toggle selection state of all animation channels in the context. + */ void ANIM_anim_channels_select_toggle(bAnimContext *ac); -/* Set the 'active' channel of type channel_type, in the given action */ +/** + * Set the given animation-channel as the active one for the active context. + */ void ANIM_set_active_channel(bAnimContext *ac, void *data, eAnimCont_Types datatype, @@ -637,18 +708,31 @@ void ANIM_set_active_channel(bAnimContext *ac, void *channel_data, eAnim_ChannelType channel_type); -/* Delete the F-Curve from the given AnimData block (if possible), - * as appropriate according to animation context */ +/** + * Delete the F-Curve from the given AnimData block (if possible), + * as appropriate according to animation context. + */ void ANIM_fcurve_delete_from_animdata(bAnimContext *ac, struct AnimData *adt, struct FCurve *fcu); -/* Unlink the action from animdata if it's empty. */ +/** + * Unlink the action from animdata if it's empty. + * + * If the action has no F-Curves, unlink it from AnimData if it did not + * come from a NLA Strip being tweaked. + */ bool ANIM_remove_empty_action_from_animdata(struct AnimData *adt); /* ************************************************ */ /* DRAWING API */ /* anim_draw.c */ -/* ---------- Current Frame Drawing ---------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Current Frame Drawing + * + * Main call to draw current-frame indicator in an Animation Editor. + * \{ */ /* flags for Current Frame Drawing */ typedef enum eAnimEditDraw_CurrentFrame { @@ -660,23 +744,54 @@ typedef enum eAnimEditDraw_CurrentFrame { DRAWCFRA_WIDE = (1 << 1), } eAnimEditDraw_CurrentFrame; -/* main call to draw current-frame indicator in an Animation Editor */ +/** + * General call for drawing current frame indicator in animation editor. + */ void ANIM_draw_cfra(const struct bContext *C, struct View2D *v2d, short flag); -/* ------------- Preview Range Drawing -------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Preview Range Drawing + * + * Main call to draw preview range curtains. + * \{ */ -/* main call to draw preview range curtains */ +/** + * Draw preview range 'curtains' for highlighting where the animation data is. + */ void ANIM_draw_previewrange(const struct bContext *C, struct View2D *v2d, int end_frame_width); -/* -------------- Frame Range Drawing --------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Frame Range Drawing + * + * Main call to draw normal frame range indicators. + * \{ */ -/* main call to draw normal frame range indicators */ +/** + * Draw frame range guides (for scene frame range) in background. + * + * TODO: Should we still show these when preview range is enabled? + */ void ANIM_draw_framerange(struct Scene *scene, struct View2D *v2d); +/** + * Draw manually set intended playback frame range guides for the action in the background. + * Allows specifying a subset of the Y range of the view. + */ +void ANIM_draw_action_framerange( + struct AnimData *adt, struct bAction *action, struct View2D *v2d, float ymin, float ymax); + /* ************************************************* */ /* F-MODIFIER TOOLS */ -/* ------------- UI Panel Drawing -------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name UI Panel Drawing + * \{ */ bool ANIM_nla_context_track_ptr(const struct bContext *C, struct PointerRNA *r_ptr); bool ANIM_nla_context_strip_ptr(const struct bContext *C, struct PointerRNA *r_ptr); @@ -690,6 +805,9 @@ typedef bool (*PanelTypePollFn)(const struct bContext *C, struct PanelType *pt); /* Avoid including "UI_interface.h" here. */ typedef void (*uiListPanelIDFromDataFunc)(void *data_link, char *r_idname); +/** + * Checks if the panels match the active strip / curve, rebuilds them if they don't. + */ void ANIM_fmodifier_panels(const struct bContext *C, struct ID *owner_id, struct ListBase *fmodifiers, @@ -702,49 +820,93 @@ void ANIM_modifier_panels_register_graph_only(struct ARegionType *region_type, const char *modifier_panel_prefix, PanelTypePollFn poll_function); -/* ------------- Copy/Paste Buffer -------------- */ +/** \} */ -/* free the copy/paste buffer */ +/* -------------------------------------------------------------------- */ +/** \name Copy/Paste Buffer + * \{ */ + +/** + * Free the copy/paste buffer. + */ void ANIM_fmodifiers_copybuf_free(void); -/* copy the given F-Modifiers to the buffer, returning whether anything was copied or not - * assuming that the buffer has been cleared already with ANIM_fmodifiers_copybuf_free() - * - active: only copy the active modifier +/** + * Copy the given F-Modifiers to the buffer, returning whether anything was copied or not + * assuming that the buffer has been cleared already with #ANIM_fmodifiers_copybuf_free() + * \param active: Only copy the active modifier. */ bool ANIM_fmodifiers_copy_to_buf(ListBase *modifiers, bool active); -/* 'Paste' the F-Modifier(s) from the buffer to the specified list - * - replace: free all the existing modifiers to leave only the pasted ones +/** + * 'Paste' the F-Modifier(s) from the buffer to the specified list + * \param replace: Free all the existing modifiers to leave only the pasted ones. */ bool ANIM_fmodifiers_paste_from_buf(ListBase *modifiers, bool replace, struct FCurve *curve); /* ************************************************* */ /* ASSORTED TOOLS */ -/* ------------ Animation F-Curves <-> Icons/Names Mapping ------------ */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Animation F-Curves <-> Icons/Names Mapping + * \{ */ + /* anim_ipo_utils.c */ -/* Get icon + name for channel-list displays for F-Curve */ +/** + * Get icon + name for channel-list displays for F-Curve. + * + * Write into "name" buffer, the name of the property + * (retrieved using RNA from the curve's settings), + * and return the icon used for the struct that this property refers to + * + * \warning name buffer we're writing to cannot exceed 256 chars + * (check anim_channels_defines.c for details). + */ int getname_anim_fcurve(char *name, struct ID *id, struct FCurve *fcu); -/* Automatically determine a color for the nth F-Curve */ +/** + * Automatically determine a color for the nth F-Curve. + */ void getcolor_fcurve_rainbow(int cur, int tot, float out[3]); -/* ----------------- NLA Drawing ----------------------- */ -/* NOTE: Technically, this is not in the animation module (it's in space_nla) +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name NLA Drawing + * + * \note Technically, this is not in the animation module (it's in space_nla) * but these are sometimes needed by various animation API's. - */ + * \{ */ -/* Get color to use for NLA Action channel's background */ +/** + * Get color to use for NLA Action channel's background. + * \note color returned includes fine-tuned alpha! + */ void nla_action_get_color(struct AnimData *adt, struct bAction *act, float color[4]); -/* ----------------- NLA-Mapping ----------------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name NLA-Mapping + * \{ */ + /* anim_draw.c */ -/* Obtain the AnimData block providing NLA-scaling for the given channel if applicable */ +/** + * Obtain the AnimData block providing NLA-mapping for the given channel (if applicable). + * + * TODO: do not supply return this if the animdata tells us that there is no mapping to perform. + */ struct AnimData *ANIM_nla_mapping_get(bAnimContext *ac, bAnimListElem *ale); -/* Apply/Unapply NLA mapping to all keyframes in the nominated F-Curve */ +/** + * Apply/Unapply NLA mapping to all keyframes in the nominated F-Curve + * \param restore: Whether to map points back to non-mapped time. + * \param only_keys: Whether to only adjust the location of the center point of beztriples. + */ void ANIM_nla_mapping_apply_fcurve(struct AnimData *adt, struct FCurve *fcu, bool restore, @@ -752,11 +914,18 @@ void ANIM_nla_mapping_apply_fcurve(struct AnimData *adt, /* ..... */ -/* Perform auto-blending/extend refreshes after some operations */ -/* NOTE: defined in space_nla/nla_edit.c, not in animation/ */ +/** + * Perform validation & auto-blending/extend refreshes after some operations + * \note defined in space_nla/nla_edit.c, not in animation/ + */ void ED_nla_postop_refresh(bAnimContext *ac); -/* ------------- Unit Conversion Mappings ------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Unit Conversion Mappings + * \{ */ + /* anim_draw.c */ /* flags for conversion mapping */ @@ -778,16 +947,24 @@ typedef enum eAnimUnitConv_Flags { ANIM_UNITCONV_NORMALIZE_FREEZE = (1 << 6), } eAnimUnitConv_Flags; -/* Normalization flags from Space Graph passing to ANIM_unit_mapping_get_factor */ +/** + * Get flags used for normalization in ANIM_unit_mapping_get_factor. + */ short ANIM_get_normalization_flags(bAnimContext *ac); - -/* Get unit conversion factor for given ID + F-Curve */ +/** + * Get unit conversion factor for given ID + F-Curve. + */ float ANIM_unit_mapping_get_factor( struct Scene *scene, struct ID *id, struct FCurve *fcu, short flag, float *r_offset); -/* ------------- Utility macros ----------------------- */ +/** \} */ -/* provide access to Keyframe Type info in BezTriple +/* -------------------------------------------------------------------- */ +/** \name Utility macros + * \{ */ + +/** + * Provide access to Keyframe Type info in #BezTriple. * NOTE: this is so that we can change it from being stored in 'hide' */ #define BEZKEYTYPE(bezt) ((bezt)->hide) @@ -830,18 +1007,37 @@ float ANIM_unit_mapping_get_factor( } \ ((void)0) -/* --------- anim_deps.c, animation updates -------- */ +/** \} */ +/* anim_deps.c */ + +/* -------------------------------------------------------------------- */ +/** \name Animation Updates + * \{ */ + +/** + * Tags the given ID block for refreshes (if applicable) due to Animation Editor editing. + */ void ANIM_id_update(struct Main *bmain, struct ID *id); +/** + * Tags the given anim list element for refreshes (if applicable) due to Animation Editor editing. + */ void ANIM_list_elem_update(struct Main *bmain, struct Scene *scene, bAnimListElem *ale); /* data -> channels syncing */ + +/** + * Main call to be exported to animation editors. + */ void ANIM_sync_animchannels_to_data(const struct bContext *C); void ANIM_center_frame(struct bContext *C, int smooth_viewtx); -/* ************************************************* */ -/* OPERATORS */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Operators + * \{ */ /* generic animation channels */ void ED_operatortypes_animchannels(void); @@ -856,12 +1052,20 @@ void ED_operatormacros_graph(void); /* space_action */ void ED_operatormacros_action(void); -/* ************************************************ */ -/* Animation Editor Exports */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Animation Editor Exports + * \{ */ + /* XXX: Should we be doing these here, or at all? */ -/* Action Editor - Action Management */ -struct AnimData *ED_actedit_animdata_from_context(struct bContext *C, struct ID **r_adt_id_owner); +/** + * Action Editor - Action Management. + * Helper function to find the active AnimData block from the Action Editor context. + */ +struct AnimData *ED_actedit_animdata_from_context(const struct bContext *C, + struct ID **r_adt_id_owner); void ED_animedit_unlink_action(struct bContext *C, struct ID *id, struct AnimData *adt, @@ -869,7 +1073,11 @@ void ED_animedit_unlink_action(struct bContext *C, struct ReportList *reports, bool force_delete); -/* Drivers Editor - Utility to set up UI correctly */ +/** + * Set up UI configuration for Drivers Editor + * (drivers editor window) and RNA (mode switching). + * \note Currently called from window-manager. + */ void ED_drivers_editor_init(struct bContext *C, struct ScrArea *area); /* ************************************************ */ @@ -897,8 +1105,14 @@ void animviz_calc_motionpaths(struct Depsgraph *depsgraph, eAnimvizCalcRange range, bool restore); +/** + * Get list of motion paths to be baked for the given object. + * - assumes the given list is ready to be used. + */ void animviz_get_object_motionpaths(struct Object *ob, ListBase *targets); +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/editors/include/ED_armature.h b/source/blender/editors/include/ED_armature.h index 868235c36e5..0053bf5c865 100644 --- a/source/blender/editors/include/ED_armature.h +++ b/source/blender/editors/include/ED_armature.h @@ -70,45 +70,91 @@ struct wmOperator; (CHECK_TYPE_INLINE(ebone, EditBone *), \ (((ebone)->flag & BONE_SELECTED) && !((ebone)->flag & BONE_EDITMODE_LOCKED))) -/* used in armature_select.c and pose_select.c */ +/* Used in `armature_select.c` and `pose_select.c`. */ + #define BONE_SELECT_PARENT 0 #define BONE_SELECT_CHILD 1 /* armature_add.c */ + +/** + * Default bone add, returns it selected, but without tail set. + * + * \note should be used everywhere, now it allocates bones still locally in functions. + */ struct EditBone *ED_armature_ebone_add(struct bArmature *arm, const char *name); struct EditBone *ED_armature_ebone_add_primitive(struct Object *obedit_arm, float length, bool view_aligned); /* armature_edit.c */ + +/** + * Adjust bone roll to align Z axis with vector `align_axis` is in local space and is normalized. + */ float ED_armature_ebone_roll_to_vector(const struct EditBone *bone, const float align_axis[3], const bool axis_only); +/** + * \param centermode: 0 == do center, 1 == center new, 2 == center cursor. + * + * \note Exported for use in `editors/object/`. + */ void ED_armature_origin_set( struct Main *bmain, struct Object *ob, const float cursor[3], int centermode, int around); +/** + * See #BKE_armature_transform for object-mode transform. + */ void ED_armature_edit_transform(struct bArmature *arm, const float mat[4][4], const bool do_props); void ED_armature_transform(struct bArmature *arm, const float mat[4][4], const bool do_props); /* armature_naming.c */ + +/** + * Ensure the bone name is unique. + * If bone is already in list, pass it as argument to ignore it. + */ void ED_armature_ebone_unique_name(struct ListBase *ebones, char *name, struct EditBone *bone); + +/** + * Bone Rename (called by UI for renaming a bone). + * Seems messy, but that's what you get with not using pointers but channel names :). + * \warning make sure the original bone was not renamed yet! + */ void ED_armature_bone_rename(struct Main *bmain, struct bArmature *arm, const char *oldnamep, const char *newnamep); +/** + * Renames (by flipping) all selected bones at once. + * + * This way if we are flipping related bones (e.g., Bone.L, Bone.R) at the same time + * all the bones are safely renamed, without conflicting with each other. + * + * \param arm: Armature the bones belong to + * \param bones_names: List of bone conflict elements (#LinkData pointing to names). + * \param do_strip_numbers: if set, try to get rid of dot-numbers at end of bone names. + */ void ED_armature_bones_flip_names(struct Main *bmain, struct bArmature *arm, struct ListBase *bones_names, const bool do_strip_numbers); /* armature_ops.c */ + void ED_operatortypes_armature(void); void ED_operatormacros_armature(void); void ED_keymap_armature(struct wmKeyConfig *keyconf); /* armature_relations.c */ + +/** + * Join armature exec is exported for use in object->join objects operator. + */ int ED_armature_join_objects_exec(struct bContext *C, struct wmOperator *op); /* armature_select.c */ + struct Base *ED_armature_base_and_ebone_from_select_buffer(struct Base **bases, uint bases_len, int hit, @@ -121,6 +167,9 @@ struct Base *ED_armature_base_and_pchan_from_select_buffer(struct Base **bases, uint bases_len, int hit, struct bPoseChannel **r_pchan); +/** + * For callers that don't need the pose channel. + */ struct Base *ED_armature_base_and_bone_from_select_buffer(struct Base **bases, uint bases_len, int hit, @@ -137,11 +186,27 @@ bool ED_armature_edit_select_pick_bone(struct bContext *C, bool extend, bool deselect, bool toggle); +/** + * Bone selection picking for armature edit-mode in the view3d. + */ bool ED_armature_edit_select_pick( struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle); +/** + * Perform a selection operation on elements which have been 'touched', + * use for lasso & border select but can be used elsewhere too. + * + * Tagging is done via #EditBone.temp.i using: #BONESEL_ROOT, #BONESEL_TIP, #BONESEL_BONE + * And optionally ignoring end-points using the #BONESEL_ROOT, #BONESEL_TIP right shifted 16 bits. + * (used when the values are clipped outside the view). + * + * \param sel_op: #eSelectOp type. + * + * \note Visibility checks must be done by the caller. + */ bool ED_armature_edit_select_op_from_tagged(struct bArmature *arm, const int sel_op); /* armature_skinning.c */ + #define ARM_GROUPS_NAME 1 #define ARM_GROUPS_ENVELOPE 2 #define ARM_GROUPS_AUTO 3 @@ -154,40 +219,74 @@ void ED_object_vgroup_calc_from_armature(struct ReportList *reports, const bool mirror); /* editarmature_undo.c */ + +/** Export for ED_undo_sys. */ void ED_armature_undosys_type(struct UndoType *ut); /* armature_utils.c */ + +/** Sync selection to parent for connected children. */ void ED_armature_edit_sync_selection(struct ListBase *edbo); void ED_armature_edit_validate_active(struct bArmature *arm); +/** + * Update the layers_used variable after bones are moved between layer + * \note Used to be done in drawing code in 2.7, but that won't work with + * Copy-on-Write, as drawing uses evaluated copies. + */ void ED_armature_edit_refresh_layer_used(struct bArmature *arm); +/** + * \param clear_connected: When false caller is responsible for keeping the flag in a valid state. + */ void ED_armature_ebone_remove_ex(struct bArmature *arm, struct EditBone *exBone, bool clear_connected); void ED_armature_ebone_remove(struct bArmature *arm, struct EditBone *exBone); bool ED_armature_ebone_is_child_recursive(struct EditBone *ebone_parent, struct EditBone *ebone_child); +/** + * Finds the first parent shared by \a ebone_child + * + * \param ebone_child: Children bones to search + * \param ebone_child_tot: Size of the ebone_child array + * \return The shared parent or NULL. + */ struct EditBone *ED_armature_ebone_find_shared_parent(struct EditBone *ebone_child[], const unsigned int ebone_child_tot); void ED_armature_ebone_to_mat3(struct EditBone *ebone, float r_mat[3][3]); void ED_armature_ebone_to_mat4(struct EditBone *ebone, float r_mat[4][4]); void ED_armature_ebone_from_mat3(struct EditBone *ebone, const float mat[3][3]); void ED_armature_ebone_from_mat4(struct EditBone *ebone, const float mat[4][4]); +/** + * Return a pointer to the bone of the given name + */ struct EditBone *ED_armature_ebone_find_name(const struct ListBase *edbo, const char *name); +/** + * \see #BKE_pose_channel_get_mirrored (pose-mode, matching function) + */ struct EditBone *ED_armature_ebone_get_mirrored(const struct ListBase *edbo, struct EditBone *ebo); void ED_armature_ebone_transform_mirror_update(struct bArmature *arm, struct EditBone *ebo, bool check_select); +/** + * If edit-bone (partial) selected, copy data. + * context; edit-mode armature, with mirror editing enabled. + */ void ED_armature_edit_transform_mirror_update(struct Object *obedit); +/** Put edit-mode back in Object. */ void ED_armature_from_edit(struct Main *bmain, struct bArmature *arm); +/** Put armature in edit-mode. */ void ED_armature_to_edit(struct bArmature *arm); void ED_armature_edit_free(struct bArmature *arm); void ED_armature_ebone_listbase_temp_clear(struct ListBase *lb); + +/** + * Free's bones and their properties. + */ void ED_armature_ebone_listbase_free(struct ListBase *lb, const bool do_id_user); void ED_armature_ebone_listbase_copy(struct ListBase *lb_dst, struct ListBase *lb_src, const bool do_id_user); -/* low level selection functions which handle */ int ED_armature_ebone_selectflag_get(const struct EditBone *ebone); void ED_armature_ebone_selectflag_set(struct EditBone *ebone, int flag); void ED_armature_ebone_select_set(struct EditBone *ebone, bool select); @@ -198,21 +297,29 @@ void ED_armature_ebone_selectflag_disable(struct EditBone *ebone, int flag); struct Object *ED_pose_object_from_context(struct bContext *C); bool ED_object_posemode_exit_ex(struct Main *bmain, struct Object *ob); bool ED_object_posemode_exit(struct bContext *C, struct Object *ob); +/** This function is used to process the necessary updates for. */ bool ED_object_posemode_enter_ex(struct Main *bmain, struct Object *ob); bool ED_object_posemode_enter(struct bContext *C, struct Object *ob); -/* Corresponds to eAnimvizCalcRange. */ +/** Corresponds to #eAnimvizCalcRange. */ typedef enum ePosePathCalcRange { POSE_PATH_CALC_RANGE_CURRENT_FRAME, POSE_PATH_CALC_RANGE_CHANGED, POSE_PATH_CALC_RANGE_FULL, } ePosePathCalcRange; +/** + * For the object with pose/action: 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_pose_recalculate_paths(struct bContext *C, struct Scene *scene, struct Object *ob, ePosePathCalcRange range); /* pose_select.c */ + void ED_armature_pose_select_pick_bone(struct ViewLayer *view_layer, struct View3D *v3d, struct Object *ob, @@ -220,6 +327,10 @@ void ED_armature_pose_select_pick_bone(struct ViewLayer *view_layer, bool extend, bool deselect, bool toggle); +/** + * Called for mode-less pose selection. + * assumes the active object is still on old situation. + */ bool ED_armature_pose_select_pick_with_buffer(struct ViewLayer *view_layer, struct View3D *v3d, struct Base *base, @@ -229,6 +340,14 @@ bool ED_armature_pose_select_pick_with_buffer(struct ViewLayer *view_layer, bool deselect, bool toggle, bool do_nearest); +/** + * While in weight-paint mode, a single pose may be active as well. + * While not common, it's possible we have multiple armatures deforming a mesh. + * + * This function de-selects all other objects, and selects the new base. + * It can't be set to the active object because we need + * to keep this set to the weight paint object. + */ void ED_armature_pose_select_in_wpaint_mode(struct ViewLayer *view_layer, struct Base *base_select); bool ED_pose_deselect_all_multi_ex(struct Base **bases, @@ -236,8 +355,16 @@ bool ED_pose_deselect_all_multi_ex(struct Base **bases, int select_mode, const bool ignore_visibility); bool ED_pose_deselect_all_multi(struct bContext *C, int select_mode, const bool ignore_visibility); +/** + * 'select_mode' is usual SEL_SELECT/SEL_DESELECT/SEL_TOGGLE/SEL_INVERT. + * When true, 'ignore_visibility' makes this func also affect invisible bones + * (hidden or on hidden layers). + */ bool ED_pose_deselect_all(struct Object *ob, int select_mode, const bool ignore_visibility); void ED_pose_bone_select_tag_update(struct Object *ob); +/** + * Utility method for changing the selection status of a bone. + */ void ED_pose_bone_select(struct Object *ob, struct bPoseChannel *pchan, bool select); /* meshlaplacian.c */ @@ -249,7 +376,9 @@ void ED_mesh_deform_bind_callback(struct MeshDeformModifierData *mmd, /* Pose backups, pose_backup.c */ struct PoseBackup; -/* Create a backup of those bones that are animated in the given action. */ +/** + * Create a backup of those bones that are animated in the given action. + */ struct PoseBackup *ED_pose_backup_create_selected_bones( const struct Object *ob, const struct bAction *action) ATTR_WARN_UNUSED_RESULT; struct PoseBackup *ED_pose_backup_create_all_bones( diff --git a/source/blender/editors/include/ED_buttons.h b/source/blender/editors/include/ED_buttons.h index af0643f0d64..79404aada41 100644 --- a/source/blender/editors/include/ED_buttons.h +++ b/source/blender/editors/include/ED_buttons.h @@ -30,6 +30,11 @@ struct ScrArea; struct SpaceProperties; struct bContext; +/** + * Fills an array with the tab context values for the properties editor. -1 signals a separator. + * + * \return The total number of items in the array returned. + */ int ED_buttons_tabs_list(struct SpaceProperties *sbuts, short *context_tabs_array); bool ED_buttons_tab_has_search_result(struct SpaceProperties *sbuts, const int index); diff --git a/source/blender/editors/include/ED_clip.h b/source/blender/editors/include/ED_clip.h index 21d8a28e2c9..6167ae3aee6 100644 --- a/source/blender/editors/include/ED_clip.h +++ b/source/blender/editors/include/ED_clip.h @@ -56,6 +56,9 @@ void ED_space_clip_get_zoom(struct SpaceClip *sc, void ED_space_clip_get_aspect(struct SpaceClip *sc, float *aspx, float *aspy); void ED_space_clip_get_aspect_dimension_aware(struct SpaceClip *sc, float *aspx, float *aspy); +/** + * Return current frame number in clip space. + */ int ED_space_clip_get_clip_frame_number(struct SpaceClip *sc); struct ImBuf *ED_space_clip_get_buffer(struct SpaceClip *sc); @@ -65,9 +68,12 @@ struct ImBuf *ED_space_clip_get_stable_buffer(struct SpaceClip *sc, float *angle); bool ED_space_clip_get_position(struct SpaceClip *sc, - struct ARegion *ar, + struct ARegion *region, int mval[2], float fpos[2]); +/** + * Returns color in linear space, matching #ED_space_image_color_sample(). + */ bool ED_space_clip_color_sample(struct SpaceClip *sc, struct ARegion *region, int mval[2], @@ -82,10 +88,17 @@ bool ED_clip_can_select(struct bContext *C); void ED_clip_point_undistorted_pos(struct SpaceClip *sc, const float co[2], float r_co[2]); void ED_clip_point_stable_pos( struct SpaceClip *sc, struct ARegion *region, float x, float y, float *xr, float *yr); +/** + * \brief the reverse of #ED_clip_point_stable_pos(), gets the marker region coords. + * better name here? view_to_track / track_to_view or so? + */ void ED_clip_point_stable_pos__reverse(struct SpaceClip *sc, struct ARegion *region, const float co[2], float r_co[2]); +/** + * Takes `event->mval`. + */ void ED_clip_mouse_pos(struct SpaceClip *sc, struct ARegion *region, const int mval[2], diff --git a/source/blender/editors/include/ED_curve.h b/source/blender/editors/include/ED_curve.h index 44c5897d3a3..805d42b6fbc 100644 --- a/source/blender/editors/include/ED_curve.h +++ b/source/blender/editors/include/ED_curve.h @@ -43,14 +43,22 @@ struct wmKeyConfig; struct wmOperator; /* curve_ops.c */ + void ED_operatortypes_curve(void); void ED_operatormacros_curve(void); void ED_keymap_curve(struct wmKeyConfig *keyconf); /* editcurve.c */ + struct ListBase *object_editcurve_get(struct Object *ob); +/** + * Load editNurb in object. + */ void ED_curve_editnurb_load(struct Main *bmain, struct Object *obedit); +/** + * Make copy in `cu->editnurb`. + */ void ED_curve_editnurb_make(struct Object *obedit); void ED_curve_editnurb_free(struct Object *obedit); @@ -65,9 +73,14 @@ int ED_curve_nurb_select_count(const struct View3D *v3d, const struct Nurb *nu); bool ED_curve_nurb_select_all(const struct Nurb *nu); bool ED_curve_nurb_deselect_all(const struct Nurb *nu); +/** + * This is used externally, by #OBJECT_OT_join. + * TODO: shape keys - as with meshes. + */ int ED_curve_join_objects_exec(struct bContext *C, struct wmOperator *op); /* editcurve_select.c */ + bool ED_curve_select_check(const struct View3D *v3d, const struct EditNurb *editnurb); bool ED_curve_deselect_all(struct EditNurb *editnurb); bool ED_curve_deselect_all_multi_ex(struct Base **bases, int bases_len); @@ -77,9 +90,12 @@ bool ED_curve_select_swap(struct EditNurb *editnurb, bool hide_handles); int ED_curve_select_count(const struct View3D *v3d, const struct EditNurb *editnurb); /* editcurve_undo.c */ + +/** Export for ED_undo_sys */ void ED_curve_undosys_type(struct UndoType *ut); /* editfont.c */ + void ED_curve_editfont_load(struct Object *obedit); void ED_curve_editfont_make(struct Object *obedit); void ED_curve_editfont_free(struct Object *obedit); @@ -92,14 +108,22 @@ void ED_curve_beztcpy(struct EditNurb *editnurb, int count); void ED_curve_bpcpy(struct EditNurb *editnurb, struct BPoint *dst, struct BPoint *src, int count); +/** + * Return 0 if animation data wasn't changed, 1 otherwise. + */ int ED_curve_updateAnimPaths(struct Main *bmain, struct Curve *cu); bool ED_curve_active_center(struct Curve *cu, float center[3]); +/** + * TextBox selection + */ bool ED_curve_editfont_select_pick( struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle); /* editfont_undo.c */ + +/** Export for ED_undo_sys. */ void ED_font_undosys_type(struct UndoType *ut); #if 0 diff --git a/source/blender/editors/include/ED_file_indexer.h b/source/blender/editors/include/ED_file_indexer.h new file mode 100644 index 00000000000..0afa8819def --- /dev/null +++ b/source/blender/editors/include/ED_file_indexer.h @@ -0,0 +1,153 @@ +/* + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software Foundation, + * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + */ + +/** \file + * \ingroup edfile + */ + +#pragma once + +#include "BLO_readfile.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * File indexing for the file/asset browser. + * + * This file contains an API to create indexing functionality when listing blend files in + * the file browser. + * + * To implement a custom indexer a `FileIndexerType` struct should be made and passed to the + * `filelist_setindexer` function. + */ + +struct AssetLibraryReference; +struct LinkNode; + +/** + * Result code of the `read_index` callback. + */ +typedef enum eFileIndexerResult { + /** + * File listing entries are loaded from the index. Reading entries from the blend file itself + * should be skipped. + */ + FILE_INDEXER_ENTRIES_LOADED, + + /** + * Index isn't available or not up to date. Entries should be read from the blend file and + * `update_index` must be called to update the index. + */ + FILE_INDEXER_NEEDS_UPDATE, +} eFileIndexerResult; + +/** + * FileIndexerEntry contains all data that is required to create a file listing entry. + */ +typedef struct FileIndexerEntry { + struct BLODataBlockInfo datablock_info; + short idcode; +} FileIndexerEntry; + +/** + * Contains all entries of a blend file. + */ +typedef struct FileIndexerEntries { + struct LinkNode /* FileIndexerEntry */ *entries; +} FileIndexerEntries; + +typedef void *(*FileIndexerInitUserDataFunc)(const char *root_directory, + size_t root_directory_maxlen); +typedef void (*FileIndexerFreeUserDataFunc)(void *); +typedef void (*FileIndexerFinishedFunc)(void *); +typedef eFileIndexerResult (*FileIndexerReadIndexFunc)(const char *file_name, + FileIndexerEntries *entries, + int *r_read_entries_len, + void *user_data); +typedef void (*FileIndexerUpdateIndexFunc)(const char *file_name, + FileIndexerEntries *entries, + void *user_data); + +typedef struct FileIndexerType { + /** + * Is called at the beginning of the file listing process. An indexer can + * setup needed data. The result of this function will be passed around as `user_data` parameter. + * + * This is an optional callback. + */ + FileIndexerInitUserDataFunc init_user_data; + + /** + * Is called at the end of the file listing process. An indexer can free the data that it created + * during the file listing process. + * + * This is an optional callback */ + FileIndexerFreeUserDataFunc free_user_data; + + /** + * Is called at the end of the file listing process (before the `free_user_data`) where indexes + * can perform clean-ups. + * + * This is an optional callback. Called when listing files completed. + */ + FileIndexerFinishedFunc filelist_finished; + + /** + * Is called for each blend file being listed to read data from the index. + * + * Read entries should be added to given `entries` parameter (type: `FileIndexerEntries`). + * `*r_read_entries_len` must be set to the number of read entries. + * and the function must return `eFileIndexerResult::FILE_INDEXER_ENTRIES_LOADED`. + * In this case the blend file will not be opened and the FileIndexerEntry added to `entries` + * will be used as the content of the file. + * + * When the index isn't available or could not be used no entries must be added to the + * entries field, `r_read_entries_len` must be set to `0` and the function must return + * `eFileIndexerResult::FILE_INDEXER_NEEDS_UPDATE`. In this case the blend file will read from + * the blend file and the `update_index` function will be called. + */ + FileIndexerReadIndexFunc read_index; + + /** + * Update an index of a blend file. + * + * Is called after reading entries from the file when the result of `read_index` was + * `eFileIndexerResult::FILE_INDEXER_NEED_UPDATE`. The callback should update the index so the + * next time that read_index is called it will read the entries from the index. + */ + FileIndexerUpdateIndexFunc update_index; +} FileIndexerType; + +/* file_indexer.cc */ + +/** Removes all entries inside the given `indexer_entries`. */ +void ED_file_indexer_entries_clear(FileIndexerEntries *indexer_entries); + +/** + * Adds all entries from the given `datablock_infos` to the `indexer_entries`. + * The datablock_infos must only contain data for a single IDType. The specific IDType must be + * passed in the `idcode` parameter. + */ +void ED_file_indexer_entries_extend_from_datablock_infos( + FileIndexerEntries *indexer_entries, + const LinkNode * /* BLODataBlockInfo */ datablock_infos, + const int idcode); + +#ifdef __cplusplus +} +#endif diff --git a/source/blender/editors/include/ED_fileselect.h b/source/blender/editors/include/ED_fileselect.h index 68b6e44371c..460de58bdb2 100644 --- a/source/blender/editors/include/ED_fileselect.h +++ b/source/blender/editors/include/ED_fileselect.h @@ -105,12 +105,26 @@ typedef struct FileSelection { struct View2D; struct rcti; +/** + * If needed, create and return the file select parameters for the active browse mode. + */ struct FileSelectParams *ED_fileselect_ensure_active_params(struct SpaceFile *sfile); +/** + * Get the file select parameters for the active browse mode. + */ struct FileSelectParams *ED_fileselect_get_active_params(const struct SpaceFile *sfile); struct FileSelectParams *ED_fileselect_get_file_params(const struct SpaceFile *sfile); struct FileAssetSelectParams *ED_fileselect_get_asset_params(const struct SpaceFile *sfile); +bool ED_fileselect_is_local_asset_library(const struct SpaceFile *sfile); void ED_fileselect_set_params_from_userdef(struct SpaceFile *sfile); +/** + * Update the user-preference data for the file space. In fact, this also contains some + * non-FileSelectParams data, but we can safely ignore this. + * + * \param temp_win_size: If the browser was opened in a temporary window, + * pass its size here so we can store that in the preferences. Otherwise NULL. + */ void ED_fileselect_params_to_userdef(struct SpaceFile *sfile, const int temp_win_size[2], const bool is_maximized); @@ -123,6 +137,10 @@ int ED_fileselect_layout_numfiles(FileLayout *layout, struct ARegion *region); int ED_fileselect_layout_offset(FileLayout *layout, int x, int y); FileSelection ED_fileselect_layout_offset_rect(FileLayout *layout, const struct rcti *rect); +/** + * Get the currently visible bounds of the layout in screen space. Matches View2D.mask minus the + * top column-header row. + */ void ED_fileselect_layout_maskrect(const FileLayout *layout, const struct View2D *v2d, struct rcti *r_rect); @@ -149,8 +167,10 @@ struct ID *ED_fileselect_active_asset_get(const struct SpaceFile *sfile); void ED_fileselect_activate_asset_catalog(const struct SpaceFile *sfile, bUUID catalog_id); -/* Activate and select the file that corresponds to the given ID. - * Pass deferred=true to wait for the next refresh before activating. */ +/** + * Activate and select the file that corresponds to the given ID. + * Pass deferred=true to wait for the next refresh before activating. + */ void ED_fileselect_activate_by_id(struct SpaceFile *sfile, struct ID *asset_id, const bool deferred); @@ -165,12 +185,18 @@ void ED_fileselect_window_params_get(const struct wmWindow *win, struct ScrArea *ED_fileselect_handler_area_find(const struct wmWindow *win, const struct wmOperator *file_operator); +/* TODO: Maybe we should move this to BLI? + * On the other hand, it's using defines from space-file area, so not sure... */ int ED_path_extension_type(const char *path); int ED_file_extension_icon(const char *path); int ED_file_icon(const struct FileDirEntry *file); void ED_file_read_bookmarks(void); +/** + * Support updating the directory even when this isn't the active space + * needed so RNA properties update function isn't context sensitive, see T70255. + */ void ED_file_change_dir_ex(struct bContext *C, struct ScrArea *area); void ED_file_change_dir(struct bContext *C); diff --git a/source/blender/editors/include/ED_gizmo_library.h b/source/blender/editors/include/ED_gizmo_library.h index 4d922162ee9..55beff40177 100644 --- a/source/blender/editors/include/ED_gizmo_library.h +++ b/source/blender/editors/include/ED_gizmo_library.h @@ -92,7 +92,17 @@ enum { ED_GIZMO_ARROW_DRAW_FLAG_STEM = (1 << 0), }; +/** + * Define a custom property UI range. + * + * \note Needs to be called before #WM_gizmo_target_property_def_rna! + */ void ED_gizmo_arrow3d_set_ui_range(struct wmGizmo *gz, const float min, const float max); +/** + * Define a custom factor for arrow min/max distance. + * + * \note Needs to be called before #WM_gizmo_target_property_def_rna! + */ void ED_gizmo_arrow3d_set_range_fac(struct wmGizmo *gz, const float range_fac); /* -------------------------------------------------------------------- */ diff --git a/source/blender/editors/include/ED_gpencil.h b/source/blender/editors/include/ED_gpencil.h index 1cf15ce3a48..99164bbe439 100644 --- a/source/blender/editors/include/ED_gpencil.h +++ b/source/blender/editors/include/ED_gpencil.h @@ -116,42 +116,97 @@ typedef struct tGPspoint { /* ----------- Grease Pencil Tools/Context ------------- */ /* Context-dependent */ + +/** + * Get pointer to active Grease Pencil data-block, + * and an RNA-pointer to trace back to whatever owns it. + */ struct bGPdata **ED_gpencil_data_get_pointers(const struct bContext *C, struct PointerRNA *r_ptr); +/** + * Get the active Grease Pencil data-block + */ struct bGPdata *ED_gpencil_data_get_active(const struct bContext *C); +/** + * Get the evaluated copy of the active Grease Pencil data-block (where applicable) + * - For the 3D View (i.e. "GP Objects"), this gives the evaluated copy of the GP data-block + * (i.e. a copy of the active GP data-block for the active object, where modifiers have been + * applied). This is needed to correctly work with "Copy-on-Write". + * - For all other editors (i.e. "GP Annotations"), this just gives the active data-block + * like for #ED_gpencil_data_get_active() + */ struct bGPdata *ED_gpencil_data_get_active_evaluated(const struct bContext *C); -/* Context independent (i.e. each required part is passed in instead) */ +/** + * Context independent (i.e. each required part is passed in instead). + * + * Get pointer to active Grease Pencil data-block, + * and an RNA-pointer to trace back to whatever owns it, + * when context info is not available. + */ struct bGPdata **ED_gpencil_data_get_pointers_direct(struct ScrArea *area, struct Object *ob, struct PointerRNA *r_ptr); +/* Get the active Grease Pencil data-block, when context is not available */ struct bGPdata *ED_gpencil_data_get_active_direct(struct ScrArea *area, struct Object *ob); +/** + * Get the active Grease Pencil data-block + * \note This is the original (#G.main) copy of the data-block, stored in files. + * Do not use for reading evaluated copies of GP Objects data. + */ struct bGPdata *ED_annotation_data_get_active(const struct bContext *C); +/** + * Get pointer to active Grease Pencil data-block, + * and an RNA-pointer to trace back to whatever owns it. + */ struct bGPdata **ED_annotation_data_get_pointers(const struct bContext *C, struct PointerRNA *r_ptr); +/** + * Get pointer to active Grease Pencil data-block for annotations, + * and an RNA-pointer to trace back to whatever owns it, + * when context info is not available. + */ struct bGPdata **ED_annotation_data_get_pointers_direct(struct ID *screen_id, struct ScrArea *area, struct Scene *scene, struct PointerRNA *r_ptr); +/** + * Get the active Grease Pencil data-block, when context is not available. + */ struct bGPdata *ED_annotation_data_get_active_direct(struct ID *screen_id, struct ScrArea *area, struct Scene *scene); +/** + * Utility to check whether the r_ptr output of ED_gpencil_data_get_pointers() + * is for annotation usage. + */ bool ED_gpencil_data_owner_is_annotation(struct PointerRNA *owner_ptr); /* 3D View */ + +/** + * Check whether there's an active GP keyframe on the current frame. + */ bool ED_gpencil_has_keyframe_v3d(struct Scene *scene, struct Object *ob, int cfra); /* ----------- Stroke Editing Utilities ---------------- */ bool ED_gpencil_frame_has_selected_stroke(const struct bGPDframe *gpf); bool ED_gpencil_layer_has_selected_stroke(const struct bGPDlayer *gpl, const bool is_multiedit); +/** + * Check whether given stroke can be edited given the supplied context. + * TODO: do we need additional flags for screen-space vs data-space?. + */ bool ED_gpencil_stroke_can_use_direct(const struct ScrArea *area, const struct bGPDstroke *gps); +/* Check whether given stroke can be edited in the current context */ bool ED_gpencil_stroke_can_use(const struct bContext *C, const struct bGPDstroke *gps); +/* Check whether given stroke can be edited for the current color */ bool ED_gpencil_stroke_material_editable(struct Object *ob, const struct bGPDlayer *gpl, const struct bGPDstroke *gps); +/* Check whether given stroke is visible for the current material. */ bool ED_gpencil_stroke_material_visible(struct Object *ob, const struct bGPDstroke *gps); /* ----------- Grease Pencil Operators ----------------- */ @@ -164,13 +219,32 @@ void ED_operatormacros_gpencil(void); /* ------------- Copy-Paste Buffers -------------------- */ /* Strokes copybuf */ + +/** + * Free copy/paste buffer data. + */ void ED_gpencil_strokes_copybuf_free(void); /* ------------ Grease-Pencil Drawing API ------------------ */ /* drawgpencil.c */ +/** + * Draw grease-pencil sketches to specified 2d-view that uses ibuf corrections. + */ void ED_annotation_draw_2dimage(const struct bContext *C); +/** + * Draw grease-pencil sketches to specified 2d-view + * assuming that matrices are already set correctly. + * + * \note This gets called twice - first time with onlyv2d=true to draw 'canvas' strokes, + * second time with onlyv2d=false for screen-aligned strokes. + */ void ED_annotation_draw_view2d(const struct bContext *C, bool onlyv2d); +/** + * Draw annotations sketches to specified 3d-view assuming that matrices are already set correctly. + * NOTE: this gets called twice - first time with only3d=true to draw 3d-strokes, + * second time with only3d=false for screen-aligned strokes. + */ void ED_annotation_draw_view3d(struct Scene *scene, struct Depsgraph *depsgraph, struct View3D *v3d, @@ -184,43 +258,103 @@ void ED_annotation_draw_ex(struct Scene *scene, const char spacetype); /* ----------- Grease-Pencil AnimEdit API ------------------ */ +/** + * Loops over the gp-frames for a gp-layer, and applies the given callback. + */ bool ED_gpencil_layer_frames_looper(struct bGPDlayer *gpl, struct Scene *scene, bool (*gpf_cb)(struct bGPDframe *, struct Scene *)); +/** + * Make a listing all the gp-frames in a layer as cfraelems. + */ void ED_gpencil_layer_make_cfra_list(struct bGPDlayer *gpl, ListBase *elems, bool onlysel); +/** + * Check if one of the frames in this layer is selected. + */ bool ED_gpencil_layer_frame_select_check(const struct bGPDlayer *gpl); +/** + * Set all/none/invert select. + */ void ED_gpencil_layer_frame_select_set(struct bGPDlayer *gpl, short mode); +/** + * Select the frames in this layer that occur within the bounds specified. + */ void ED_gpencil_layer_frames_select_box(struct bGPDlayer *gpl, float min, float max, short select_mode); +/** + * Select the frames in this layer that occur within the lasso/circle region specified. + */ void ED_gpencil_layer_frames_select_region(struct KeyframeEditData *ked, struct bGPDlayer *gpl, short tool, short select_mode); +/** + * Set all/none/invert select (like above, but with SELECT_* modes). + */ void ED_gpencil_select_frames(struct bGPDlayer *gpl, short select_mode); +/** + * Select the frame in this layer that occurs on this frame (there should only be one at most). + */ void ED_gpencil_select_frame(struct bGPDlayer *gpl, int selx, short select_mode); +/** + * Delete selected frames. + */ bool ED_gpencil_layer_frames_delete(struct bGPDlayer *gpl); +/** + * Duplicate selected frames from given gp-layer. + */ void ED_gpencil_layer_frames_duplicate(struct bGPDlayer *gpl); +/** + * Merge two layers. + */ void ED_gpencil_layer_merge(struct bGPdata *gpd, struct bGPDlayer *gpl_src, struct bGPDlayer *gpl_dst, const bool reverse); +/** + * Set keyframe type for selected frames from given gp-layer + * + * \param type: The type of keyframe (#eBezTriple_KeyframeType) to set selected frames to. + */ void ED_gpencil_layer_frames_keytype_set(struct bGPDlayer *gpl, short type); - +/** + * Snap selected frames to .... + */ void ED_gpencil_layer_snap_frames(struct bGPDlayer *gpl, struct Scene *scene, short mode); + +/** + * Mirror selected gp-frames on... + * TODO: mirror over a specific time. + */ void ED_gpencil_layer_mirror_frames(struct bGPDlayer *gpl, struct Scene *scene, short mode); +/** + * This function frees any MEM_calloc'ed copy/paste buffer data. + */ void ED_gpencil_anim_copybuf_free(void); +/** + * This function adds data to the copy/paste buffer, freeing existing data first + * Only the selected GP-layers get their selected keyframes copied. + * + * Returns whether the copy operation was successful or not. + */ bool ED_gpencil_anim_copybuf_copy(struct bAnimContext *ac); +/** + * Pastes keyframes from buffer, and reports success. + */ bool ED_gpencil_anim_copybuf_paste(struct bAnimContext *ac, const short copy_mode); /* ------------ Grease-Pencil Undo System ------------------ */ int ED_gpencil_session_active(void); +/** + * \param step: eUndoStepDir. + */ int ED_undo_gpencil_step(struct bContext *C, const int step); /* eUndoStepDir. */ /* ------------ Grease-Pencil Armature ------------------ */ @@ -234,7 +368,10 @@ bool ED_gpencil_add_armature_weights(const struct bContext *C, struct Object *ob_arm, int mode); -/* Add Lattice modifier using Parent operator */ +/** + * Add Lattice modifier using Parent operator. + * Parent GPencil object to Lattice. + */ bool ED_gpencil_add_lattice_modifier(const struct bContext *C, struct ReportList *reports, struct Object *ob, @@ -246,37 +383,74 @@ bool ED_gpencil_add_lattice_modifier(const struct bContext *C, /* ------------ Transformation Utilities ------------ */ -/* reset parent matrix for all layers */ +/** + * Reset parent matrix for all layers. + */ void ED_gpencil_reset_layers_parent(struct Depsgraph *depsgraph, struct Object *obact, struct bGPdata *gpd); -/* cursor utilities */ +/* Cursor utilities. */ + +/** + * Draw eraser cursor. + */ void ED_gpencil_brush_draw_eraser(struct Brush *brush, int x, int y); /* ----------- Add Primitive Utilities -------------- */ -/* Number of values defining each point in the built-in data buffers for primitives. */ +/** Number of values defining each point in the built-in data buffers for primitives. */ #define GP_PRIM_DATABUF_SIZE 5 +/** + * Populate stroke with point data from data buffers. + * \param gps: Grease pencil stroke + * \param array: Flat array of point data values. Each entry has #GP_PRIM_DATABUF_SIZE values. + * \param totpoints: Total of points + * \param mat: 4x4 transform matrix to transform points into the right coordinate space. + */ void ED_gpencil_stroke_init_data(struct bGPDstroke *gps, const float *array, const int totpoints, const float mat[4][4]); +/** + * Add a Simple empty object with one layer and one color. + */ void ED_gpencil_create_blank(struct bContext *C, struct Object *ob, float mat[4][4]); +/** + * Add a 2D Suzanne (original model created by Matias Mendiola). + */ void ED_gpencil_create_monkey(struct bContext *C, struct Object *ob, float mat[4][4]); +/** + * Add a Simple stroke with colors + * (original design created by Daniel M. Lara and Matias Mendiola). + */ void ED_gpencil_create_stroke(struct bContext *C, struct Object *ob, float mat[4][4]); +/** + * Add a Simple LineArt setup. + */ void ED_gpencil_create_lineart(struct bContext *C, struct Object *ob); /* ------------ Object Utilities ------------ */ +/** + * Helper function to create new #OB_GPENCIL Object. + */ struct Object *ED_gpencil_add_object(struct bContext *C, const float loc[3], unsigned short local_view_bits); +/** + * Helper function to create default colors and drawing brushes. + */ void ED_gpencil_add_defaults(struct bContext *C, struct Object *ob); -/* set object modes */ +/** + * Set object modes. + */ void ED_gpencil_setup_modes(struct bContext *C, struct bGPdata *gpd, int newmode); bool ED_object_gpencil_exit(struct Main *bmain, struct Object *ob); +/** + * Reproject all points of the stroke to a plane locked to axis to avoid stroke offset + */ void ED_gpencil_project_stroke_to_plane(const struct Scene *scene, const struct Object *ob, const struct RegionView3D *rv3d, @@ -284,6 +458,10 @@ void ED_gpencil_project_stroke_to_plane(const struct Scene *scene, struct bGPDstroke *gps, const float origin[3], const int axis); +/** + * Reproject given point to a plane locked to axis to avoid stroke offset + * \param pt: Point to affect (used for input & output). + */ void ED_gpencil_project_point_to_plane(const struct Scene *scene, const struct Object *ob, struct bGPDlayer *gpl, @@ -291,14 +469,21 @@ void ED_gpencil_project_point_to_plane(const struct Scene *scene, const float origin[3], const int axis, struct bGPDspoint *pt); +/** + * Get drawing reference point for conversion or projection of the stroke + * \param r_vec: Reference point found + */ void ED_gpencil_drawing_reference_get(const struct Scene *scene, const struct Object *ob, char align_flag, - float vec[3]); + float r_vec[3]); void ED_gpencil_project_stroke_to_view(struct bContext *C, struct bGPDlayer *gpl, struct bGPDstroke *gps); +/** + * Reproject selected strokes. + */ void ED_gpencil_stroke_reproject(struct Depsgraph *depsgraph, const struct GP_SpaceConversion *gsc, struct SnapObjectContext *sctx, @@ -308,27 +493,54 @@ void ED_gpencil_stroke_reproject(struct Depsgraph *depsgraph, const eGP_ReprojectModes mode, const bool keep_original); -/* set sculpt cursor */ +/** + * Turn brush cursor in on/off. + */ void ED_gpencil_toggle_brush_cursor(struct bContext *C, bool enable, void *customdata); /* vertex groups */ + +/** + * Assign points to vertex group. + */ void ED_gpencil_vgroup_assign(struct bContext *C, struct Object *ob, float weight); +/** + * Remove points from vertex group. + */ void ED_gpencil_vgroup_remove(struct bContext *C, struct Object *ob); +/** + * Select points of vertex group. + */ void ED_gpencil_vgroup_select(struct bContext *C, struct Object *ob); +/** + * Unselect points of vertex group. + */ void ED_gpencil_vgroup_deselect(struct bContext *C, struct Object *ob); /* join objects */ + +/** + * Join objects called from OBJECT_OT_join. + */ int ED_gpencil_join_objects_exec(struct bContext *C, struct wmOperator *op); /* texture coordinate utilities */ + +/** + * Convert 2d #tGPspoint to 3d #bGPDspoint. + */ void ED_gpencil_tpoint_to_point(struct ARegion *region, float origin[3], const struct tGPspoint *tpt, struct bGPDspoint *pt); +/** + * Recalculate UV for any stroke using the material. + */ void ED_gpencil_update_color_uv(struct Main *bmain, struct Material *mat); -/* extend selection to stroke intersections - * returns: +/** + * Extend selection to stroke intersections: + * \returns: * 0 - No hit * 1 - Hit in point A * 2 - Hit in point B @@ -347,17 +559,23 @@ int ED_gpencil_select_stroke_segment(struct bGPdata *gpd, void ED_gpencil_select_toggle_all(struct bContext *C, int action); void ED_gpencil_select_curve_toggle_all(struct bContext *C, int action); -/* Ensure stroke sbuffer size is enough */ +/** + * Ensure the #tGPspoint buffer (while drawing stroke) + * size is enough to save all points of the stroke. + */ struct tGPspoint *ED_gpencil_sbuffer_ensure(struct tGPspoint *buffer_array, int *buffer_size, int *buffer_used, const bool clear); void ED_gpencil_sbuffer_update_eval(struct bGPdata *gpd, struct Object *ob_eval); -/* Tag all scene grease pencil object to update. */ +/** + * Tag all scene grease pencil object to update. + */ void ED_gpencil_tag_scene_gpencil(struct Scene *scene); /* Vertex color set. */ + void ED_gpencil_fill_vertex_color_set(struct ToolSettings *ts, struct Brush *brush, struct bGPDstroke *gps); @@ -376,15 +594,30 @@ void ED_gpencil_init_random_settings(struct Brush *brush, const int mval[2], struct GpRandomSettings *random_settings); +/** + * Check if the stroke collides with brush. + */ bool ED_gpencil_stroke_check_collision(const struct GP_SpaceConversion *gsc, struct bGPDstroke *gps, const float mouse[2], const int radius, const float diff_mat[4][4]); +/** + * Check if a point is inside of the stroke. + * + * \param gps: Stroke to check. + * \param gsc: Space conversion data. + * \param mouse: Mouse position. + * \param diff_mat: View matrix. + * \return True if the point is inside. + */ bool ED_gpencil_stroke_point_is_inside(const struct bGPDstroke *gps, const struct GP_SpaceConversion *gsc, const int mouse[2], const float diff_mat[4][4]); +/** + * Get the bigger 2D bound box points. + */ void ED_gpencil_projected_2d_bound_box(const struct GP_SpaceConversion *gsc, const struct bGPDstroke *gps, const float diff_mat[4][4], @@ -400,18 +633,27 @@ struct bGPDstroke *ED_gpencil_stroke_nearest_to_ends(struct bContext *C, const float ctrl2[2], const float radius, int *r_index); +/** + * Get extremes of stroke in 2D using current view. + */ void ED_gpencil_stroke_extremes_to2d(const struct GP_SpaceConversion *gsc, const float diff_mat[4][4], struct bGPDstroke *gps, float r_ctrl1[2], float r_ctrl2[2]); +/** + * Join two stroke using a contact point index and trimming the rest. + */ struct bGPDstroke *ED_gpencil_stroke_join_and_trim(struct bGPdata *gpd, struct bGPDframe *gpf, struct bGPDstroke *gps, struct bGPDstroke *gps_dst, const int pt_index); +/** + * Close if the distance between extremes is below threshold. + */ void ED_gpencil_stroke_close_by_distance(struct bGPDstroke *gps, const float threshold); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_image.h b/source/blender/editors/include/ED_image.h index 1400bcf5ee3..3308ae2c178 100644 --- a/source/blender/editors/include/ED_image.h +++ b/source/blender/editors/include/ED_image.h @@ -48,11 +48,17 @@ float ED_space_image_zoom_level(const struct View2D *v2d, const int grid_dimensi void ED_space_image_grid_steps(struct SpaceImage *sima, float grid_steps[SI_GRID_STEPS_LEN], const int grid_dimension); +/** + * Calculate the increment snapping value for UV/image editor based on the zoom factor + * The code in here (except the offset part) is used in `grid_frag.glsl` (see `grid_res`) for + * drawing the grid overlay for the UV/Image editor. + */ float ED_space_image_increment_snap_value(const int grid_dimesnions, const float grid_steps[SI_GRID_STEPS_LEN], const float zoom_factor); -/* image_edit.c, exported for transform */ +/* image_edit.c, exported for transform. */ + struct Image *ED_space_image(const struct SpaceImage *sima); void ED_space_image_set(struct Main *bmain, struct SpaceImage *sima, @@ -62,13 +68,22 @@ void ED_space_image_auto_set(const struct bContext *C, struct SpaceImage *sima); struct Mask *ED_space_image_get_mask(const struct SpaceImage *sima); void ED_space_image_set_mask(struct bContext *C, struct SpaceImage *sima, struct Mask *mask); +/** + * Returns mouse position in image space. + */ bool ED_space_image_get_position(struct SpaceImage *sima, struct ARegion *region, int mval[2], float fpos[2]); +/** + * Returns color in linear space, matching #ED_space_node_color_sample(). + */ bool ED_space_image_color_sample( struct SpaceImage *sima, struct ARegion *region, int mval[2], float r_col[3], bool *r_is_data); struct ImBuf *ED_space_image_acquire_buffer(struct SpaceImage *sima, void **r_lock, int tile); +/** + * Get the #SpaceImage flag that is valid for the given ibuf. + */ int ED_space_image_get_display_channel_mask(struct ImBuf *ibuf); void ED_space_image_release_buffer(struct SpaceImage *sima, struct ImBuf *ibuf, void *lock); bool ED_space_image_has_buffer(struct SpaceImage *sima); @@ -87,6 +102,12 @@ void ED_space_image_scopes_update(const struct bContext *C, struct ImBuf *ibuf, bool use_view_settings); +/** + * Enable the paint cursor if it isn't already. + * + * purpose is to make sure the paint cursor is shown if paint mode is enabled in the image editor. + * The paint poll will ensure that the cursor is hidden when not in paint mode. + */ void ED_space_image_paint_update(struct Main *bmain, struct wmWindowManager *wm, struct Scene *scene); @@ -95,6 +116,7 @@ void ED_image_get_uv_aspect(struct Image *ima, struct ImageUser *iuser, float *r_aspx, float *r_aspy); +/** Takes `event->mval`. */ void ED_image_mouse_pos(struct SpaceImage *sima, const struct ARegion *region, const int mval[2], @@ -110,6 +132,10 @@ void ED_image_point_pos__reverse(struct SpaceImage *sima, const struct ARegion *region, const float co[2], float r_co[2]); +/** + * This is more a user-level functionality, for going to `next/prev` used slot, + * Stepping onto the last unused slot too. + */ bool ED_image_slot_cycle(struct Image *image, int direction); bool ED_space_image_show_render(const struct SpaceImage *sima); @@ -118,11 +144,17 @@ bool ED_space_image_show_uvedit(const struct SpaceImage *sima, struct Object *ob bool ED_space_image_paint_curve(const struct bContext *C); +/** + * Matches clip function. + */ bool ED_space_image_check_show_maskedit(struct SpaceImage *sima, struct Object *obedit); bool ED_space_image_maskedit_poll(struct bContext *C); bool ED_space_image_maskedit_mask_poll(struct bContext *C); bool ED_space_image_cursor_poll(struct bContext *C); +/** + * Used by node view too. + */ void ED_image_draw_info(struct Scene *scene, struct ARegion *region, bool color_manage, @@ -161,6 +193,9 @@ typedef struct ImageFrameRange { ListBase frames; } ImageFrameRange; +/** + * Used for both images and volume file loading. + */ ListBase ED_image_filesel_detect_sequences(struct Main *bmain, struct wmOperator *op, const bool detect_udim); diff --git a/source/blender/editors/include/ED_info.h b/source/blender/editors/include/ED_info.h index dde26c072d0..caf76841bcd 100644 --- a/source/blender/editors/include/ED_info.h +++ b/source/blender/editors/include/ED_info.h @@ -39,6 +39,11 @@ const char *ED_info_statistics_string(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer); +/** + * \param v3d_local: Pass this argument to calculate view-port local statistics. + * Note that this must only be used for local-view, otherwise report specific statistics + * will be written into the global scene statistics giving incorrect results. + */ void ED_info_draw_stats(struct Main *bmain, struct Scene *scene, struct ViewLayer *view_layer, diff --git a/source/blender/editors/include/ED_keyframes_edit.h b/source/blender/editors/include/ED_keyframes_edit.h index e29ff3ed890..bafe68bd28d 100644 --- a/source/blender/editors/include/ED_keyframes_edit.h +++ b/source/blender/editors/include/ED_keyframes_edit.h @@ -39,7 +39,9 @@ struct bDopeSheet; /* ************************************************ */ /* Common Macros and Defines */ -/* --------- Tool Flags ------------ */ +/* -------------------------------------------------------------------- */ +/** \name Tool Flags + * \{ */ /* bezt validation */ typedef enum eEditKeyframes_Validate { @@ -60,7 +62,7 @@ typedef enum eEditKeyframes_Validate { BEZT_OK_CHANNEL_CIRCLE, } eEditKeyframes_Validate; -/* ------------ */ +/** \} */ /* select modes */ typedef enum eEditKeyframes_Select { @@ -120,7 +122,9 @@ typedef struct KeyframeEdit_CircleData { /* ************************************************ */ /* Non-Destructive Editing API (keyframes_edit.c) */ -/* --- Defines for 'OK' polls + KeyframeEditData Flags --------- */ +/* -------------------------------------------------------------------- */ +/** \name Defines for 'OK' polls + KeyframeEditData Flags + * \{ */ /* which verts of a keyframe is active (after polling) */ typedef enum eKeyframeVertOk { @@ -154,7 +158,11 @@ typedef enum eKeyframeIterFlags { KEYFRAME_ITER_HANDLES_DEFAULT_INVISIBLE = (1 << 3), } eKeyframeIterFlags; -/* --- Generic Properties for Keyframe Edit Tools ----- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Generic Properties for Keyframe Edit Tools + * \{ */ typedef struct KeyframeEditData { /* generic properties/data access */ @@ -184,14 +192,22 @@ typedef struct KeyframeEditData { eKeyframeIterFlags iterflags; } KeyframeEditData; -/* ------- Function Pointer Typedefs ---------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Function Pointer Typedefs + * \{ */ /* callback function that refreshes the F-Curve after use */ typedef void (*FcuEditFunc)(struct FCurve *fcu); /* callback function that operates on the given BezTriple */ typedef short (*KeyframeEditFunc)(KeyframeEditData *ked, struct BezTriple *bezt); -/* ------- Custom Data Type Defines ------------------ */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Custom Data Type Defines + * \{ */ /* Custom data for remapping one range to another in a fixed way */ typedef struct KeyframeEditCD_Remap { @@ -222,18 +238,28 @@ typedef enum eKeyMergeMode { KEYFRAME_PASTE_MERGE_OVER_RANGE_ALL, } eKeyMergeMode; -/* ---------------- Looping API --------------------- */ +/** \} */ -/* functions for looping over keyframes */ -/* function for working with F-Curve data only - * (i.e. when filters have been chosen to explicitly use this) */ +/* -------------------------------------------------------------------- */ +/** \name Looping API + * + * Functions for looping over keyframes. + * \{ */ + +/** + * This function is used to loop over BezTriples in the given F-Curve, applying a given + * operation on them, and optionally applies an F-Curve validation function afterwards. + * + * function for working with F-Curve data only + * (i.e. when filters have been chosen to explicitly use this). + */ short ANIM_fcurve_keyframes_loop(KeyframeEditData *ked, struct FCurve *fcu, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb); -/* function for working with any type (i.e. one of the known types) of animation channel - * - filterflag is bDopeSheet->flag (DOPESHEET_FILTERFLAG) +/** + * Function for working with any type (i.e. one of the known types) of animation channel. */ short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, @@ -241,8 +267,9 @@ short ANIM_animchannel_keyframes_loop(KeyframeEditData *ked, KeyframeEditFunc key_ok, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb); -/* same as above, except bAnimListElem wrapper is not needed... - * - keytype is eAnim_KeyType +/** + * Same as above, except bAnimListElem wrapper is not needed. + * \param keytype: is #eAnim_KeyType. */ short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, struct bDopeSheet *ads, @@ -252,55 +279,92 @@ short ANIM_animchanneldata_keyframes_loop(KeyframeEditData *ked, KeyframeEditFunc key_cb, FcuEditFunc fcu_cb); -/* Calls callback_fn() for each keyframe in each fcurve in the filtered animation context. - * Assumes the callback updates keys. */ +/** + * Calls callback_fn() for each keyframe in each fcurve in the filtered animation context. + * Assumes the callback updates keys. + */ void ANIM_animdata_keyframe_callback(struct bAnimContext *ac, eAnimFilter_Flags filter, KeyframeEditFunc callback_fn); -/* functions for making sure all keyframes are in good order */ +/** + * Functions for making sure all keyframes are in good order. + */ void ANIM_editkeyframes_refresh(struct bAnimContext *ac); -/* ----------- BezTriple Callback Getters ---------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name BezTriple Callback Getters + * \{ */ /* accessories */ KeyframeEditFunc ANIM_editkeyframes_ok(short mode); /* edit */ KeyframeEditFunc ANIM_editkeyframes_snap(short mode); +/** + * \note for markers and 'value', the values to use must be supplied as the first float value. + */ KeyframeEditFunc ANIM_editkeyframes_mirror(short mode); KeyframeEditFunc ANIM_editkeyframes_select(short mode); +/** + * Set all selected Bezier Handles to a single type. + */ KeyframeEditFunc ANIM_editkeyframes_handles(short mode); +/** + * Set the interpolation type of the selected BezTriples in each F-Curve to the specified one. + */ KeyframeEditFunc ANIM_editkeyframes_ipo(short mode); KeyframeEditFunc ANIM_editkeyframes_keytype(short mode); KeyframeEditFunc ANIM_editkeyframes_easing(short mode); -/* -------- BezTriple Callbacks (Selection Map) ---------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name BezTriple Callbacks (Selection Map) + * \{ */ -/* Get a callback to populate the selection settings map - * requires: ked->custom = char[] of length fcurve->totvert +/** + * Get a callback to populate the selection settings map + * requires: ked->custom = char[] of length fcurve->totvert. */ KeyframeEditFunc ANIM_editkeyframes_buildselmap(short mode); -/* Change the selection status of the keyframe based on the map entry for this vert - * requires: ked->custom = char[] of length fcurve->totvert +/** + * Change the selection status of the keyframe based on the map entry for this vert + * requires: ked->custom = char[] of length fcurve->totvert. */ short bezt_selmap_flush(KeyframeEditData *ked, struct BezTriple *bezt); -/* ----------- BezTriple Callback (Assorted Utilities) ---------- */ +/** \} */ -/* used to calculate the average location of all relevant BezTriples by summing their locations */ +/* -------------------------------------------------------------------- */ +/** \name BezTriple Callback (Assorted Utilities) + * \{ */ + +/** + * Used to calculate the average location of all relevant BezTriples by summing their locations. + */ short bezt_calc_average(KeyframeEditData *ked, struct BezTriple *bezt); -/* used to extract a set of cfra-elems from the keyframes */ +/** + * Used to extract a set of cfra-elems from the keyframes. + */ short bezt_to_cfraelem(KeyframeEditData *ked, struct BezTriple *bezt); -/* used to remap times from one range to another - * requires: ked->custom = KeyframeEditCD_Remap +/** + * Used to remap times from one range to another. + * requires: `ked->custom = KeyframeEditCD_Remap`. */ void bezt_remap_times(KeyframeEditData *ked, struct BezTriple *bezt); -/* ------ 1.5-D Region Testing Utilities (Lasso/Circle Select) ------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name 1.5-D Region Testing Utilities (Lasso/Circle Select) + * \{ */ + /* XXX: These are temporary, * until we can unify GP/Mask Keyframe handling and standard FCurve Keyframe handling */ @@ -321,6 +385,9 @@ void clean_fcurve(struct bAnimContext *ac, float thresh, bool cleardefault); bool decimate_fcurve(struct bAnimListElem *ale, float remove_ratio, float error_sq_max); +/** + * Use a weighted moving-means method to reduce intensity of fluctuations. + */ void smooth_fcurve(struct FCurve *fcu); void sample_fcurve(struct FCurve *fcu); @@ -336,6 +403,8 @@ short paste_animedit_keys(struct bAnimContext *ac, /* ************************************************ */ +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/editors/include/ED_keyframing.h b/source/blender/editors/include/ED_keyframing.h index 673f629d6ef..d539c7b688c 100644 --- a/source/blender/editors/include/ED_keyframing.h +++ b/source/blender/editors/include/ED_keyframing.h @@ -53,22 +53,28 @@ struct PropertyRNA; struct NlaKeyframingContext; -/* ************ Keyframing Management **************** */ +/* -------------------------------------------------------------------- */ +/** \name Key-Framing Management + * \{ */ -/* Get the active settings for keyframing settings from context (specifically the given scene) - * - use_autokey_mode: include settings from keyframing mode in the result (i.e. replace only). +/** + * Get the active settings for key-framing settings from context (specifically the given scene) + * \param use_autokey_mode: include settings from key-framing mode in the result + * (i.e. replace only). */ eInsertKeyFlags ANIM_get_keyframing_flags(struct Scene *scene, const bool use_autokey_mode); /* -------- */ -/* Get (or add relevant data to be able to do so) the Active Action for the given +/** + * Get (or add relevant data to be able to do so) the Active Action for the given * Animation Data block, given an ID block where the Animation Data should reside. */ struct bAction *ED_id_action_ensure(struct Main *bmain, struct ID *id); -/* Get (or add relevant data to be able to do so) F-Curve from the given Action. - * This assumes that all the destinations are valid. +/** + * Get (or add relevant data to be able to do so) F-Curve from the Active Action, + * for the given Animation Data block. This assumes that all the destinations are valid. */ struct FCurve *ED_action_fcurve_ensure(struct Main *bmain, struct bAction *act, @@ -77,15 +83,21 @@ struct FCurve *ED_action_fcurve_ensure(struct Main *bmain, const char rna_path[], const int array_index); +/** + * Find the F-Curve from the Active Action, + * for the given Animation Data block. This assumes that all the destinations are valid. + */ struct FCurve *ED_action_fcurve_find(struct bAction *act, const char rna_path[], const int array_index); /* -------- */ -/* Lesser Keyframing API call: - * Update integer/discrete flags of the FCurve (used when creating/inserting keyframes, - * but also through RNA when editing an ID prop, see T37103). +/** + * \brief Lesser Key-framing API call. + * + * Update integer/discrete flags of the FCurve (used when creating/inserting keyframes, + * but also through RNA when editing an ID prop, see T37103). */ void update_autoflags_fcurve(struct FCurve *fcu, struct bContext *C, @@ -94,16 +106,34 @@ void update_autoflags_fcurve(struct FCurve *fcu, /* -------- */ -/* Lesser Keyframing API call: - * Use this when validation of necessary animation data isn't necessary as it already - * exists, and there is a beztriple that can be directly copied into the array. +/** + * \brief Lesser Key-framing API call. + * + * Use this when validation of necessary animation data isn't necessary as it already + * exists, and there is a #BezTriple that can be directly copied into the array. + * + * This function adds a given #BezTriple to an F-Curve. It will allocate + * memory for the array if needed, and will insert the #BezTriple into a + * suitable place in chronological order. + * + * \note any recalculate of the F-Curve that needs to be done will need to be done by the caller. */ int insert_bezt_fcurve(struct FCurve *fcu, const struct BezTriple *bezt, eInsertKeyFlags flag); -/* Main Keyframing API call: - * Use this when validation of necessary animation data isn't necessary as it - * already exists. It will insert a keyframe using the current value being keyframed. - * Returns the index at which a keyframe was added (or -1 if failed) +/** + * \brief Main Key-framing API call. + * + * Use this when validation of necessary animation data isn't necessary as it + * already exists. It will insert a keyframe using the current value being keyframed. + * Returns the index at which a keyframe was added (or -1 if failed). + * + * This function is a wrapper for #insert_bezt_fcurve(), and should be used when + * adding a new keyframe to a curve, when the keyframe doesn't exist anywhere else yet. + * It returns the index at which the keyframe was added. + * + * \param keyframe_type: The type of keyframe (#eBezTriple_KeyframeType). + * \param flag: Optional flags (#eInsertKeyFlags) for controlling how keys get added + * and/or whether updates get done. */ int insert_vert_fcurve(struct FCurve *fcu, float x, @@ -113,9 +143,21 @@ int insert_vert_fcurve(struct FCurve *fcu, /* -------- */ -/* Secondary Keyframing API calls: - * Use this to insert a keyframe using the current value being keyframed, in the - * nominated F-Curve (no creation of animation data performed). Returns success. +/** + * \brief Secondary Insert Key-framing API call. + * + * Use this when validation of necessary animation data is not necessary, + * since an RNA-pointer to the necessary data being keyframed, + * and a pointer to the F-Curve to use have both been provided. + * + * This function can't keyframe quaternion channels on some NLA strip types. + * + * \param keytype: The "keyframe type" (eBezTriple_KeyframeType), as shown in the Dope Sheet. + * + * \param flag: Used for special settings that alter the behavior of the keyframe insertion. + * These include the 'visual' key-framing modes, quick refresh, + * and extra keyframe filtering. + * \return Success. */ bool insert_keyframe_direct(struct ReportList *reports, struct PointerRNA ptr, @@ -128,9 +170,17 @@ bool insert_keyframe_direct(struct ReportList *reports, /* -------- */ -/* Main Keyframing API calls: +/** + * \brief Main Insert Key-framing API call. + * * Use this to create any necessary animation data, and then insert a keyframe - * using the current value being keyframed, in the relevant place. Returns success. + * using the current value being keyframed, in the relevant place. + * + * \param flag: Used for special settings that alter the behavior of the keyframe insertion. + * These include the 'visual' key-framing modes, quick refresh, and extra keyframe filtering. + * + * \param array_index: The index to key or -1 keys all array indices. + * \return The number of key-frames inserted. */ int insert_keyframe(struct Main *bmain, struct ReportList *reports, @@ -144,9 +194,13 @@ int insert_keyframe(struct Main *bmain, struct ListBase *nla_cache, eInsertKeyFlags flag); -/* Main Keyframing API call: +/** + * \brief Main Delete Key-Framing API call. + * * Use this to delete keyframe on current frame for relevant channel. - * Will perform checks just in case. */ + * Will perform checks just in case. + * \return The number of key-frames deleted. + */ int delete_keyframe(struct Main *bmain, struct ReportList *reports, struct ID *id, @@ -155,7 +209,11 @@ int delete_keyframe(struct Main *bmain, int array_index, float cfra); -/* ************ Keying Sets ********************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Keying Sets + * \{ */ /* forward decl. for this struct which is declared a bit later... */ struct ExtensionRNA; @@ -206,7 +264,9 @@ typedef struct KeyingSetInfo { /* -------- */ -/* Add another data source for Relative Keying Sets to be evaluated with */ +/** + * Add another data source for Relative Keying Sets to be evaluated with. + */ void ANIM_relative_keyingset_add_source(ListBase *dsources, struct ID *id, struct StructRNA *srna, @@ -226,13 +286,28 @@ typedef enum eModifyKey_Returns { MODIFYKEY_MISSING_TYPEINFO = -2, } eModifyKey_Returns; -/* poll the current KeyingSet, updating its set of paths - * (if "builtin"/"relative") for context changes */ +/** + * Given a #KeyingSet and context info, validate Keying Set's paths. + * This is only really necessary with relative/built-in KeyingSets + * where their list of paths is dynamically generated based on the + * current context info. + * + * \return 0 if succeeded, otherwise an error code: #eModifyKey_Returns. + */ eModifyKey_Returns ANIM_validate_keyingset(struct bContext *C, ListBase *dsources, struct KeyingSet *ks); -/* use the specified KeyingSet to add/remove various Keyframes on the specified frame */ +/** + * Use the specified #KeyingSet and context info (if required) + * to add/remove various Keyframes on the specified frame. + * + * Modify keyframes for the channels specified by the KeyingSet. + * This takes into account many of the different combinations of using KeyingSets. + * + * \returns the number of channels that key-frames were added or + * an #eModifyKey_Returns value (always a negative number). + */ int ANIM_apply_keyingset(struct bContext *C, ListBase *dsources, struct bAction *act, @@ -242,49 +317,88 @@ int ANIM_apply_keyingset(struct bContext *C, /* -------- */ -/* Get the first builtin KeyingSet with the given name, which occurs after the given one - * (or start of list if none given) */ +/** + * Find builtin #KeyingSet by name. + * + * \return The first builtin #KeyingSet with the given name, which occurs after the given one + * (or start of list if none given). + */ struct KeyingSet *ANIM_builtin_keyingset_get_named(struct KeyingSet *prevKS, const char name[]); -/* Find KeyingSet type info given a name */ +/** + * Find KeyingSet type info given a name. + */ KeyingSetInfo *ANIM_keyingset_info_find_name(const char name[]); -/* Find a given ID in the KeyingSet */ +/** + * Check if the ID appears in the paths specified by the #KeyingSet. + */ bool ANIM_keyingset_find_id(struct KeyingSet *ks, ID *id); -/* for RNA type registrations... */ +/** + * Add the given KeyingSetInfo to the list of type infos, + * and create an appropriate builtin set too. + */ void ANIM_keyingset_info_register(KeyingSetInfo *ksi); +/** + * Remove the given #KeyingSetInfo from the list of type infos, + * and also remove the builtin set if appropriate. + */ void ANIM_keyingset_info_unregister(struct Main *bmain, KeyingSetInfo *ksi); /* cleanup on exit */ +/* --------------- */ + void ANIM_keyingset_infos_exit(void); /* -------- */ -/* Get the active KeyingSet for the given scene */ +/** + * Get the active Keying Set for the given scene. + */ struct KeyingSet *ANIM_scene_get_active_keyingset(const struct Scene *scene); -/* Get the index of the Keying Set provided, for the given Scene */ +/** + * Get the index of the Keying Set provided, for the given Scene. + */ int ANIM_scene_get_keyingset_index(struct Scene *scene, struct KeyingSet *ks); -/* Get Keying Set to use for Auto-Keyframing some transforms */ +/** + * Get Keying Set to use for Auto-Key-Framing some transforms. + */ struct KeyingSet *ANIM_get_keyingset_for_autokeying(const struct Scene *scene, const char *transformKSName); -/* Dynamically populate an enum of Keying Sets */ +/** + * Dynamically populate an enum of Keying Sets. + */ const struct EnumPropertyItem *ANIM_keying_sets_enum_itemf(struct bContext *C, struct PointerRNA *ptr, struct PropertyRNA *prop, bool *r_free); -/* Use to get the keying set from the int value used by enums. */ +/** + * Get the keying set from enum values generated in #ANIM_keying_sets_enum_itemf. + * + * Type is the Keying Set the user specified to use when calling the operator: + * \param type: + * - == 0: use scene's active Keying Set. + * - > 0: use a user-defined Keying Set from the active scene. + * - < 0: use a builtin Keying Set. + */ KeyingSet *ANIM_keyingset_get_from_enum_type(struct Scene *scene, int type); KeyingSet *ANIM_keyingset_get_from_idname(struct Scene *scene, const char *idname); -/* Check if KeyingSet can be used in the current context */ +/** + * Check if #KeyingSet can be used in the current context. + */ bool ANIM_keyingset_context_ok_poll(struct bContext *C, struct KeyingSet *ks); -/* ************ Drivers ********************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Drivers + * \{ */ /* Flags for use by driver creation calls */ typedef enum eCreateDriverFlags { @@ -311,7 +425,10 @@ typedef enum eCreateDriver_MappingTypes { CREATEDRIVER_MAPPING_NONE_ALL = 4, } eCreateDriver_MappingTypes; -/* RNA Enum of eCreateDriver_MappingTypes, for use by the appropriate operators */ +/** + * Mapping Types enum for operators. + * \note Used by #ANIM_OT_driver_button_add and #UI_OT_eyedropper_driver. + */ extern EnumPropertyItem prop_driver_create_mapping_types[]; /* -------- */ @@ -323,7 +440,11 @@ typedef enum eDriverFCurveCreationMode { DRIVER_FCURVE_EMPTY = 3 /* Add without data, for pasting. */ } eDriverFCurveCreationMode; -/* Low-level call to add a new driver F-Curve. This shouldn't be used directly for most tools, +/** + * Get (or add relevant data to be able to do so) F-Curve from the driver stack, + * for the given Animation Data block. This assumes that all the destinations are valid. + * + * \note This low-level function shouldn't be used directly for most tools, * although there are special cases where this approach is preferable. */ struct FCurve *verify_driver_fcurve(struct ID *id, @@ -337,16 +458,18 @@ struct FCurve *alloc_driver_fcurve(const char rna_path[], /* -------- */ -/* Main Driver Management API calls: - * Add a new driver for the specified property on the given ID block, - * and make it be driven by the specified target. +/** + * \brief Main Driver Management API calls + * + * Add a new driver for the specified property on the given ID block, + * and make it be driven by the specified target. * * This is intended to be used in conjunction with a modal "eyedropper" * for picking the variable that is going to be used to drive this one. * - * - flag: eCreateDriverFlags - * - driver_type: eDriver_Types - * - mapping_type: eCreateDriver_MappingTypes + * \param flag: eCreateDriverFlags + * \param driver_type: eDriver_Types + * \param mapping_type: eCreateDriver_MappingTypes */ int ANIM_add_driver_with_target(struct ReportList *reports, struct ID *dst_id, @@ -361,8 +484,10 @@ int ANIM_add_driver_with_target(struct ReportList *reports, /* -------- */ -/* Main Driver Management API calls: - * Add a new driver for the specified property on the given ID block +/** + * \brief Main Driver Management API calls. + * + * Add a new driver for the specified property on the given ID block */ int ANIM_add_driver(struct ReportList *reports, struct ID *id, @@ -371,90 +496,128 @@ int ANIM_add_driver(struct ReportList *reports, short flag, int type); -/* Main Driver Management API calls: - * Remove the driver for the specified property on the given ID block (if available) +/** + * \brief Main Driver Management API calls. + * + * Remove the driver for the specified property on the given ID block (if available). */ bool ANIM_remove_driver( struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag); /* -------- */ -/* Clear copy-paste buffer for drivers */ +/** + * Clear copy-paste buffer for drivers. + * \note This function frees any MEM_calloc'ed copy/paste buffer data. + */ void ANIM_drivers_copybuf_free(void); -/* Clear copy-paste buffer for driver variable sets */ +/** + * Clear copy-paste buffer for driver variable sets. + * \note This function frees any MEM_calloc'ed copy/paste buffer data. + */ void ANIM_driver_vars_copybuf_free(void); /* -------- */ -/* Returns whether there is a driver in the copy/paste buffer to paste */ +/** + * Returns whether there is a driver in the copy/paste buffer to paste. + */ bool ANIM_driver_can_paste(void); -/* Main Driver Management API calls: - * Make a copy of the driver for the specified property on the given ID block +/** + * \brief Main Driver Management API calls. + * + * Make a copy of the driver for the specified property on the given ID block. */ bool ANIM_copy_driver( struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag); -/* Main Driver Management API calls: +/** + * \brief Main Driver Management API calls. + * * Add a new driver for the specified property on the given ID block or replace an existing one - * with the driver + driver-curve data from the buffer + * with the driver + driver-curve data from the buffer. */ bool ANIM_paste_driver( struct ReportList *reports, struct ID *id, const char rna_path[], int array_index, short flag); /* -------- */ -/* Checks if there are driver variables in the copy/paste buffer */ +/** + * Checks if there are driver variables in the copy/paste buffer. + */ bool ANIM_driver_vars_can_paste(void); -/* Copy the given driver's variables to the buffer */ +/** + * Copy the given driver's variables to the buffer. + */ bool ANIM_driver_vars_copy(struct ReportList *reports, struct FCurve *fcu); -/* Paste the variables in the buffer to the given FCurve */ +/** + * Paste the variables in the buffer to the given FCurve. + */ bool ANIM_driver_vars_paste(struct ReportList *reports, struct FCurve *fcu, bool replace); /* -------- */ -/* Create a driver & variable that reads the specified property, - * and store it in the buffers for Paste Driver and Paste Variables. */ +/** + * Create a driver & variable that reads the specified property, + * and store it in the buffers for Paste Driver and Paste Variables. + */ void ANIM_copy_as_driver(struct ID *target_id, const char *target_path, const char *var_name); -/* ************ Auto-Keyframing ********************** */ -/* Notes: +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Auto-Key-Framing + * + * Notes: * - All the defines for this (User-Pref settings and Per-Scene settings) * are defined in DNA_userdef_types.h - * - Scene settings take precedence over those for userprefs, with old files - * inheriting userpref settings for the scene settings - * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored - * as userprefs - */ + * - Scene settings take precedence over those for user-preferences, with old files + * inheriting user-preferences settings for the scene settings + * - "On/Off + Mode" are stored per Scene, but "settings" are currently stored as user-preferences. + * \{ */ -/* Auto-Keying macros for use by various tools */ -/* check if auto-keyframing is enabled (per scene takes precedence) */ +/* Auto-Keying macros for use by various tools. */ + +/** Check if auto-key-framing is enabled (per scene takes precedence). + */ #define IS_AUTOKEY_ON(scene) \ ((scene) ? ((scene)->toolsettings->autokey_mode & AUTOKEY_ON) : (U.autokey_mode & AUTOKEY_ON)) -/* Check the mode for auto-keyframing (per scene takes precedence). */ +/** Check the mode for auto-keyframing (per scene takes precedence). */ #define IS_AUTOKEY_MODE(scene, mode) \ ((scene) ? ((scene)->toolsettings->autokey_mode == AUTOKEY_MODE_##mode) : \ (U.autokey_mode == AUTOKEY_MODE_##mode)) -/* check if a flag is set for auto-keyframing (per scene takes precedence) */ +/** Check if a flag is set for auto-key-framing (per scene takes precedence). */ #define IS_AUTOKEY_FLAG(scene, flag) \ ((scene) ? (((scene)->toolsettings->autokey_flag & AUTOKEY_FLAG_##flag) || \ (U.autokey_flag & AUTOKEY_FLAG_##flag)) : \ (U.autokey_flag & AUTOKEY_FLAG_##flag)) -/* auto-keyframing feature - checks for whether anything should be done for the current frame */ +/** + * Auto-keyframing feature - checks for whether anything should be done for the current frame. + */ bool autokeyframe_cfra_can_key(const struct Scene *scene, struct ID *id); -/* ************ Keyframe Checking ******************** */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Keyframe Checking + * \{ */ -/* Lesser Keyframe Checking API call: - * - Used for the buttons to check for keyframes... +/** + * \brief Lesser Keyframe Checking API call. + * + * Checks if some F-Curve has a keyframe for a given frame. + * \note Used for the buttons to check for keyframes. */ bool fcurve_frame_has_keyframe(const struct FCurve *fcu, float frame, short filter); -/* Lesser Keyframe Checking API call: +/** + * \brief Lesser Keyframe Checking API call. + * * - Returns whether the current value of a given property differs from the interpolated value. * - Used for button drawing. */ @@ -464,18 +627,19 @@ bool fcurve_is_changed(struct PointerRNA ptr, const struct AnimationEvalContext *anim_eval_context); /** - * Main Keyframe Checking API call: + * \brief Main Keyframe Checking API call. + * * Checks whether a keyframe exists for the given ID-block one the given frame. - * - It is recommended to call this method over the other keyframe-checkers directly, - * in case some detail of the implementation changes... - * - frame: the value of this is quite often result of #BKE_scene_ctime_get() + * It is recommended to call this method over the other keyframe-checkers directly, + * in case some detail of the implementation changes... + * \param frame: The value of this is quite often result of #BKE_scene_ctime_get() */ bool id_frame_has_keyframe(struct ID *id, float frame, short filter); -/* filter flags for id_cfra_has_keyframe +/** + * Filter flags for #id_frame_has_keyframe. * - * WARNING: do not alter order of these, as also stored in files - * (for v3d->keyflags) + * \warning do not alter order of these, as also stored in files (for `v3d->keyflags`). */ typedef enum eAnimFilterFlags { /* general */ @@ -488,7 +652,8 @@ typedef enum eAnimFilterFlags { ANIMFILTER_KEYS_NOSKEY = (1 << 10), /* don't include shape keys (for geometry) */ } eAnimFilterFlags; -/* utility funcs for auto keyframe */ +/* Utility functions for auto key-frame. */ + bool ED_autokeyframe_object(struct bContext *C, struct Scene *scene, struct Object *ob, @@ -498,6 +663,9 @@ bool ED_autokeyframe_pchan(struct bContext *C, struct Object *ob, struct bPoseChannel *pchan, struct KeyingSet *ks); +/** + * Use for auto-key-framing from the UI. + */ bool ED_autokeyframe_property(struct bContext *C, struct Scene *scene, PointerRNA *ptr, @@ -506,7 +674,8 @@ bool ED_autokeyframe_property(struct bContext *C, float cfra); /* Names for builtin keying sets so we don't confuse these with labels/text, - * defined in python script: keyingsets_builtins.py */ + * defined in python script: `keyingsets_builtins.py`. */ + #define ANIM_KS_LOCATION_ID "Location" #define ANIM_KS_ROTATION_ID "Rotation" #define ANIM_KS_SCALING_ID "Scaling" @@ -516,6 +685,8 @@ bool ED_autokeyframe_property(struct bContext *C, #define ANIM_KS_WHOLE_CHARACTER_ID "WholeCharacter" #define ANIM_KS_WHOLE_CHARACTER_SELECTED_ID "WholeCharacterSelected" +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/editors/include/ED_lattice.h b/source/blender/editors/include/ED_lattice.h index 6982ad20f07..dc800d78007 100644 --- a/source/blender/editors/include/ED_lattice.h +++ b/source/blender/editors/include/ED_lattice.h @@ -33,10 +33,12 @@ struct UndoType; struct wmKeyConfig; /* lattice_ops.c */ + void ED_operatortypes_lattice(void); void ED_keymap_lattice(struct wmKeyConfig *keyconf); /* editlattice_select.c */ + bool ED_lattice_flags_set(struct Object *obedit, int flag); bool ED_lattice_select_pick( struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle); @@ -45,6 +47,8 @@ bool ED_lattice_deselect_all_multi_ex(struct Base **bases, const uint bases_len) bool ED_lattice_deselect_all_multi(struct bContext *C); /* editlattice_undo.c */ + +/** Export for ED_undo_sys. */ void ED_lattice_undosys_type(struct UndoType *ut); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_markers.h b/source/blender/editors/include/ED_markers.h index 8c10a8e36fd..8e6961ffd6f 100644 --- a/source/blender/editors/include/ED_markers.h +++ b/source/blender/editors/include/ED_markers.h @@ -33,7 +33,9 @@ struct bAnimContext; struct bContext; struct wmKeyConfig; -/* Drawing API ------------------------------ */ +/* -------------------------------------------------------------------- */ +/** \name Drawing API + * \{ */ /* flags for drawing markers */ enum { @@ -42,37 +44,86 @@ enum { DRAW_MARKERS_MARGIN = (1 << 2), }; +/* Draw Scene-Markers in time window */ void ED_markers_draw(const struct bContext *C, int flag); -/* Backend API ----------------------------- */ +/** \} */ +/* -------------------------------------------------------------------- */ +/** \name Backend API + * \{ */ + +/** + * Public API for getting markers from context. + */ ListBase *ED_context_get_markers(const struct bContext *C); +/** + * Public API for getting markers from "animation" context. + */ ListBase *ED_animcontext_get_markers(const struct bAnimContext *ac); +/** + * Apply some transformation to markers after the fact + * + * \param markers: List of markers to affect - this may or may not be the scene markers list, + * so don't assume anything. + * \param scene: Current scene (for getting current frame) + * \param mode: (TfmMode) transform mode that this transform is for + * \param value: From the transform code, this is `t->vec[0]` + * (which is delta transform for grab/extend, and scale factor for scale) + * \param side: (B/L/R) for 'extend' functionality, which side of current frame to use + */ int ED_markers_post_apply_transform( ListBase *markers, struct Scene *scene, int mode, float value, char side); +/** + * Get the marker that is closest to this point. + * XXX: for select, the min_dist should be small. + */ struct TimeMarker *ED_markers_find_nearest_marker(ListBase *markers, float x); +/** + * Return the time of the marker that occurs on a frame closest to the given time. + */ int ED_markers_find_nearest_marker_time(ListBase *markers, float x); void ED_markers_get_minmax(ListBase *markers, short sel, float *first, float *last); +/** + * This function makes a list of all the markers. The only_sel + * argument is used to specify whether only the selected markers + * are added. + */ void ED_markers_make_cfra_list(ListBase *markers, ListBase *lb, short sel); void ED_markers_deselect_all(ListBase *markers, int action); +/** + * Get the first selected marker. + */ struct TimeMarker *ED_markers_get_first_selected(ListBase *markers); -/* Operators ------------------------------ */ +/** \} */ -/* called in screen_ops.c:ED_operatortypes_screen() */ +/* -------------------------------------------------------------------- */ +/** \name Operators + * \{ */ + +/** + * Called in screen_ops.c:ED_operatortypes_screen(). + */ void ED_operatortypes_marker(void); -/* called in screen_ops.c:ED_keymap_screen() */ +/** + * Called in screen_ops.c:ED_keymap_screen(). + */ void ED_keymap_marker(struct wmKeyConfig *keyconf); -/* debugging only */ +/** + * Debugging only: print debugging prints of list of markers. + */ void debug_markers_print_list(struct ListBase *markers); +/** \} */ + #ifdef __cplusplus } #endif diff --git a/source/blender/editors/include/ED_mask.h b/source/blender/editors/include/ED_mask.h index c2fdbc160de..3aab6882dc2 100644 --- a/source/blender/editors/include/ED_mask.h +++ b/source/blender/editors/include/ED_mask.h @@ -37,6 +37,7 @@ struct bContext; struct wmKeyConfig; /* mask_edit.c */ + void ED_mask_deselect_all(const struct bContext *C); void ED_operatortypes_mask(void); @@ -44,6 +45,7 @@ void ED_keymap_mask(struct wmKeyConfig *keyconf); void ED_operatormacros_mask(void); /* mask_query.c */ + void ED_mask_get_size(struct ScrArea *area, int *width, int *height); void ED_mask_zoom(struct ScrArea *area, struct ARegion *region, float *zoomx, float *zoomy); void ED_mask_get_aspect(struct ScrArea *area, struct ARegion *region, float *aspx, float *aspy); @@ -52,11 +54,18 @@ void ED_mask_pixelspace_factor(struct ScrArea *area, struct ARegion *region, float *scalex, float *scaley); +/** + * Takes `event->mval`. + */ void ED_mask_mouse_pos(struct ScrArea *area, struct ARegion *region, const int mval[2], float co[2]); +/** + * \param x/y: input, mval space. + * \param xr/yr: output, mask point space. + */ void ED_mask_point_pos( struct ScrArea *area, struct ARegion *region, float x, float y, float *xr, float *yr); void ED_mask_point_pos__reverse( @@ -69,7 +78,12 @@ bool ED_mask_selected_minmax(const struct bContext *C, bool handles_as_control_point); /* mask_draw.c */ + void ED_mask_draw(const struct bContext *C, const char draw_flag, const char draw_type); +/** + * Sets up the opengl context. + * width, height are to match the values from #ED_mask_get_size(). + */ void ED_mask_draw_region(struct Depsgraph *depsgraph, struct Mask *mask, struct ARegion *region, @@ -89,33 +103,68 @@ void ED_mask_draw_frames( struct Mask *mask, struct ARegion *region, const int cfra, const int sfra, const int efra); /* mask_shapekey.c */ + void ED_mask_layer_shape_auto_key(struct MaskLayer *mask_layer, const int frame); bool ED_mask_layer_shape_auto_key_all(struct Mask *mask, const int frame); bool ED_mask_layer_shape_auto_key_select(struct Mask *mask, const int frame); /* ----------- Mask AnimEdit API ------------------ */ + +/** + * Loops over the mask-frames for a mask-layer, and applies the given callback. + */ bool ED_masklayer_frames_looper(struct MaskLayer *mask_layer, struct Scene *scene, bool (*mask_layer_shape_cb)(struct MaskLayerShape *, struct Scene *)); +/** + * Make a listing all the mask-frames in a layer as cfraelems. + */ void ED_masklayer_make_cfra_list(struct MaskLayer *mask_layer, ListBase *elems, bool onlysel); +/** + * Check if one of the frames in this layer is selected. + */ bool ED_masklayer_frame_select_check(const struct MaskLayer *mask_layer); +/** + * Set all/none/invert select. + */ void ED_masklayer_frame_select_set(struct MaskLayer *mask_layer, short mode); +/** + * Select the frames in this layer that occur within the bounds specified. + */ void ED_masklayer_frames_select_box(struct MaskLayer *mask_layer, float min, float max, short select_mode); +/** + * Select the frames in this layer that occur within the lasso/circle region specified. + */ void ED_masklayer_frames_select_region(struct KeyframeEditData *ked, struct MaskLayer *mask_layer, short tool, short select_mode); +/** + * Set all/none/invert select (like above, but with SELECT_* modes). + */ void ED_mask_select_frames(struct MaskLayer *mask_layer, short select_mode); +/** + * Select the frame in this layer that occurs on this frame (there should only be one at most). + */ void ED_mask_select_frame(struct MaskLayer *mask_layer, int selx, short select_mode); +/** + * Delete selected frames. + */ bool ED_masklayer_frames_delete(struct MaskLayer *mask_layer); +/** + * Duplicate selected frames from given mask-layer. + */ void ED_masklayer_frames_duplicate(struct MaskLayer *mask_layer); +/** + * Snap selected frames to ... + */ void ED_masklayer_snap_frames(struct MaskLayer *mask_layer, struct Scene *scene, short mode); #if 0 diff --git a/source/blender/editors/include/ED_mball.h b/source/blender/editors/include/ED_mball.h index 7648af159c9..1afd7f06a5a 100644 --- a/source/blender/editors/include/ED_mball.h +++ b/source/blender/editors/include/ED_mball.h @@ -37,6 +37,9 @@ void ED_operatortypes_metaball(void); void ED_operatormacros_metaball(void); void ED_keymap_metaball(struct wmKeyConfig *keyconf); +/** + * Add meta-element primitive to meta-ball object (which is in edit mode). + */ struct MetaElem *ED_mball_add_primitive(struct bContext *C, struct Object *obedit, bool obedit_is_new, @@ -44,17 +47,32 @@ struct MetaElem *ED_mball_add_primitive(struct bContext *C, float dia, int type); +/** + * Select MetaElement with mouse click (user can select radius circle or stiffness circle). + */ bool ED_mball_select_pick( struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle); bool ED_mball_deselect_all_multi_ex(struct Base **bases, uint bases_len); bool ED_mball_deselect_all_multi(struct bContext *C); +/** + * This function is used to free all MetaElems from MetaBall. + */ void ED_mball_editmball_free(struct Object *obedit); +/** + * This function is called, when MetaBall Object is switched from object mode to edit mode. + */ void ED_mball_editmball_make(struct Object *obedit); +/** + * This function is called, when MetaBall Object switched from edit mode to object mode. + * List of MetaElements is copied from object->data->edit_elems to object->data->elems. + */ void ED_mball_editmball_load(struct Object *obedit); /* editmball_undo.c */ + +/** Export for ED_undo_sys. */ void ED_mball_undosys_type(struct UndoType *ut); #define MBALLSEL_STIFF (1u << 30) diff --git a/source/blender/editors/include/ED_mesh.h b/source/blender/editors/include/ED_mesh.h index 22de6ca15bf..35838f4ce48 100644 --- a/source/blender/editors/include/ED_mesh.h +++ b/source/blender/editors/include/ED_mesh.h @@ -58,6 +58,17 @@ struct wmKeyConfig; struct wmOperator; /* editmesh_utils.c */ + +/** + * \param em: Editmesh. + * \param use_self: Allow a vertex to point to its self (middle verts). + * \param use_select: Restrict to selected verts. + * \param respecthide: Skip hidden vertices. + * \param use_topology: Use topology mirror. + * \param maxdist: Distance for close point test. + * \param r_index: Optional array to write into, as an alternative to a customdata layer + * (length of total verts). + */ void EDBM_verts_mirror_cache_begin_ex(struct BMEditMesh *em, const int axis, const bool use_self, @@ -86,14 +97,24 @@ void EDBM_mesh_clear(struct BMEditMesh *em); void EDBM_selectmode_to_scene(struct bContext *C); void EDBM_mesh_make(struct Object *ob, const int select_mode, const bool add_key_index); +/** + * Should only be called on the active edit-mesh, otherwise call #BKE_editmesh_free_data. + */ void EDBM_mesh_free_data(struct BMEditMesh *em); +/** + * \warning This can invalidate the #Mesh runtime cache of other objects (for linked duplicates). + * Most callers should run #DEG_id_tag_update on `ob->data`, see: T46738, T46913. + * This ensures #BKE_object_free_derived_caches runs on all objects that use this mesh. + */ void EDBM_mesh_load_ex(struct Main *bmain, struct Object *ob, bool free_data); void EDBM_mesh_load(struct Main *bmain, struct Object *ob); -/* flushes based on the current select mode. if in vertex select mode, +/** + * flushes based on the current select mode. If in vertex select mode, * verts select/deselect edges and faces, if in edge select mode, * edges select/deselect faces and vertices, and in face select mode faces select/deselect - * edges and vertices. */ + * edges and vertices. + */ void EDBM_select_more(struct BMEditMesh *em, const bool use_face_step); void EDBM_select_less(struct BMEditMesh *em, const bool use_face_step); @@ -105,6 +126,9 @@ void EDBM_select_flush(struct BMEditMesh *em); bool EDBM_vert_color_check(struct BMEditMesh *em); +/** + * Swap is 0 or 1, if 1 it hides not selected. + */ bool EDBM_mesh_hide(struct BMEditMesh *em, bool swap); bool EDBM_mesh_reveal(struct BMEditMesh *em, bool select); @@ -114,9 +138,18 @@ struct EDBMUpdate_Params { uint is_destructive : 1; }; +/** + * So many tools call these that we better make it a generic function. + */ void EDBM_update(struct Mesh *me, const struct EDBMUpdate_Params *params); +/** + * Bad level call from Python API. + */ void EDBM_update_extern(struct Mesh *me, const bool do_tessellation, const bool is_destructive); +/** + * A specialized vert map used by stitch operator. + */ struct UvElementMap *BM_uv_element_map_create(struct BMesh *bm, const struct Scene *scene, const bool face_selected, @@ -128,13 +161,23 @@ struct UvElement *BM_uv_element_get(struct UvElementMap *map, struct BMFace *efa, struct BMLoop *l); +/** + * Can we edit UV's for this mesh? + */ bool EDBM_uv_check(struct BMEditMesh *em); +/** + * last_sel, use em->act_face otherwise get the last selected face in the editselections + * at the moment, last_sel is mainly useful for making sure the space image doesn't flicker. + */ struct BMFace *EDBM_uv_active_face_get(struct BMEditMesh *em, const bool sloppy, const bool selected); void BM_uv_vert_map_free(struct UvVertMap *vmap); struct UvMapVert *BM_uv_vert_map_at_index(struct UvVertMap *vmap, unsigned int v); +/** + * Return a new #UvVertMap from the edit-mesh. + */ struct UvVertMap *BM_uv_vert_map_create(struct BMesh *bm, const bool use_select, const bool use_winding); @@ -156,6 +199,7 @@ void EDBM_project_snap_verts(struct bContext *C, struct BMEditMesh *em); /* editmesh_automerge.c */ + void EDBM_automerge(struct Object *ob, bool update, const char hflag, const float dist); void EDBM_automerge_and_split(struct Object *ob, const bool split_edges, @@ -165,9 +209,12 @@ void EDBM_automerge_and_split(struct Object *ob, const float dist); /* editmesh_undo.c */ + +/** Export for ED_undo_sys. */ void ED_mesh_undosys_type(struct UndoType *ut); /* editmesh_select.c */ + void EDBM_select_mirrored(struct BMEditMesh *em, const struct Mesh *me, const int axis, @@ -175,6 +222,17 @@ void EDBM_select_mirrored(struct BMEditMesh *em, int *r_totmirr, int *r_totfail); +/** + * Nearest vertex under the cursor. + * + * \param dist_px_manhattan_p: (in/out), minimal distance to the nearest and at the end, + * actual distance. + * \param use_select_bias: + * - When true, selected vertices are given a 5 pixel bias + * to make them further than unselected vertices. + * - When false, unselected vertices are given the bias. + * \param use_cycle: Cycle over elements within #FIND_NEAR_CYCLE_THRESHOLD_MIN in order of index. + */ struct BMVert *EDBM_vert_find_nearest_ex(struct ViewContext *vc, float *dist_px_manhattan_p, const bool use_select_bias, @@ -195,6 +253,13 @@ struct BMEdge *EDBM_edge_find_nearest_ex(struct ViewContext *vc, uint *r_base_index); struct BMEdge *EDBM_edge_find_nearest(struct ViewContext *vc, float *dist_px_manhattan_p); +/** + * \param use_zbuf_single_px: Special case, when using the back-buffer selection, + * only use the pixel at `vc->mval` instead of using `dist_px_manhattan_p` to search over a larger + * region. This is needed because historically selection worked this way for a long time, however + * it's reasonable that some callers might want to expand the region too. So add an argument to do + * this, + */ struct BMFace *EDBM_face_find_nearest_ex(struct ViewContext *vc, float *dist_px_manhattan, float *r_dist_center, @@ -230,19 +295,48 @@ bool EDBM_unified_findnearest_from_raycast(struct ViewContext *vc, bool EDBM_select_pick( struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle); +/** + * When switching select mode, makes sure selection is consistent for editing + * also for paranoia checks to make sure edge or face mode works. + */ void EDBM_selectmode_set(struct BMEditMesh *em); +/** + * Expand & Contract the Selection + * (used when changing modes and Ctrl key held) + * + * Flush the selection up: + * - vert -> edge + * - vert -> face + * - edge -> face + * + * Flush the selection down: + * - face -> edge + * - face -> vert + * - edge -> vert + */ void EDBM_selectmode_convert(struct BMEditMesh *em, const short selectmode_old, const short selectmode_new); -/* user access this */ +/** + * User access this. + */ bool EDBM_selectmode_set_multi(struct bContext *C, const short selectmode); +/** + * User facing function, does notification. + */ bool EDBM_selectmode_toggle_multi(struct bContext *C, const short selectmode_new, const int action, const bool use_extend, const bool use_expand); +/** + * Use to disable a select-mode if its enabled, Using another mode as a fallback + * if the disabled mode is the only mode set. + * + * \return true if the mode is changed. + */ bool EDBM_selectmode_disable(struct Scene *scene, struct BMEditMesh *em, const short selectmode_disable, @@ -305,12 +399,22 @@ void EDBM_preselect_elem_update_preview(struct EditMesh_PreSelElem *psel, void EDBM_preselect_action_set(struct EditMesh_PreSelElem *psel, eEditMesh_PreSelPreviewAction action); eEditMesh_PreSelPreviewAction EDBM_preselect_action_get(struct EditMesh_PreSelElem *psel); + /* mesh_ops.c */ + void ED_operatortypes_mesh(void); void ED_operatormacros_mesh(void); +/** + * Note mesh keymap also for other space? + */ void ED_keymap_mesh(struct wmKeyConfig *keyconf); /* editface.c */ + +/** + * Copy the face flags, most importantly selection from the mesh to the final derived mesh, + * use in object mode when selecting faces (while painting). + */ void paintface_flush_flags(struct bContext *C, struct Object *ob, short flag); bool paintface_mouse_select(struct bContext *C, struct Object *ob, @@ -331,8 +435,17 @@ bool paintface_minmax(struct Object *ob, float r_min[3], float r_max[3]); void paintface_hide(struct bContext *C, struct Object *ob, const bool unselected); void paintface_reveal(struct bContext *C, struct Object *ob, const bool select); +/** + * \note if the caller passes false to flush_flags, + * then they will need to run #paintvert_flush_flags(ob) themselves. + */ bool paintvert_deselect_all_visible(struct Object *ob, int action, bool flush_flags); void paintvert_select_ungrouped(struct Object *ob, bool extend, bool flush_flags); +/** + * (similar to void `paintface_flush_flags(Object *ob)`) + * copy the vertex flags, most importantly selection from the mesh to the final derived mesh, + * use in object mode when selecting vertices (while painting). + */ void paintvert_flush_flags(struct Object *ob); void paintvert_tag_select_update(struct bContext *C, struct Object *ob); @@ -360,17 +473,35 @@ void ED_mesh_mirrtopo_free(MirrTopoStore_t *mesh_topo_store); bool ED_vgroup_sync_from_pose(struct Object *ob); void ED_vgroup_select_by_name(struct Object *ob, const char *name); +/** + * Removes out of range #MDeformWeights + */ void ED_vgroup_data_clamp_range(struct ID *id, const int total); +/** + * Matching index only. + */ bool ED_vgroup_array_copy(struct Object *ob, struct Object *ob_from); bool ED_vgroup_parray_alloc(struct ID *id, struct MDeformVert ***dvert_arr, int *dvert_tot, const bool use_vert_sel); +/** + * For use with tools that use ED_vgroup_parray_alloc with \a use_vert_sel == true. + * This finds the unselected mirror deform verts and copies the weights to them from the selected. + * + * \note \a dvert_array has mirrored weights filled in, + * in case cleanup operations are needed on both. + */ void ED_vgroup_parray_mirror_sync(struct Object *ob, struct MDeformVert **dvert_array, const int dvert_tot, const bool *vgroup_validmap, const int vgroup_tot); +/** + * Fill in the pointers for mirror verts (as if all mirror verts were selected too). + * + * similar to #ED_vgroup_parray_mirror_sync but only fill in mirror points. + */ void ED_vgroup_parray_mirror_assign(struct Object *ob, struct MDeformVert **dvert_array, const int dvert_tot); @@ -397,13 +528,23 @@ void ED_vgroup_mirror(struct Object *ob, int *r_totmirr, int *r_totfail); +/** + * Called while not in editmode. + */ void ED_vgroup_vert_add( struct Object *ob, struct bDeformGroup *dg, int vertnum, float weight, int assignmode); +/** + * Mesh object mode, lattice can be in edit-mode. + */ void ED_vgroup_vert_remove(struct Object *ob, struct bDeformGroup *dg, int vertnum); float ED_vgroup_vert_weight(struct Object *ob, struct bDeformGroup *dg, int vertnum); +/** + * Use when adjusting the active vertex weight and apply to mirror vertices. + */ void ED_vgroup_vert_active_mirror(struct Object *ob, int def_nr); /* mesh_data.c */ + void ED_mesh_verts_add(struct Mesh *mesh, struct ReportList *reports, int count); void ED_mesh_edges_add(struct Mesh *mesh, struct ReportList *reports, int count); void ED_mesh_loops_add(struct Mesh *mesh, struct ReportList *reports, int count); @@ -428,6 +569,9 @@ bool ED_mesh_uv_texture_remove_index(struct Mesh *me, const int n); bool ED_mesh_uv_texture_remove_active(struct Mesh *me); bool ED_mesh_uv_texture_remove_named(struct Mesh *me, const char *name); void ED_mesh_uv_loop_reset(struct bContext *C, struct Mesh *me); +/** + * Without a #bContext, called when UV-editing. + */ void ED_mesh_uv_loop_reset_ex(struct Mesh *me, const int layernum); bool ED_mesh_color_ensure(struct Mesh *me, const char *name); int ED_mesh_color_add(struct Mesh *me, @@ -452,7 +596,9 @@ bool ED_mesh_sculpt_color_remove_named(struct Mesh *me, const char *name); void ED_mesh_report_mirror(struct wmOperator *op, int totmirr, int totfail); void ED_mesh_report_mirror_ex(struct wmOperator *op, int totmirr, int totfail, char selectmode); -/* Returns the pinned mesh, the mesh from the pinned object, or the mesh from the active object. */ +/** + * Returns the pinned mesh, the mesh from the pinned object, or the mesh from the active object. + */ struct Mesh *ED_mesh_context(struct bContext *C); /* mesh backup */ @@ -460,20 +606,30 @@ typedef struct BMBackup { struct BMesh *bmcopy; } BMBackup; +/** + * Save a copy of the #BMesh for restoring later. + */ struct BMBackup EDBM_redo_state_store(struct BMEditMesh *em); -/* restore a bmesh from backup */ +/** + * Restore a BMesh from backup. + */ void EDBM_redo_state_restore(struct BMBackup *backup, struct BMEditMesh *em, bool recalc_looptri) ATTR_NONNULL(1, 2); +/** + * Delete the backup, flushing it to an edit-mesh. + */ void EDBM_redo_state_restore_and_free(struct BMBackup *backup, struct BMEditMesh *em, bool recalc_looptri) ATTR_NONNULL(1, 2); void EDBM_redo_state_free(struct BMBackup *backup) ATTR_NONNULL(1); /* *** meshtools.c *** */ + int ED_mesh_join_objects_exec(struct bContext *C, struct wmOperator *op); int ED_mesh_shapes_join_objects_exec(struct bContext *C, struct wmOperator *op); /* mirror lookup api */ + /* Spatial Mirror */ void ED_mesh_mirror_spatial_table_begin(struct Object *ob, struct BMEditMesh *em, @@ -485,11 +641,19 @@ int ED_mesh_mirror_spatial_table_lookup(struct Object *ob, const float co[3]); /* Topology Mirror */ + +/** + * Mode is 's' start, or 'e' end, or 'u' use if end, ob can be NULL. + * \note This is supposed return -1 on error, + * which callers are currently checking for, but is not used so far. + */ void ED_mesh_mirror_topo_table_begin(struct Object *ob, struct Mesh *me_eval); void ED_mesh_mirror_topo_table_end(struct Object *ob); -/* Retrieves mirrored cache vert, or NULL if there isn't one. - * NOTE: calling this without ensuring the mirror cache state is bad. */ +/** + * Retrieves mirrored cache vert, or NULL if there isn't one. + * \note calling this without ensuring the mirror cache state is bad. + */ int mesh_get_x_mirror_vert(struct Object *ob, struct Mesh *me_eval, int index, @@ -500,8 +664,16 @@ struct BMVert *editbmesh_get_x_mirror_vert(struct Object *ob, const float co[3], int index, const bool use_topology); +/** + * This is a Mesh-based copy of #mesh_get_x_mirror_faces(). + */ int *mesh_get_x_mirror_faces(struct Object *ob, struct BMEditMesh *em, struct Mesh *me_eval); +/** + * Wrapper for object-mode/edit-mode. + * + * call #BM_mesh_elem_table_ensure first for editmesh. + */ int ED_mesh_mirror_get_vert(struct Object *ob, int index); bool ED_mesh_pick_vert(struct bContext *C, @@ -510,8 +682,18 @@ bool ED_mesh_pick_vert(struct bContext *C, uint dist_px, bool use_zbuf, uint *r_index); +/** + * Face selection in object mode, + * currently only weight-paint and vertex-paint use this. + * + * \return boolean true == Found + */ bool ED_mesh_pick_face( struct bContext *C, struct Object *ob, const int mval[2], uint dist_px, uint *r_index); +/** + * Use when the back buffer stores face index values. but we want a vert. + * This gets the face then finds the closest vertex to mval. + */ bool ED_mesh_pick_face_vert( struct bContext *C, struct Object *ob, const int mval[2], uint dist_px, uint *r_index); diff --git a/source/blender/editors/include/ED_node.h b/source/blender/editors/include/ED_node.h index e68617f7867..5bac452c7c9 100644 --- a/source/blender/editors/include/ED_node.h +++ b/source/blender/editors/include/ED_node.h @@ -77,6 +77,7 @@ struct bNodeTree *ED_node_tree_get(struct SpaceNode *snode, int level); void ED_node_set_active_viewer_key(struct SpaceNode *snode); /* drawnode.c */ + void ED_node_init_butfuncs(void); void ED_init_custom_node_type(struct bNodeType *ntype); void ED_init_custom_node_socket_type(struct bNodeSocketType *stype); @@ -87,6 +88,12 @@ void ED_node_draw_snap( struct View2D *v2d, const float cent[2], float size, NodeBorder border, unsigned int pos); /* node_draw.cc */ + +/** + * Draw a single node socket at default size. + * \note this is only called from external code, internally #node_socket_draw_nested() is used for + * optimized drawing of multiple/all sockets of a node. + */ void ED_node_socket_draw(struct bNodeSocket *sock, const struct rcti *rect, const float color[4], @@ -94,22 +101,46 @@ void ED_node_socket_draw(struct bNodeSocket *sock, void ED_node_tree_update(const struct bContext *C); void ED_node_tag_update_id(struct ID *id); void ED_node_tag_update_nodetree(struct Main *bmain, struct bNodeTree *ntree, struct bNode *node); +/** + * Sort nodes by selection: unselected nodes first, then selected, + * then the active node at the very end. Relative order is kept intact. + */ void ED_node_sort(struct bNodeTree *ntree); float ED_node_grid_size(void); /* node_relationships.c */ + +/** + * Test == 0, clear all intersect flags. + */ void ED_node_link_intersect_test(struct ScrArea *area, int test); +/** + * Assumes link with #NODE_LINKFLAG_HILITE set. + */ void ED_node_link_insert(struct Main *bmain, struct ScrArea *area); /* node_edit.c */ + void ED_node_set_tree_type(struct SpaceNode *snode, struct bNodeTreeType *typeinfo); bool ED_node_is_compositor(struct SpaceNode *snode); bool ED_node_is_shader(struct SpaceNode *snode); bool ED_node_is_texture(struct SpaceNode *snode); bool ED_node_is_geometry(struct SpaceNode *snode); +/** + * Assumes nothing being done in ntree yet, sets the default in/out node. + * Called from shading buttons or header. + */ void ED_node_shader_default(const struct bContext *C, struct ID *id); +/** + * Assumes nothing being done in ntree yet, sets the default in/out node. + * Called from shading buttons or header. + */ void ED_node_composit_default(const struct bContext *C, struct Scene *scene); +/** + * Assumes nothing being done in ntree yet, sets the default in/out node. + * Called from shading buttons or header. + */ void ED_node_texture_default(const struct bContext *C, struct Tex *tex); bool ED_node_select_check(const ListBase *lb); void ED_node_select_all(ListBase *lb, int action); @@ -120,19 +151,34 @@ void ED_node_set_active(struct Main *bmain, struct bNode *node, bool *r_active_texture_changed); +/** + * \param scene_owner: is the owner of the job, + * we don't use it for anything else currently so could also be a void pointer, + * but for now keep it an 'Scene' for consistency. + * + * \note only call from spaces `refresh` callbacks, not direct! - use with care. + */ void ED_node_composite_job(const struct bContext *C, struct bNodeTree *nodetree, struct Scene *scene_owner); /* node_ops.c */ + void ED_operatormacros_node(void); /* node_view.c */ +/** + * Returns mouse position in image space. + */ bool ED_space_node_get_position(struct Main *bmain, struct SpaceNode *snode, struct ARegion *region, const int mval[2], float fpos[2]); +/** + * Returns color in linear space, matching #ED_space_image_color_sample(). + * And here we've got recursion in the comments tips... + */ bool ED_space_node_color_sample(struct Main *bmain, struct SpaceNode *snode, struct ARegion *region, diff --git a/source/blender/editors/include/ED_numinput.h b/source/blender/editors/include/ED_numinput.h index d5685788ce1..84fa4488374 100644 --- a/source/blender/editors/include/ED_numinput.h +++ b/source/blender/editors/include/ED_numinput.h @@ -94,8 +94,14 @@ struct UnitSettings; */ void initNumInput(NumInput *n); +/** + * \param str: Must be NUM_STR_REP_LEN * (idx_max + 1) length. + */ void outputNumInput(NumInput *n, char *str, struct UnitSettings *unit_settings); bool hasNumInput(const NumInput *n); +/** + * \warning \a vec must be set beforehand otherwise we risk uninitialized vars. + */ bool applyNumInput(NumInput *n, float *vec); bool handleNumInput(struct bContext *C, NumInput *n, const struct wmEvent *event); 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 */ diff --git a/source/blender/editors/include/ED_outliner.h b/source/blender/editors/include/ED_outliner.h index 1d1471f0be6..99f65010595 100644 --- a/source/blender/editors/include/ED_outliner.h +++ b/source/blender/editors/include/ED_outliner.h @@ -33,10 +33,21 @@ struct bContext; bool ED_outliner_collections_editor_poll(struct bContext *C); +/** + * Populates the \param objects: ListBase with all the outliner selected objects + * We store it as (Object *)LinkData->data + * \param objects: expected to be empty + */ void ED_outliner_selected_objects_get(const struct bContext *C, struct ListBase *objects); +/** + * Get base of object under cursor. Used for eyedropper tool. + */ struct Base *ED_outliner_give_base_under_cursor(struct bContext *C, const int mval[2]); +/** + * Functions for tagging outliner selection syncing is dirty from operators. + */ void ED_outliner_select_sync_from_object_tag(struct bContext *C); void ED_outliner_select_sync_from_edit_bone_tag(struct bContext *C); void ED_outliner_select_sync_from_pose_bone_tag(struct bContext *C); @@ -45,9 +56,15 @@ void ED_outliner_select_sync_from_all_tag(struct bContext *C); bool ED_outliner_select_sync_is_dirty(const struct bContext *C); +/** + * Set clean outliner and mark other outliners for syncing. + */ void ED_outliner_select_sync_from_outliner(struct bContext *C, struct SpaceOutliner *space_outliner); +/** + * Copy sync select dirty flag from window manager to all outliners to be synced lazily on draw. + */ void ED_outliner_select_sync_flag_outliners(const struct bContext *C); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_paint.h b/source/blender/editors/include/ED_paint.h index 6a28baa4ca1..1d1ba264de5 100644 --- a/source/blender/editors/include/ED_paint.h +++ b/source/blender/editors/include/ED_paint.h @@ -54,11 +54,21 @@ void ED_imapaint_bucket_fill(struct bContext *C, const int mouse[2]); /* paint_image_proj.c */ + void ED_paint_data_warning(struct ReportList *reports, bool uvs, bool mat, bool tex, bool stencil); +/** + * Make sure that active object has a material, + * and assign UVs and image layers if they do not exist. + */ bool ED_paint_proj_mesh_data_check( struct Scene *scene, struct Object *ob, bool *uvs, bool *mat, bool *tex, bool *stencil); /* image_undo.c */ + +/** + * The caller is responsible for running #ED_image_undo_push_end, + * failure to do so causes an invalid state for the undo system. + */ void ED_image_undo_push_begin(const char *name, int paint_mode); void ED_image_undo_push_begin_with_image(const char *name, struct Image *image, @@ -66,8 +76,12 @@ void ED_image_undo_push_begin_with_image(const char *name, struct ImageUser *iuser); void ED_image_undo_push_end(void); +/** + * Restore painting image to previous state. Used for anchored and drag-dot style brushes. + */ void ED_image_undo_restore(struct UndoStep *us); +/** Export for ED_undo_sys. */ void ED_image_undosys_type(struct UndoType *ut); void *ED_image_paint_tile_find(struct ListBase *paint_tiles, @@ -100,9 +114,11 @@ struct ListBase *ED_image_paint_tile_list_get(void); (((size) + ED_IMAGE_UNDO_TILE_SIZE - 1) >> ED_IMAGE_UNDO_TILE_BITS) /* paint_curve_undo.c */ + void ED_paintcurve_undo_push_begin(const char *name); void ED_paintcurve_undo_push_end(struct bContext *C); +/** Export for ED_undo_sys. */ void ED_paintcurve_undosys_type(struct UndoType *ut); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_particle.h b/source/blender/editors/include/ED_particle.h index 5318c653b6d..ce25943b40a 100644 --- a/source/blender/editors/include/ED_particle.h +++ b/source/blender/editors/include/ED_particle.h @@ -39,10 +39,12 @@ struct rcti; struct wmGenericUserData; /* particle edit mode */ + void PE_free_ptcache_edit(struct PTCacheEdit *edit); int PE_start_edit(struct PTCacheEdit *edit); /* access */ + struct PTCacheEdit *PE_get_current_from_psys(struct ParticleSystem *psys); struct PTCacheEdit *PE_get_current(struct Depsgraph *depsgraph, struct Scene *scene, @@ -59,6 +61,7 @@ int PE_minmax(struct Depsgraph *depsgraph, struct ParticleEditSettings *PE_settings(struct Scene *scene); /* update calls */ + void PE_hide_keys_time(struct Scene *scene, struct PTCacheEdit *edit, float cfra); void PE_update_object(struct Depsgraph *depsgraph, struct Scene *scene, @@ -66,6 +69,7 @@ void PE_update_object(struct Depsgraph *depsgraph, int useflag); /* selection tools */ + bool PE_mouse_particles( struct bContext *C, const int mval[2], bool extend, bool deselect, bool toggle); bool PE_box_select(struct bContext *C, const struct rcti *rect, const int sel_op); @@ -82,6 +86,8 @@ bool PE_deselect_all_visible_ex(struct PTCacheEdit *edit); bool PE_deselect_all_visible(struct bContext *C); /* particle_edit_undo.c */ + +/** Export for ED_undo_sys. */ void ED_particle_undosys_type(struct UndoType *ut); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_render.h b/source/blender/editors/include/ED_render.h index 5cdcbbab42a..f60d62ed384 100644 --- a/source/blender/editors/include/ED_render.h +++ b/source/blender/editors/include/ED_render.h @@ -41,6 +41,7 @@ struct bContext; struct bScreen; struct wmWindow; struct wmWindowManager; +enum eIconSizes; /* render_ops.c */ @@ -55,7 +56,14 @@ void ED_render_view_layer_changed(struct Main *bmain, struct bScreen *screen); /* Callbacks handling data update events coming from depsgraph. */ void ED_render_id_flush_update(const struct DEGEditorUpdateContext *update_ctx, struct ID *id); +/** + * Update all 3D viewport render and draw engines on changes to the scene. + * This is called by the dependency graph when it detects changes. + */ void ED_render_scene_update(const struct DEGEditorUpdateContext *update_ctx, const bool updated); +/** + * Update 3D viewport render or draw engine on changes to the scene or view settings. + */ void ED_render_view3d_update(struct Depsgraph *depsgraph, struct wmWindow *window, struct ScrArea *area, @@ -69,19 +77,22 @@ struct Scene *ED_render_job_get_current_scene(const struct bContext *C); * pr_method: * - PR_BUTS_RENDER: preview is rendered for buttons window * - PR_ICON_RENDER: preview is rendered for icons. hopefully fast enough for at least 32x32 - * - PR_NODE_RENDER: preview is rendered for node editor * - PR_ICON_DEFERRED: No render, we just ensure deferred icon data gets generated. */ typedef enum ePreviewRenderMethod { PR_BUTS_RENDER = 0, PR_ICON_RENDER = 1, - PR_NODE_RENDER = 2, - PR_ICON_DEFERRED = 3, + PR_ICON_DEFERRED = 2, } ePreviewRenderMethod; void ED_preview_ensure_dbase(void); void ED_preview_free_dbase(void); +/** + * Check if \a id is supported by the automatic preview render. + */ +bool ED_preview_id_is_supported(const struct ID *id); + void ED_preview_shader_job(const struct bContext *C, void *owner, struct ID *id, @@ -103,6 +114,11 @@ void ED_preview_icon_job(const struct bContext *C, int sizex, int sizey, const bool delay); + +void ED_preview_restart_queue_free(void); +void ED_preview_restart_queue_add(struct ID *id, enum eIconSizes size); +void ED_preview_restart_queue_work(const struct bContext *C); + void ED_preview_kill_jobs(struct wmWindowManager *wm, struct Main *bmain); void ED_preview_draw(const struct bContext *C, void *idp, void *parentp, void *slot, rcti *rect); diff --git a/source/blender/editors/include/ED_scene.h b/source/blender/editors/include/ED_scene.h index e3abd26a4cd..e4e7a4bdfce 100644 --- a/source/blender/editors/include/ED_scene.h +++ b/source/blender/editors/include/ED_scene.h @@ -32,7 +32,14 @@ struct Scene *ED_scene_add(struct Main *bmain, struct bContext *C, struct wmWindow *win, enum eSceneCopyMethod method) ATTR_NONNULL(); +/** + * \note Only call outside of area/region loops. + * \return true if successful. + */ bool ED_scene_delete(struct bContext *C, struct Main *bmain, struct Scene *scene) ATTR_NONNULL(); +/** + * Depsgraph updates after scene becomes active in a window. + */ void ED_scene_change_update(struct Main *bmain, struct Scene *scene, struct ViewLayer *layer) ATTR_NONNULL(); bool ED_scene_view_layer_delete(struct Main *bmain, diff --git a/source/blender/editors/include/ED_screen.h b/source/blender/editors/include/ED_screen.h index eee119c0712..c65ef3e397d 100644 --- a/source/blender/editors/include/ED_screen.h +++ b/source/blender/editors/include/ED_screen.h @@ -65,33 +65,65 @@ struct wmWindow; struct wmWindowManager; /* regions */ +/** Only exported for WM. */ void ED_region_do_listen(struct wmRegionListenerParams *params); +/** Only exported for WM. */ void ED_region_do_layout(struct bContext *C, struct ARegion *region); +/** Only exported for WM. */ void ED_region_do_draw(struct bContext *C, struct ARegion *region); void ED_region_exit(struct bContext *C, struct ARegion *region); +/** + * Utility to exit and free an area-region. Screen level regions (menus/popups) need to be treated + * slightly differently, see #ui_region_temp_remove(). + */ void ED_region_remove(struct bContext *C, struct ScrArea *area, struct ARegion *region); void ED_region_pixelspace(const struct ARegion *region); +/** + * Call to move a popup window (keep OpenGL context free!) + */ void ED_region_update_rect(struct ARegion *region); +/** + * Externally called for floating regions like menus. + */ void ED_region_floating_init(struct ARegion *region); void ED_region_tag_redraw(struct ARegion *region); void ED_region_tag_redraw_partial(struct ARegion *region, const struct rcti *rct, bool rebuild); void ED_region_tag_redraw_cursor(struct ARegion *region); void ED_region_tag_redraw_no_rebuild(struct ARegion *region); void ED_region_tag_refresh_ui(struct ARegion *region); +/** + * Tag editor overlays to be redrawn. If in doubt about which parts need to be redrawn (partial + * clipping rectangle set), redraw everything. + */ void ED_region_tag_redraw_editor_overlays(struct ARegion *region); +/** + * Set the temporary update flag for property search. + */ void ED_region_search_filter_update(const struct ScrArea *area, struct ARegion *region); +/** + * Returns the search string if the space type and region type support property search. + */ const char *ED_area_region_search_filter_get(const struct ScrArea *area, const struct ARegion *region); void ED_region_panels_init(struct wmWindowManager *wm, struct ARegion *region); void ED_region_panels_ex(const struct bContext *C, struct ARegion *region, const char *contexts[]); void ED_region_panels(const struct bContext *C, struct ARegion *region); +/** + * \param contexts: A NULL terminated array of context strings to match against. + * Matching against any of these strings will draw the panel. + * Can be NULL to skip context checks. + */ void ED_region_panels_layout_ex(const struct bContext *C, struct ARegion *region, struct ListBase *paneltypes, const char *contexts[], const char *category_override); +/** + * Build the same panel list as #ED_region_panels_layout_ex and checks whether any + * of the panels contain a search result based on the area / region's search filter. + */ bool ED_region_property_search(const struct bContext *C, struct ARegion *region, struct ListBase *paneltypes, @@ -107,11 +139,20 @@ void ED_region_header_layout(const struct bContext *C, struct ARegion *region); void ED_region_header_draw(const struct bContext *C, struct ARegion *region); void ED_region_cursor_set(struct wmWindow *win, struct ScrArea *area, struct ARegion *region); +/** + * Exported to all editors, uses fading default. + */ void ED_region_toggle_hidden(struct bContext *C, struct ARegion *region); +/** + * For use after changing visibility of regions. + */ void ED_region_visibility_change_update(struct bContext *C, struct ScrArea *area, struct ARegion *region); /* screen_ops.c */ +/** + * \note Assumes that \a region itself is not a split version from previous region. + */ void ED_region_visibility_change_update_animated(struct bContext *C, struct ScrArea *area, struct ARegion *region); @@ -129,6 +170,9 @@ void ED_region_grid_draw(struct ARegion *region, float zoomx, float zoomy, float float ED_region_blend_alpha(struct ARegion *region); void ED_region_visible_rect_calc(struct ARegion *region, struct rcti *rect); const rcti *ED_region_visible_rect(ARegion *region); +/** + * Overlapping regions only in the following restricted cases. + */ bool ED_region_is_overlap(int spacetype, int regiontype); int ED_region_snap_size_test(const struct ARegion *region); @@ -142,39 +186,76 @@ void ED_area_do_msg_notify_tag_refresh(struct bContext *C, struct wmMsgSubscribeKey *msg_key, struct wmMsgSubscribeValue *msg_val); +/** + * Follow #ARegionType.message_subscribe. + */ void ED_area_do_mgs_subscribe_for_tool_header(const struct wmRegionMessageSubscribeParams *params); void ED_area_do_mgs_subscribe_for_tool_ui(const struct wmRegionMessageSubscribeParams *params); /* message bus */ + +/** + * Generate subscriptions for this region. + */ void ED_region_message_subscribe(struct wmRegionMessageSubscribeParams *params); /* spaces */ + +/** + * \note Keymap definitions are registered only once per WM initialize, + * usually on file read, using the keymap the actual areas/regions add the handlers. + * \note Called in wm.c. */ void ED_spacetypes_keymap(struct wmKeyConfig *keyconf); +/** + * Returns offset for next button in header. + */ int ED_area_header_switchbutton(const struct bContext *C, struct uiBlock *block, int yco); /* areas */ +/** + * Called in screen_refresh, or screens_init, also area size changes. + */ void ED_area_init(struct wmWindowManager *wm, struct wmWindow *win, struct ScrArea *area); void ED_area_exit(struct bContext *C, struct ScrArea *area); int ED_screen_area_active(const struct bContext *C); void ED_screen_global_areas_refresh(struct wmWindow *win); void ED_screen_global_areas_sync(struct wmWindow *win); +/** Only exported for WM. */ void ED_area_do_listen(struct wmSpaceTypeListenerParams *params); void ED_area_tag_redraw(ScrArea *area); void ED_area_tag_redraw_no_rebuild(ScrArea *area); void ED_area_tag_redraw_regiontype(ScrArea *area, int type); void ED_area_tag_refresh(ScrArea *area); +/** + * Only exported for WM. + */ void ED_area_do_refresh(struct bContext *C, ScrArea *area); struct AZone *ED_area_azones_update(ScrArea *area, const int mouse_xy[2]); +/** + * Use NULL to disable it. + */ void ED_area_status_text(ScrArea *area, const char *str); +/** + * \param skip_region_exit: Skip calling area exit callback. Set for opening temp spaces. + */ void ED_area_newspace(struct bContext *C, ScrArea *area, int type, const bool skip_region_exit); void ED_area_prevspace(struct bContext *C, ScrArea *area); void ED_area_swapspace(struct bContext *C, ScrArea *sa1, ScrArea *sa2); int ED_area_headersize(void); int ED_area_footersize(void); +/** + * \return the final height of a global \a area, accounting for DPI. + */ int ED_area_global_size_y(const ScrArea *area); int ED_area_global_min_size_y(const ScrArea *area); int ED_area_global_max_size_y(const ScrArea *area); bool ED_area_is_global(const ScrArea *area); +/** + * For now we just assume all global areas are made up out of horizontal bars + * with the same size. A fixed size could be stored in ARegion instead if needed. + * + * \return the DPI aware height of a single bar/region in global areas. + */ int ED_region_global_size_y(void); void ED_area_update_region_sizes(struct wmWindowManager *wm, struct wmWindow *win, @@ -204,31 +285,90 @@ ScrArea *ED_screen_areas_iter_next(const bScreen *screen, const ScrArea *area); vert_name->next) /* screens */ + +/** + * File read, set all screens, .... + */ void ED_screens_init(struct Main *bmain, struct wmWindowManager *wm); +/** + * Only for edge lines between areas. + */ void ED_screen_draw_edges(struct wmWindow *win); + +/** + * Make this screen usable. + * for file read and first use, for scaling window, area moves. + */ void ED_screen_refresh(struct wmWindowManager *wm, struct wmWindow *win); void ED_screen_ensure_updated(struct wmWindowManager *wm, struct wmWindow *win, struct bScreen *screen); void ED_screen_do_listen(struct bContext *C, struct wmNotifier *note); +/** + * \brief Change the active screen. + * + * Operator call, WM + Window + screen already existed before + * + * \warning Do NOT call in area/region queues! + * \returns if screen changing was successful. + */ bool ED_screen_change(struct bContext *C, struct bScreen *screen); void ED_screen_scene_change(struct bContext *C, struct wmWindow *win, struct Scene *scene, const bool refresh_toolsystem); +/** + * Called in wm_event_system.c. sets state vars in screen, cursors. + * event type is mouse move. + */ void ED_screen_set_active_region(struct bContext *C, struct wmWindow *win, const int xy[2]); void ED_screen_exit(struct bContext *C, struct wmWindow *window, struct bScreen *screen); +/** + * redraws: uses defines from `stime->redraws` + * \param enable: 1 - forward on, -1 - backwards on, 0 - off. + */ void ED_screen_animation_timer(struct bContext *C, int redraws, int sync, int enable); void ED_screen_animation_timer_update(struct bScreen *screen, int redraws); void ED_screen_restore_temp_type(struct bContext *C, ScrArea *area); ScrArea *ED_screen_full_newspace(struct bContext *C, ScrArea *area, int type); +/** + * \a was_prev_temp for the case previous space was a temporary full-screen as well + */ void ED_screen_full_prevspace(struct bContext *C, ScrArea *area); +/** + * Restore a screen / area back to default operation, after temp full-screen modes. + */ void ED_screen_full_restore(struct bContext *C, ScrArea *area); +/** + * Create a new temporary screen with a maximized, empty area. + * This can be closed with #ED_screen_state_toggle(). + * + * Use this to just create a new maximized screen/area, rather than maximizing an existing one. + * Otherwise, maximize with #ED_screen_state_toggle(). + */ bScreen *ED_screen_state_maximized_create(struct bContext *C); +/** + * This function toggles: if area is maximized/full then the parent will be restored. + * + * Use #ED_screen_state_maximized_create() if you do not want the toggle behavior when changing to + * a maximized area. I.e. if you just want to open a new maximized screen/area, not maximize a + * specific area. In the former case, space data of the maximized and non-maximized area should be + * independent, in the latter it should be the same. + * + * \warning \a area may be freed. + */ struct ScrArea *ED_screen_state_toggle(struct bContext *C, struct wmWindow *win, struct ScrArea *area, const short state); +/** + * Wrapper to open a temporary space either as fullscreen space, or as separate window, as defined + * by \a display_type. + * + * \param title: Title to set for the window, if a window is spawned. + * \param x, y: Position of the window, if a window is spawned. + * \param sizex, sizey: Dimensions of the window, if a window is spawned. + */ ScrArea *ED_screen_temp_space_open(struct bContext *C, const char *title, int x, @@ -243,8 +383,15 @@ void ED_screens_footer_tools_menu_create(struct bContext *C, struct uiLayout *la void ED_screens_navigation_bar_tools_menu_create(struct bContext *C, struct uiLayout *layout, void *arg); +/** + * \return true if any active area requires to see in 3D. + */ bool ED_screen_stereo3d_required(const struct bScreen *screen, const struct Scene *scene); Scene *ED_screen_scene_find(const struct bScreen *screen, const struct wmWindowManager *wm); +/** + * Find the scene displayed in \a screen. + * \note Assumes \a screen to be visible/active! + */ Scene *ED_screen_scene_find_with_window(const struct bScreen *screen, const struct wmWindowManager *wm, struct wmWindow **r_window); @@ -253,31 +400,64 @@ ScrArea *ED_screen_area_find_with_spacedata(const bScreen *screen, const bool only_visible); struct wmWindow *ED_screen_window_find(const struct bScreen *screen, const struct wmWindowManager *wm); +/** + * Render the preview for a screen layout in \a screen. + */ void ED_screen_preview_render(const struct bScreen *screen, int size_x, int size_y, unsigned int *r_rect) ATTR_NONNULL(); /* workspaces */ + struct WorkSpace *ED_workspace_add(struct Main *bmain, const char *name) ATTR_NONNULL(); +/** + * \brief Change the active workspace. + * + * Operator call, WM + Window + screen already existed before + * Pretty similar to #ED_screen_change since changing workspace also changes screen. + * + * \warning Do NOT call in area/region queues! + * \returns if workspace changing was successful. + */ bool ED_workspace_change(struct WorkSpace *workspace_new, struct bContext *C, struct wmWindowManager *wm, struct wmWindow *win) ATTR_NONNULL(); +/** + * Duplicate a workspace including its layouts. Does not activate the workspace, but + * it stores the screen-layout to be activated (BKE_workspace_temp_layout_store) + */ struct WorkSpace *ED_workspace_duplicate(struct WorkSpace *workspace_old, struct Main *bmain, struct wmWindow *win); +/** + * \return if succeeded. + */ bool ED_workspace_delete(struct WorkSpace *workspace, struct Main *bmain, struct bContext *C, struct wmWindowManager *wm) ATTR_NONNULL(); +/** + * Some editor data may need to be synced with scene data (3D View camera and layers). + * This function ensures data is synced for editors in active layout of \a workspace. + */ void ED_workspace_scene_data_sync(struct WorkSpaceInstanceHook *hook, Scene *scene) ATTR_NONNULL(); +/** + * Make sure there is a non-full-screen layout to switch to that isn't used yet by an other window. + * Needed for workspace or screen switching to ensure valid screens. + * + * \param layout_fallback_base: As last resort, this layout is duplicated and returned. + */ struct WorkSpaceLayout *ED_workspace_screen_change_ensure_unused_layout( struct Main *bmain, struct WorkSpace *workspace, struct WorkSpaceLayout *layout_new, const struct WorkSpaceLayout *layout_fallback_base, struct wmWindow *win) ATTR_NONNULL(); +/** + * Empty screen, with 1 dummy area without space-data. Uses window size. + */ struct WorkSpaceLayout *ED_workspace_layout_add(struct Main *bmain, struct WorkSpace *workspace, struct wmWindow *win, @@ -286,6 +466,10 @@ struct WorkSpaceLayout *ED_workspace_layout_duplicate(struct Main *bmain, struct WorkSpace *workspace, const struct WorkSpaceLayout *layout_old, struct wmWindow *win) ATTR_NONNULL(); +/** + * \warning Only call outside of area/region loops! + * \return true if succeeded. + */ bool ED_workspace_layout_delete(struct WorkSpace *workspace, struct WorkSpaceLayout *layout_old, struct bContext *C) ATTR_NONNULL(); @@ -296,22 +480,42 @@ bool ED_workspace_layout_cycle(struct WorkSpace *workspace, void ED_workspace_status_text(struct bContext *C, const char *str); /* anim */ +/** + * Results in fully updated anim system. + */ void ED_update_for_newframe(struct Main *bmain, struct Depsgraph *depsgraph); +/** + * Update frame rate info for viewport drawing. + */ void ED_refresh_viewport_fps(struct bContext *C); +/** + * Toggle operator. + */ int ED_screen_animation_play(struct bContext *C, int sync, int mode); +/** + * Find window that owns the animation timer. + */ bScreen *ED_screen_animation_playing(const struct wmWindowManager *wm); bScreen *ED_screen_animation_no_scrub(const struct wmWindowManager *wm); /* screen keymaps */ +/* called in spacetypes.c */ void ED_operatortypes_screen(void); +/* called in spacetypes.c */ void ED_keymap_screen(struct wmKeyConfig *keyconf); -/* workspace keymaps */ +/** + * Workspace key-maps. + */ void ED_operatortypes_workspace(void); /* operators; context poll callbacks */ + bool ED_operator_screenactive(struct bContext *C); bool ED_operator_screenactive_nobackground(struct bContext *C); +/** + * When mouse is over area-edge. + */ bool ED_operator_screen_mainwinactive(struct bContext *C); bool ED_operator_areaactive(struct bContext *C); bool ED_operator_regionactive(struct bContext *C); @@ -319,14 +523,31 @@ bool ED_operator_regionactive(struct bContext *C); bool ED_operator_scene(struct bContext *C); bool ED_operator_scene_editable(struct bContext *C); bool ED_operator_objectmode(struct bContext *C); +/** + * Same as #ED_operator_objectmode() but additionally sets a "disabled hint". That is, a message + * to be displayed to the user explaining why the operator can't be used in current context. + */ bool ED_operator_objectmode_poll_msg(struct bContext *C); bool ED_operator_view3d_active(struct bContext *C); bool ED_operator_region_view3d_active(struct bContext *C); +/** + * Generic for any view2d which uses anim_ops. + */ bool ED_operator_animview_active(struct bContext *C); bool ED_operator_outliner_active(struct bContext *C); bool ED_operator_outliner_active_no_editobject(struct bContext *C); +/** + * \note Will return true for file spaces in either file or asset browsing mode! See + * #ED_operator_file_browsing_active() (file browsing only) and + * #ED_operator_asset_browsing_active() (asset browsing only). + */ bool ED_operator_file_active(struct bContext *C); +/** + * \note Will only return true if the file space is in file browsing mode, not asset browsing! See + * #ED_operator_file_active() (file or asset browsing) and + * #ED_operator_asset_browsing_active() (asset browsing only). + */ bool ED_operator_file_browsing_active(struct bContext *C); bool ED_operator_asset_browsing_active(struct bContext *C); bool ED_operator_spreadsheet_active(struct bContext *C); @@ -345,6 +566,9 @@ bool ED_operator_console_active(struct bContext *C); bool ED_operator_object_active(struct bContext *C); bool ED_operator_object_active_editable_ex(struct bContext *C, const Object *ob); bool ED_operator_object_active_editable(struct bContext *C); +/** + * Object must be editable and fully local (i.e. not an override). + */ bool ED_operator_object_active_local_editable_ex(struct bContext *C, const Object *ob); bool ED_operator_object_active_local_editable(struct bContext *C); bool ED_operator_object_active_editable_mesh(struct bContext *C); @@ -363,11 +587,21 @@ bool ED_operator_editsurfcurve_region_view3d(struct bContext *C); bool ED_operator_editfont(struct bContext *C); bool ED_operator_editlattice(struct bContext *C); bool ED_operator_editmball(struct bContext *C); +/** + * Wrapper for #ED_space_image_show_uvedit. + */ bool ED_operator_uvedit(struct bContext *C); bool ED_operator_uvedit_space_image(struct bContext *C); bool ED_operator_uvmap(struct bContext *C); bool ED_operator_posemode_exclusive(struct bContext *C); +/** + * Object must be editable, fully local (i.e. not an override), and exclusively in Pose mode. + */ bool ED_operator_object_active_local_editable_posemode_exclusive(struct bContext *C); +/** + * Allows for pinned pose objects to be used in the object buttons + * and the non-active pose object to be used in the 3D view. + */ bool ED_operator_posemode_context(struct bContext *C); bool ED_operator_posemode(struct bContext *C); bool ED_operator_posemode_local(struct bContext *C); @@ -418,8 +652,15 @@ void ED_region_cache_draw_cached_segments(struct ARegion *region, const int efra); /* area_utils.c */ + +/** + * Callback for #ARegionType.message_subscribe + */ void ED_region_generic_tools_region_message_subscribe( const struct wmRegionMessageSubscribeParams *params); +/** + * Callback for #ARegionType.snap_size + */ int ED_region_generic_tools_region_snap_size(const struct ARegion *region, int size, int axis); /* area_query.c */ @@ -440,15 +681,29 @@ bool ED_region_overlap_isect_xy_with_margin(const ARegion *region, bool ED_region_panel_category_gutter_calc_rect(const ARegion *region, rcti *r_region_gutter); bool ED_region_panel_category_gutter_isect_xy(const ARegion *region, const int event_xy[2]); +/** + * \note: This may return true for multiple overlapping regions. + * If it matters, check overlapped regions first (#ARegion.overlap). + */ bool ED_region_contains_xy(const struct ARegion *region, const int event_xy[2]); +/** + * Similar to #BKE_area_find_region_xy() but when \a event_xy intersects an overlapping region, + * this returns the region that is visually under the cursor. E.g. when over the + * transparent part of the region, it returns the region underneath. + * + * The overlapping region is determined using the #ED_region_contains_xy() query. + */ ARegion *ED_area_find_region_xy_visual(const ScrArea *area, int regiontype, const int event_xy[2]); /* interface_region_hud.c */ + struct ARegionType *ED_area_type_hud(int space_type); void ED_area_type_hud_clear(struct wmWindowManager *wm, ScrArea *area_keep); void ED_area_type_hud_ensure(struct bContext *C, struct ScrArea *area); -/* default keymaps, bitflags (matches order of evaluation). */ +/** + * Default key-maps, bit-flags (matches order of evaluation). + */ enum { ED_KEYMAP_UI = (1 << 1), ED_KEYMAP_GIZMO = (1 << 2), @@ -462,7 +717,7 @@ enum { ED_KEYMAP_NAVBAR = (1 << 11), }; -/* SCREEN_OT_space_context_cycle direction */ +/** #SCREEN_OT_space_context_cycle direction. */ typedef enum eScreenCycle { SPACE_CONTEXT_CYCLE_PREV, SPACE_CONTEXT_CYCLE_NEXT, diff --git a/source/blender/editors/include/ED_sculpt.h b/source/blender/editors/include/ED_sculpt.h index 348ea503372..0cdd8873cb2 100644 --- a/source/blender/editors/include/ED_sculpt.h +++ b/source/blender/editors/include/ED_sculpt.h @@ -35,6 +35,7 @@ struct bContext; struct rcti; /* sculpt.c */ + void ED_operatortypes_sculpt(void); void ED_sculpt_redraw_planes_get(float planes[4][4], struct ARegion *region, struct Object *ob); bool ED_sculpt_mask_box_select(struct bContext *C, @@ -42,18 +43,22 @@ bool ED_sculpt_mask_box_select(struct bContext *C, const struct rcti *rect, bool select); -/* transform */ +/* sculpt_transform.c */ + void ED_sculpt_update_modal_transform(struct bContext *C, struct Object *ob); void ED_sculpt_init_transform(struct bContext *C, struct Object *ob); void ED_sculpt_end_transform(struct bContext *C, struct Object *ob); /* sculpt_undo.c */ + +/** Export for ED_undo_sys. */ void ED_sculpt_undosys_type(struct UndoType *ut); void ED_sculpt_undo_geometry_begin(struct Object *ob, const char *name); void ED_sculpt_undo_geometry_end(struct Object *ob); /* Face sets. */ + int ED_sculpt_face_sets_find_next_available_id(struct Mesh *mesh); void ED_sculpt_face_sets_initialize_none_to_id(struct Mesh *mesh, const int new_id); @@ -62,7 +67,7 @@ int ED_sculpt_face_sets_active_update_and_get(struct bContext *C, const float mval[2]); /* Undo for changes happening on a base mesh for multires sculpting. - * if there is no multires sculpt active regular undo is used. */ + * if there is no multi-res sculpt active regular undo is used. */ void ED_sculpt_undo_push_multires_mesh_begin(struct bContext *C, const char *str); void ED_sculpt_undo_push_multires_mesh_end(struct bContext *C, const char *str); diff --git a/source/blender/editors/include/ED_select_utils.h b/source/blender/editors/include/ED_select_utils.h index 049ea7a092f..4656099799b 100644 --- a/source/blender/editors/include/ED_select_utils.h +++ b/source/blender/editors/include/ED_select_utils.h @@ -60,8 +60,17 @@ enum { #define SEL_OP_USE_PRE_DESELECT(sel_op) (ELEM(sel_op, SEL_OP_SET)) #define SEL_OP_CAN_DESELECT(sel_op) (!ELEM(sel_op, SEL_OP_ADD)) -/* Use when we've de-selected all first for 'SEL_OP_SET' */ +/** + * Use when we've de-selected all first for 'SEL_OP_SET'. + * 1: select, 0: deselect, -1: pass. + */ int ED_select_op_action(const eSelectOp sel_op, const bool is_select, const bool is_inside); +/** + * Use when we've de-selected all items first (for modes that need it). + * + * \note In some cases changing selection needs to perform other checks, + * so it's more straightforward to deselect all, then select. + */ int ED_select_op_action_deselected(const eSelectOp sel_op, const bool is_select, const bool is_inside); @@ -72,6 +81,9 @@ bool ED_select_similar_compare_float_tree(const struct KDTree_1d *tree, const float thresh, const int compare); +/** + * Utility to use for selection operations that run multiple times (circle select). + */ eSelectOp ED_select_op_modal(const eSelectOp sel_op, const bool is_first); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_sequencer.h b/source/blender/editors/include/ED_sequencer.h index 606b4c9cad0..843b94cea00 100644 --- a/source/blender/editors/include/ED_sequencer.h +++ b/source/blender/editors/include/ED_sequencer.h @@ -40,8 +40,18 @@ bool ED_space_sequencer_maskedit_mask_poll(struct bContext *C); bool ED_space_sequencer_check_show_maskedit(struct SpaceSeq *sseq, struct Scene *scene); bool ED_space_sequencer_maskedit_poll(struct bContext *C); +/** + * Are we displaying the seq output (not channels or histogram). + */ bool ED_space_sequencer_check_show_imbuf(struct SpaceSeq *sseq); + bool ED_space_sequencer_check_show_strip(struct SpaceSeq *sseq); +/** + * Check if there is animation shown during playback. + * + * - Colors of color strips are displayed on the strip itself. + * - Backdrop is drawn. + */ bool ED_space_sequencer_has_playback_animation(const struct SpaceSeq *sseq, const struct Scene *scene); diff --git a/source/blender/editors/include/ED_space_api.h b/source/blender/editors/include/ED_space_api.h index 958df8f7707..f4a69737da1 100644 --- a/source/blender/editors/include/ED_space_api.h +++ b/source/blender/editors/include/ED_space_api.h @@ -30,12 +30,18 @@ extern "C" { struct ARegionType; struct bContext; +/* Only called once on startup. storage is global in BKE kernel listbase. */ void ED_spacetypes_init(void); void ED_spacemacros_init(void); /* the pluginnable API for export to editors */ -/* calls for registering default spaces */ +/* -------------------------------------------------------------------- */ +/** \name Calls for registering default spaces + * + * Calls for registering default spaces, only called once, from #ED_spacetypes_init + * \{ */ + void ED_spacetype_outliner(void); void ED_spacetype_view3d(void); void ED_spacetype_ipo(void); @@ -57,12 +63,18 @@ void ED_spacetype_statusbar(void); void ED_spacetype_topbar(void); void ED_spacetype_spreadsheet(void); -/* calls for instancing and freeing spacetype static data - * called in WM_init_exit */ -/* in space_file.c */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Spacetype Static Data + * Calls for instancing and freeing space-type static data called in #WM_init_exit + * \{ */ + void ED_file_init(void); void ED_file_exit(void); +/** \} */ + #define REGION_DRAW_POST_VIEW 0 #define REGION_DRAW_POST_PIXEL 1 #define REGION_DRAW_PRE_VIEW 2 diff --git a/source/blender/editors/include/ED_text.h b/source/blender/editors/include/ED_text.h index 6e012ec1a91..33ca3ea03a6 100644 --- a/source/blender/editors/include/ED_text.h +++ b/source/blender/editors/include/ED_text.h @@ -36,16 +36,25 @@ struct bContext; bool ED_text_activate_in_screen(struct bContext *C, struct Text *text); +/** + * Moves the view to the cursor location, also used to make sure the view isn't outside the file. + */ void ED_text_scroll_to_cursor(struct SpaceText *st, struct ARegion *region, bool center); +/** + * Takes a cursor (row, character) and returns x,y pixel coords. + */ bool ED_text_region_location_from_cursor(struct SpaceText *st, struct ARegion *region, const int cursor_co[2], int r_pixel_co[2]); /* text_undo.c */ + +/** Export for ED_undo_sys. */ void ED_text_undosys_type(struct UndoType *ut); +/** Use operator system to finish the undo step. */ struct UndoStep *ED_text_undo_push_init(struct bContext *C); /* text_format.c */ diff --git a/source/blender/editors/include/ED_transform.h b/source/blender/editors/include/ED_transform.h index b132e559baa..f0d6072fdbc 100644 --- a/source/blender/editors/include/ED_transform.h +++ b/source/blender/editors/include/ED_transform.h @@ -146,6 +146,15 @@ void Transform_Properties(struct wmOperatorType *ot, int flags); /* *** transform_orientations.c *** */ void ED_transform_calc_orientation_from_type(const struct bContext *C, float r_mat[3][3]); +/** + * \note The resulting matrix may not be orthogonal, + * callers that depend on `r_mat` to be orthogonal should use #orthogonalize_m3. + * + * A non orthogonal matrix may be returned when: + * - #V3D_ORIENT_GIMBAL the result won't be orthogonal unless the object has no rotation. + * - #V3D_ORIENT_LOCAL may contain shear from non-uniform scale in parent/child relationships. + * - #V3D_ORIENT_CUSTOM may have been created from #V3D_ORIENT_LOCAL. + */ short ED_transform_calc_orientation_from_type_ex(const struct Scene *scene, struct ViewLayer *view_layer, const struct View3D *v3d, @@ -159,6 +168,9 @@ short ED_transform_calc_orientation_from_type_ex(const struct Scene *scene, /* transform gizmos */ void VIEW3D_GGT_xform_gizmo(struct wmGizmoGroupType *gzgt); +/** + * Only poll, flag & gzmap_params differ. + */ void VIEW3D_GGT_xform_gizmo_context(struct wmGizmoGroupType *gzgt); void VIEW3D_GGT_xform_cage(struct wmGizmoGroupType *gzgt); void VIEW3D_GGT_xform_shear(struct wmGizmoGroupType *gzgt); @@ -196,6 +208,11 @@ struct TransformCalcParams { /* Use 'Scene.orientation_type' when zero, otherwise subtract one and use. */ ushort orientation_index; }; +/** + * Centroid, bound-box, of selection. + * + * Returns total items selected. + */ int ED_transform_calc_gizmo_stats(const struct bContext *C, const struct TransformCalcParams *params, struct TransformBounds *tbounds); diff --git a/source/blender/editors/include/ED_transform_snap_object_context.h b/source/blender/editors/include/ED_transform_snap_object_context.h index c4da1588117..6f25a63188d 100644 --- a/source/blender/editors/include/ED_transform_snap_object_context.h +++ b/source/blender/editors/include/ED_transform_snap_object_context.h @@ -117,6 +117,13 @@ bool ED_transform_snap_object_project_ray(SnapObjectContext *sctx, float r_co[3], float r_no[3]); +/** + * Fill in a list of all hits. + * + * \param ray_depth: Only depths in this range are considered, -1.0 for maximum. + * \param sort: Optionally sort the hits by depth. + * \param r_hit_list: List of #SnapObjectHitDepth (caller must free). + */ bool ED_transform_snap_object_project_ray_all(SnapObjectContext *sctx, struct Depsgraph *depsgraph, const View3D *v3d, @@ -142,6 +149,19 @@ short ED_transform_snap_object_project_view3d_ex(struct SnapObjectContext *sctx, struct Object **r_ob, float r_obmat[4][4], float r_face_nor[3]); +/** + * Convenience function for performing snapping. + * + * Given a 2D region value, snap to vert/edge/face. + * + * \param sctx: Snap context. + * \param mval: Screenspace coordinate. + * \param prev_co: Coordinate for perpendicular point calculation (optional). + * \param dist_px: Maximum distance to snap (in pixels). + * \param r_loc: hit location. + * \param r_no: hit normal (optional). + * \return Snap success. + */ short ED_transform_snap_object_project_view3d(struct SnapObjectContext *sctx, struct Depsgraph *depsgraph, const ARegion *region, @@ -155,6 +175,9 @@ short ED_transform_snap_object_project_view3d(struct SnapObjectContext *sctx, float r_loc[3], float r_no[3]); +/** + * see: #ED_transform_snap_object_project_ray_all + */ bool ED_transform_snap_object_project_all_view3d_ex(SnapObjectContext *sctx, struct Depsgraph *depsgraph, const ARegion *region, diff --git a/source/blender/editors/include/ED_undo.h b/source/blender/editors/include/ED_undo.h index 059277e1466..dceecc6aab5 100644 --- a/source/blender/editors/include/ED_undo.h +++ b/source/blender/editors/include/ED_undo.h @@ -36,6 +36,9 @@ struct wmOperator; struct wmOperatorType; /* undo.c */ +/** + * Run from the main event loop, basic checks that undo is left in a correct state. + */ bool ED_undo_is_state_valid(struct bContext *C); void ED_undo_group_begin(struct bContext *C); void ED_undo_group_end(struct bContext *C); @@ -52,18 +55,38 @@ void ED_OT_redo(struct wmOperatorType *ot); void ED_OT_undo_redo(struct wmOperatorType *ot); void ED_OT_undo_history(struct wmOperatorType *ot); +/** + * UI callbacks should call this rather than calling WM_operator_repeat() themselves. + */ int ED_undo_operator_repeat(struct bContext *C, struct wmOperator *op); -/* Convenience since UI callbacks use this mostly. */ +/** + * Convenience since UI callbacks use this mostly. + */ void ED_undo_operator_repeat_cb(struct bContext *C, void *arg_op, void *arg_unused); void ED_undo_operator_repeat_cb_evt(struct bContext *C, void *arg_op, int arg_unused); +/** + * Name optionally, function used to check for operator redo panel. + */ bool ED_undo_is_valid(const struct bContext *C, const char *undoname); bool ED_undo_is_memfile_compatible(const struct bContext *C); /* Unfortunate workaround for limits mixing undo systems. */ + +/** + * When a property of ID changes, return false. + * + * This is to avoid changes to a property making undo pushes + * which are ignored by the undo-system. + * For example, changing a brush property isn't stored by sculpt-mode undo steps. + * This workaround is needed until the limitation is removed, see: T61948. + */ bool ED_undo_is_legacy_compatible_for_property(struct bContext *C, struct ID *id); +/** + * Load all our objects from `object_array` into edit-mode, clear everything else. + */ void ED_undo_object_editmode_restore_helper(struct bContext *C, struct Object **object_array, uint object_array_len, @@ -73,6 +96,13 @@ struct Object **ED_undo_editmode_objects_from_view_layer(struct ViewLayer *view_ uint *r_len); struct Base **ED_undo_editmode_bases_from_view_layer(struct ViewLayer *view_layer, uint *r_len); +/** + * Ideally we won't access the stack directly, + * this is needed for modes which handle undo themselves (bypassing #ED_undo_push). + * + * Using global isn't great, this just avoids doing inline, + * causing 'BKE_global.h' & 'BKE_main.h' includes. + */ struct UndoStack *ED_undo_stack_get(void); /* helpers */ @@ -83,11 +113,28 @@ void ED_undo_object_set_active_or_warn(struct Scene *scene, struct CLG_LogRef *log); /* undo_system_types.c */ + void ED_undosys_type_init(void); void ED_undosys_type_free(void); /* memfile_undo.c */ + struct MemFile *ED_undosys_stack_memfile_get_active(struct UndoStack *ustack); +/** + * If the last undo step is a memfile one, find the first #MemFileChunk matching given ID + * (using its session UUID), and tag it as "changed in the future". + * + * Since non-memfile undo-steps cannot automatically set this flag in the previous step as done + * with memfile ones, this has to be called manually by relevant undo code. + * + * \note Only current known case for this is undoing a switch from Object to Sculpt mode (see + * T82388). + * + * \note Calling this ID by ID is not optimal, as it will loop over all #MemFile.chunks until it + * finds the expected one. If this becomes an issue we'll have to add a mapping from session UUID + * to first #MemFileChunk in #MemFile itself + * (currently we only do that in #MemFileWriteData when writing a new step). + */ void ED_undosys_stack_memfile_id_changed_tag(struct UndoStack *ustack, struct ID *id); #ifdef __cplusplus diff --git a/source/blender/editors/include/ED_util.h b/source/blender/editors/include/ED_util.h index df132e6ae80..69378d436ab 100644 --- a/source/blender/editors/include/ED_util.h +++ b/source/blender/editors/include/ED_util.h @@ -35,8 +35,12 @@ struct Main; struct bContext; /* ed_util.c */ + void ED_editors_init_for_undo(struct Main *bmain); void ED_editors_init(struct bContext *C); +/** + * Frees all edit-mode stuff. + */ void ED_editors_exit(struct Main *bmain, bool do_undo_system); bool ED_editors_flush_edits_for_object_ex(struct Main *bmain, @@ -45,9 +49,17 @@ bool ED_editors_flush_edits_for_object_ex(struct Main *bmain, bool check_needs_flush); bool ED_editors_flush_edits_for_object(struct Main *bmain, struct Object *ob); +/** + * Flush any temp data from object editing to DNA before writing files, rendering, copying, etc. + */ bool ED_editors_flush_edits_ex(struct Main *bmain, bool for_render, bool check_needs_flush); bool ED_editors_flush_edits(struct Main *bmain); +/** + * Use to free ID references within runtime data (stored outside of DNA) + * + * \param new_id: may be NULL to unlink \a old_id. + */ void ED_spacedata_id_remap(struct ScrArea *area, struct SpaceLink *sl, struct ID *old_id, @@ -56,21 +68,38 @@ void ED_spacedata_id_remap(struct ScrArea *area, void ED_operatortypes_edutils(void); /* Drawing */ + +/** + * Callback that draws a line between the mouse and a position given as the initial argument. + */ void ED_region_draw_mouse_line_cb(const struct bContext *C, struct ARegion *region, void *arg_info); +/** + * \note Keep in sync with #BKE_image_stamp_buf. + */ void ED_region_image_metadata_draw( int x, int y, struct ImBuf *ibuf, const rctf *frame, float zoomx, float zoomy); /* Slider */ + struct tSlider; struct tSlider *ED_slider_create(struct bContext *C); +/** + * For modal operations so the percentage doesn't pop on the first mouse movement. + */ void ED_slider_init(struct tSlider *slider, const struct wmEvent *event); +/** + * Calculate slider factor based on mouse position. + */ bool ED_slider_modal(struct tSlider *slider, const struct wmEvent *event); void ED_slider_destroy(struct bContext *C, struct tSlider *slider); +/** + * Return string based on the current state of the slider. + */ void ED_slider_status_string_get(const struct tSlider *slider, char *status_string, const size_t size_of_status_string); @@ -83,6 +112,11 @@ void ED_slider_allow_overshoot_set(struct tSlider *slider, const bool value); /* ************** XXX OLD CRUFT WARNING ************* */ +/** + * Now only used in 2D spaces, like time, f-curve, NLA, image, etc. + * + * \note Shift/Control are not configurable key-bindings. + */ void apply_keyb_grid( int shift, int ctrl, float *val, float fac1, float fac2, float fac3, int invert); diff --git a/source/blender/editors/include/ED_uvedit.h b/source/blender/editors/include/ED_uvedit.h index 884124396b9..e7b3c191d36 100644 --- a/source/blender/editors/include/ED_uvedit.h +++ b/source/blender/editors/include/ED_uvedit.h @@ -46,6 +46,7 @@ struct bNodeTree; struct wmKeyConfig; /* uvedit_ops.c */ + void ED_operatortypes_uvedit(void); void ED_operatormacros_uvedit(void); void ED_keymap_uvedit(struct wmKeyConfig *keyconf); @@ -54,6 +55,9 @@ bool ED_uvedit_minmax(const struct Scene *scene, struct Object *obedit, float min[2], float max[2]); +/** + * Be careful when using this, it bypasses all synchronization options. + */ void ED_uvedit_select_all(struct BMesh *bm); bool ED_uvedit_minmax_multi(const struct Scene *scene, @@ -231,12 +235,17 @@ struct BMLoop *ED_uvedit_active_vert_loop_get(struct BMesh *bm); void ED_uvedit_active_edge_loop_set(struct BMesh *bm, struct BMLoop *l); struct BMLoop *ED_uvedit_active_edge_loop_get(struct BMesh *bm); +/** + * Intentionally don't return #UV_SELECT_ISLAND as it's not an element type. + * In this case return #UV_SELECT_VERTEX as a fallback. + */ char ED_uvedit_select_mode_get(const struct Scene *scene); void ED_uvedit_select_sync_flush(const struct ToolSettings *ts, struct BMEditMesh *em, const bool select); /* uvedit_unwrap_ops.c */ + void ED_uvedit_live_unwrap_begin(struct Scene *scene, struct Object *obedit); void ED_uvedit_live_unwrap_re_solve(void); void ED_uvedit_live_unwrap_end(short cancel); @@ -245,9 +254,11 @@ void ED_uvedit_live_unwrap(const struct Scene *scene, struct Object **objects, i void ED_uvedit_add_simple_uvs(struct Main *bmain, const struct Scene *scene, struct Object *ob); /* uvedit_draw.c */ + void ED_image_draw_cursor(struct ARegion *region, const float cursor[2]); /* uvedit_buttons.c */ + void ED_uvedit_buttons_register(struct ARegionType *art); /* uvedit_islands.c */ @@ -273,6 +284,9 @@ struct UVPackIsland_Params { uint correct_aspect : 1; }; +/** + * Returns true if UV coordinates lie on a valid tile in UDIM grid or tiled image. + */ bool uv_coords_isect_udim(const struct Image *image, const int udim_grid[2], const float coords[2]); diff --git a/source/blender/editors/include/ED_view3d.h b/source/blender/editors/include/ED_view3d.h index 008ad5b3203..6c986d8efe1 100644 --- a/source/blender/editors/include/ED_view3d.h +++ b/source/blender/editors/include/ED_view3d.h @@ -107,6 +107,11 @@ void ED_view3d_background_color_get(const struct Scene *scene, bool ED_view3d_has_workbench_in_texture_color(const struct Scene *scene, const struct Object *ob, const struct View3D *v3d); +/** + * Cursor position in `r_cursor_co`, result in `r_cursor_co`, `mval` in region coords. + * + * \note cannot use `event->mval` here, called by #object_add(). + */ void ED_view3d_cursor3d_position(struct bContext *C, const int mval[2], const bool use_depth, @@ -124,11 +129,44 @@ void ED_view3d_cursor3d_update(struct bContext *C, struct Camera *ED_view3d_camera_data_get(struct View3D *v3d, struct RegionView3D *rv3d); +/** + * Calculate the view transformation matrix from RegionView3D input. + * The resulting matrix is equivalent to #RegionView3D.viewinv + * \param mat: The view 4x4 transformation matrix to calculate. + * \param ofs: The view offset, normally from #RegionView3D.ofs. + * \param quat: The view rotation, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from ofs, normally from #RegionView3D.dist. + */ void ED_view3d_to_m4(float mat[4][4], const float ofs[3], const float quat[4], const float dist); +/** + * Set the view transformation from a 4x4 matrix. + * + * \param mat: The view 4x4 transformation matrix to assign. + * \param ofs: The view offset, normally from #RegionView3D.ofs. + * \param quat: The view rotation, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from `ofs`, normally from #RegionView3D.dist. + */ void ED_view3d_from_m4(const float mat[4][4], float ofs[3], float quat[4], const float *dist); +/** + * Set the #RegionView3D members from an objects transformation and optionally lens. + * \param ob: The object to set the view to. + * \param ofs: The view offset to be set, normally from #RegionView3D.ofs. + * \param quat: The view rotation to be set, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from `ofs `to be set, normally from #RegionView3D.dist. + * \param lens: The view lens angle set for cameras and lights, normally from View3D.lens. + */ void ED_view3d_from_object( const struct Object *ob, float ofs[3], float quat[4], float *dist, float *lens); +/** + * Set the object transformation from #RegionView3D members. + * \param depsgraph: The depsgraph to get the evaluated object parent + * for the transformation calculation. + * \param ob: The object which has the transformation assigned. + * \param ofs: The view offset, normally from #RegionView3D.ofs. + * \param quat: The view rotation, quaternion normally from #RegionView3D.viewquat. + * \param dist: The view distance from `ofs`, normally from #RegionView3D.dist. + */ void ED_view3d_to_object(const struct Depsgraph *depsgraph, struct Object *ob, const float ofs[3], @@ -140,14 +178,24 @@ bool ED_view3d_camera_to_view_selected(struct Main *bmain, const struct Scene *scene, struct Object *camera_ob); +/** + * Use to store the last view, before entering camera view. + */ void ED_view3d_lastview_store(struct RegionView3D *rv3d); /* Depth buffer */ typedef enum { + /** Redraw viewport without Grease Pencil and Annotations. */ V3D_DEPTH_NO_GPENCIL = 0, + /** Redraw viewport with Grease Pencil and Annotations only. */ V3D_DEPTH_GPENCIL_ONLY, + /** Redraw viewport with active object only. */ V3D_DEPTH_OBJECT_ONLY, + } eV3DDepthOverrideMode; +/** + * Redraw the viewport depth buffer. + */ void ED_view3d_depth_override(struct Depsgraph *depsgraph, struct ARegion *region, struct View3D *v3d, @@ -309,6 +357,7 @@ void ED_view3d_cursor_snap_draw_util(struct RegionView3D *rv3d, /* view3d_iterators.c */ /* foreach iterators */ + void meshobject_foreachScreenVert( struct ViewContext *vc, void (*func)(void *userData, struct MVert *eve, const float screen_co[2], int index), @@ -328,6 +377,10 @@ void mesh_foreachScreenEdge(struct ViewContext *vc, void *userData, const eV3DProjTest clip_flag); +/** + * A version of #mesh_foreachScreenEdge that clips the segment when + * there is a clipping bounding box. + */ void mesh_foreachScreenEdge_clip_bb_segment(struct ViewContext *vc, void (*func)(void *userData, struct BMEdge *eed, @@ -352,6 +405,9 @@ void nurbs_foreachScreenVert(struct ViewContext *vc, const float screen_co[2]), void *userData, const eV3DProjTest clip_flag); +/** + * #ED_view3d_init_mats_rv3d must be called first. + */ void mball_foreachScreenElem(struct ViewContext *vc, void (*func)(void *userData, struct MetaElem *ml, @@ -364,6 +420,9 @@ void lattice_foreachScreenVert(struct ViewContext *vc, const float screen_co[2]), void *userData, const eV3DProjTest clip_flag); +/** + * #ED_view3d_init_mats_rv3d must be called first. + */ void armature_foreachScreenBone(struct ViewContext *vc, void (*func)(void *userData, struct EditBone *ebone, @@ -371,6 +430,10 @@ void armature_foreachScreenBone(struct ViewContext *vc, const float screen_co_b[2]), void *userData, const eV3DProjTest clip_flag); + +/** + * ED_view3d_init_mats_rv3d must be called first. + */ void pose_foreachScreenBone(struct ViewContext *vc, void (*func)(void *userData, struct bPoseChannel *pchan, @@ -381,10 +444,17 @@ void pose_foreachScreenBone(struct ViewContext *vc, /* *** end iterators *** */ /* view3d_project.c */ + +/** + * \note use #ED_view3d_ob_project_mat_get to get the projection matrix + */ void ED_view3d_project_float_v2_m4(const struct ARegion *region, const float co[3], float r_co[2], float mat[4][4]); +/** + * \note use #ED_view3d_ob_project_mat_get to get projecting mat + */ void ED_view3d_project_float_v3_m4(const struct ARegion *region, const float co[3], float r_co[3], @@ -399,10 +469,12 @@ eV3DProjStatus ED_view3d_project_short_ex(const struct ARegion *region, const float co[3], short r_co[2], const eV3DProjTest flag); +/* --- short --- */ eV3DProjStatus ED_view3d_project_short_global(const struct ARegion *region, const float co[3], short r_co[2], const eV3DProjTest flag); +/* object space, use ED_view3d_init_mats_rv3d before calling */ eV3DProjStatus ED_view3d_project_short_object(const struct ARegion *region, const float co[3], short r_co[2], @@ -415,10 +487,12 @@ eV3DProjStatus ED_view3d_project_int_ex(const struct ARegion *region, const float co[3], int r_co[2], const eV3DProjTest flag); +/* --- int --- */ eV3DProjStatus ED_view3d_project_int_global(const struct ARegion *region, const float co[3], int r_co[2], const eV3DProjTest flag); +/* object space, use ED_view3d_init_mats_rv3d before calling */ eV3DProjStatus ED_view3d_project_int_object(const struct ARegion *region, const float co[3], int r_co[2], @@ -431,10 +505,14 @@ eV3DProjStatus ED_view3d_project_float_ex(const struct ARegion *region, const float co[3], float r_co[2], const eV3DProjTest flag); +/* --- float --- */ eV3DProjStatus ED_view3d_project_float_global(const struct ARegion *region, const float co[3], float r_co[2], const eV3DProjTest flag); +/** + * Object space, use #ED_view3d_init_mats_rv3d before calling. + */ eV3DProjStatus ED_view3d_project_float_object(const struct ARegion *region, const float co[3], float r_co[2], @@ -443,17 +521,52 @@ eV3DProjStatus ED_view3d_project_float_object(const struct ARegion *region, float ED_view3d_pixel_size(const struct RegionView3D *rv3d, const float co[3]); float ED_view3d_pixel_size_no_ui_scale(const struct RegionView3D *rv3d, const float co[3]); +/** + * Calculate a depth value from \a co, use with #ED_view3d_win_to_delta + */ float ED_view3d_calc_zfac(const struct RegionView3D *rv3d, const float co[3], bool *r_flip); +/** + * Calculate a depth value from `co` (result should only be used for comparison). + */ float ED_view3d_calc_depth_for_comparison(const struct RegionView3D *rv3d, const float co[3]); bool ED_view3d_clip_segment(const struct RegionView3D *rv3d, float ray_start[3], float ray_end[3]); +/** + * Calculate a 3d viewpoint and direction vector from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_normal is the direction towards mval. + * ray_start is clipped by the view near limit so points in front of it are always in view. + * In orthographic view the resulting ray_normal will match the view vector. + * \param region: The region (used for the window width and height). + * \param v3d: The 3d viewport (used for near clipping value). + * \param mval: The area relative 2d location (such as event->mval, converted into float[2]). + * \param r_ray_start: The world-space point where the ray intersects the window plane. + * \param r_ray_normal: The normalized world-space direction of towards mval. + * \param do_clip_planes: Optionally clip the start of the ray by the view clipping planes. + * \return success, false if the ray is totally clipped. + */ bool ED_view3d_win_to_ray_clipped(struct Depsgraph *depsgraph, const struct ARegion *region, const struct View3D *v3d, const float mval[2], - float ray_start[3], - float ray_normal[3], - const bool do_clip); + float r_ray_start[3], + float r_ray_normal[3], + const bool do_clip_planes); +/** + * Calculate a 3d viewpoint and direction vector from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_normal is the direction towards `mval`. + * ray_start is clipped by the view near limit so points in front of it are always in view. + * In orthographic view the resulting ray_normal will match the view vector. + * This version also returns the ray_co point of the ray on window plane, useful to fix precision + * issues especially with orthographic view, where default ray_start is set rather far away. + * \param region: The region (used for the window width and height). + * \param v3d: The 3d viewport (used for near clipping value). + * \param mval: The area relative 2d location (such as `event->mval`, converted into float[2]). + * \param r_ray_co: The world-space point where the ray intersects the window plane. + * \param r_ray_normal: The normalized world-space direction of towards mval. + * \param r_ray_start: The world-space starting point of the ray. + * \param do_clip_planes: Optionally clip the start of the ray by the view clipping planes. + * \return success, false if the ray is totally clipped. + */ bool ED_view3d_win_to_ray_clipped_ex(struct Depsgraph *depsgraph, const struct ARegion *region, const struct View3D *v3d, @@ -461,14 +574,39 @@ bool ED_view3d_win_to_ray_clipped_ex(struct Depsgraph *depsgraph, float r_ray_co[3], float r_ray_normal[3], float r_ray_start[3], - bool do_clip); + bool do_clip_planes); +/** + * Calculate a 3d viewpoint and direction vector from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_normal is the direction towards `mval`. + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d location (such as `event->mval`, converted into float[2]). + * \param r_ray_start: The world-space point where the ray intersects the window plane. + * \param r_ray_normal: The normalized world-space direction of towards mval. + * + * \note Ignores view near/far clipping, + * to take this into account use #ED_view3d_win_to_ray_clipped. + */ void ED_view3d_win_to_ray(const struct ARegion *region, const float mval[2], float r_ray_start[3], float r_ray_normal[3]); +/** + * Calculate a normalized 3d direction vector from the viewpoint towards a global location. + * In orthographic view the resulting vector will match the view vector. + * \param rv3d: The region (used for the window width and height). + * \param coord: The world-space location. + * \param vec: The resulting normalized vector. + */ void ED_view3d_global_to_vector(const struct RegionView3D *rv3d, const float coord[3], float vec[3]); +/** + * Calculate a 3d location from 2d window coordinates. + * \param region: The region (used for the window width and height). + * \param depth_pt: The reference location used to calculate the Z depth. + * \param mval: The area relative location (such as `event->mval` converted to floats). + * \param r_out: The resulting world-space location. + */ void ED_view3d_win_to_3d(const struct View3D *v3d, const struct ARegion *region, const float depth_pt[3], @@ -484,6 +622,13 @@ bool ED_view3d_win_to_3d_on_plane(const struct ARegion *region, const float mval[2], const bool do_clip, float r_out[3]); +/** + * A wrapper for #ED_view3d_win_to_3d_on_plane that projects onto \a plane_fallback + * then maps this back to \a plane. + * + * This is intended to be used when \a plane is orthogonal to the views Z axis where + * projecting the \a mval doesn't work well (or fail completely when exactly aligned). + */ bool ED_view3d_win_to_3d_on_plane_with_fallback(const struct ARegion *region, const float plane[4], const float mval[2], @@ -495,19 +640,64 @@ bool ED_view3d_win_to_3d_on_plane_int(const struct ARegion *region, const int mval[2], const bool do_clip, float r_out[3]); +/** + * Calculate a 3d difference vector from 2d window offset. + * note that #ED_view3d_calc_zfac() must be called first to determine + * the depth used to calculate the delta. + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d difference (such as `event->mval[0] - other_x`). + * \param out: The resulting world-space delta. + */ void ED_view3d_win_to_delta(const struct ARegion *region, const float mval[2], float out[3], const float zfac); +/** + * Calculate a 3d origin from 2d window coordinates. + * \note Orthographic views have a less obvious origin, + * Since far clip can be a very large value resulting in numeric precision issues, + * the origin in this case is close to zero coordinate. + * + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d location (such as event->mval converted to floats). + * \param out: The resulting normalized world-space direction vector. + */ void ED_view3d_win_to_origin(const struct ARegion *region, const float mval[2], float out[3]); +/** + * Calculate a 3d direction vector from 2d window coordinates. + * This direction vector starts and the view in the direction of the 2d window coordinates. + * In orthographic view all window coordinates yield the same vector. + * + * \note doesn't rely on ED_view3d_calc_zfac + * for perspective view, get the vector direction to + * the mouse cursor as a normalized vector. + * + * \param region: The region (used for the window width and height). + * \param mval: The area relative 2d location (such as event->mval converted to floats). + * \param out: The resulting normalized world-space direction vector. + */ void ED_view3d_win_to_vector(const struct ARegion *region, const float mval[2], float out[3]); +/** + * Calculate a 3d segment from 2d window coordinates. + * This ray_start is located at the viewpoint, ray_end is a far point. + * ray_start and ray_end are clipped by the view near and far limits + * so points along this line are always in view. + * In orthographic view all resulting segments will be parallel. + * \param region: The region (used for the window width and height). + * \param v3d: The 3d viewport (used for near and far clipping range). + * \param mval: The area relative 2d location (such as event->mval, converted into float[2]). + * \param r_ray_start: The world-space starting point of the segment. + * \param r_ray_end: The world-space end point of the segment. + * \param do_clip_planes: Optionally clip the ray by the view clipping planes. + * \return success, false if the segment is totally clipped. + */ bool ED_view3d_win_to_segment_clipped(struct Depsgraph *depsgraph, const struct ARegion *region, struct View3D *v3d, const float mval[2], float r_ray_start[3], float r_ray_end[3], - const bool do_clip); + const bool do_clip_planes); void ED_view3d_ob_project_mat_get(const struct RegionView3D *v3d, const struct Object *ob, float r_pmat[4][4]); @@ -515,6 +705,10 @@ void ED_view3d_ob_project_mat_get_from_obmat(const struct RegionView3D *rv3d, const float obmat[4][4], float r_pmat[4][4]); +/** + * Convert between region relative coordinates (x,y) and depth component z and + * a point in world space. + */ void ED_view3d_project_v3(const struct ARegion *region, const float world[3], float r_region_co[3]); @@ -527,6 +721,9 @@ bool ED_view3d_unproject_v3( /* end */ void ED_view3d_dist_range_get(const struct View3D *v3d, float r_dist_range[2]); +/** + * \note copies logic of #ED_view3d_viewplane_get(), keep in sync. + */ bool ED_view3d_clip_range_get(struct Depsgraph *depsgraph, const struct View3D *v3d, const struct RegionView3D *rv3d, @@ -543,6 +740,9 @@ bool ED_view3d_viewplane_get(struct Depsgraph *depsgraph, float *r_clipend, float *r_pixsize); +/** + * Use instead of: `GPU_polygon_offset(rv3d->dist, ...)` see bug T37727. + */ void ED_view3d_polygon_offset(const struct RegionView3D *rv3d, const float dist); void ED_view3d_calc_camera_border(const struct Scene *scene, @@ -572,15 +772,61 @@ void ED_view3d_clipping_calc(struct BoundBox *bb, const struct ARegion *region, const struct Object *ob, const struct rcti *rect); +/** + * Clamp min/max by the viewport clipping. + * + * \note This is an approximation, with the limitation that the bounding box from the (mix, max) + * calculation might not have any geometry inside the clipped region. + * Performing a clipping test on each vertex would work well enough for most cases, + * although it's not perfect either as edges/faces may intersect the clipping without having any + * of their vertices inside it. + * A more accurate result would be quite involved. + * + * \return True when the arguments were clamped. + */ bool ED_view3d_clipping_clamp_minmax(const struct RegionView3D *rv3d, float min[3], float max[3]); void ED_view3d_clipping_local(struct RegionView3D *rv3d, const float mat[4][4]); +/** + * Return true when `co` is hidden by the 3D views clipping planes. + * + * \param is_local: When true use local (object-space) #ED_view3d_clipping_local must run first, + * then all comparisons can be done in local-space. + * \return True when `co` is outside all clipping planes. + * + * \note Callers should check #RV3D_CLIPPING_ENABLED first. + */ bool ED_view3d_clipping_test(const struct RegionView3D *rv3d, const float co[3], const bool is_local); float ED_view3d_radius_to_dist_persp(const float angle, const float radius); float ED_view3d_radius_to_dist_ortho(const float lens, const float radius); +/** + * Return a new #RegionView3D.dist value to fit the \a radius. + * + * \note Depth isn't taken into account, this will fit a flat plane exactly, + * but points towards the view (with a perspective projection), + * may be within the radius but outside the view. eg: + * + * <pre> + * + + * pt --> + /^ radius + * / | + * / | + * view + + + * \ | + * \ | + * \| + * + + * </pre> + * + * \param region: Can be NULL if \a use_aspect is false. + * \param persp: Allow the caller to tell what kind of perspective to use (ortho/view/camera) + * \param use_aspect: Increase the distance to account for non 1:1 view aspect. + * \param radius: The radius will be fitted exactly, + * typically pre-scaled by a margin (#VIEW3D_MARGIN). + */ float ED_view3d_radius_to_dist(const struct View3D *v3d, const struct ARegion *region, const struct Depsgraph *depsgraph, @@ -588,12 +834,26 @@ float ED_view3d_radius_to_dist(const struct View3D *v3d, const bool use_aspect, const float radius); -/* Back-buffer select and draw support. */ +/** + * Back-buffer select and draw support. + */ void ED_view3d_backbuf_depth_validate(struct ViewContext *vc); +/** + * allow for small values [0.5 - 2.5], + * and large values, FLT_MAX by clamping by the area size + */ int ED_view3d_backbuf_sample_size_clamp(struct ARegion *region, const float dist); void ED_view3d_select_id_validate(struct ViewContext *vc); +/** + * Get the world-space 3d location from a screen-space 2d point. + * TODO: Implement #alphaoverride. We don't want to zoom into billboards. + * + * \param mval: Input screen-space pixel location. + * \param mouse_worldloc: Output world-space location. + * \param fallback_depth_pt: Use this points depth when no depth can be found. + */ bool ED_view3d_autodist(struct Depsgraph *depsgraph, struct ARegion *region, struct View3D *v3d, @@ -602,6 +862,9 @@ bool ED_view3d_autodist(struct Depsgraph *depsgraph, const bool alphaoverride, const float fallback_depth_pt[3]); +/** + * No 4x4 sampling, run #ED_view3d_depth_override first. + */ bool ED_view3d_autodist_simple(struct ARegion *region, const int mval[2], float mouse_worldloc[3], @@ -635,9 +898,21 @@ typedef enum { eV3DSelectObjectFilter ED_view3d_select_filter_from_mode(const struct Scene *scene, const struct Object *obact); +/** + * Optionally cache data for multiple calls to #view3d_opengl_select + * + * just avoid GPU_select headers outside this file + */ void view3d_opengl_select_cache_begin(void); void view3d_opengl_select_cache_end(void); +/** + * \warning be sure to account for a negative return value + * This is an error, "Too many objects in select buffer" + * and no action should be taken (can crash blender) if this happens + * + * \note (vc->obedit == NULL) can be set to explicitly skip edit-object selection. + */ int view3d_opengl_select_ex(struct ViewContext *vc, unsigned int *buffer, unsigned int bufsize, @@ -665,28 +940,57 @@ void ED_view3d_viewcontext_init(struct bContext *C, struct ViewContext *vc, struct Depsgraph *depsgraph); void ED_view3d_viewcontext_init_object(struct ViewContext *vc, struct Object *obact); +/** + * Use this call when executing an operator, + * event system doesn't set for each event the OpenGL drawing context. + */ void view3d_operator_needs_opengl(const struct bContext *C); void view3d_region_operator_needs_opengl(struct wmWindow *win, struct ARegion *region); -/* XXX should move to BLI_math */ +/** XXX: should move to BLI_math */ bool edge_inside_circle(const float cent[2], float radius, const float screen_co_a[2], const float screen_co_b[2]); -/* get 3d region from context, also if mouse is in header or toolbar */ +/** + * Get 3D region from context, also if mouse is in header or toolbar. + */ struct RegionView3D *ED_view3d_context_rv3d(struct bContext *C); +/** + * Ideally would return an rv3d but in some cases the region is needed too + * so return that, the caller can then access the `region->regiondata`. + */ bool ED_view3d_context_user_region(struct bContext *C, struct View3D **r_v3d, struct ARegion **r_region); +/** + * Similar to #ED_view3d_context_user_region() but does not use context. Always performs a lookup. + * Also works if \a v3d is not the active space. + */ bool ED_view3d_area_user_region(const struct ScrArea *area, const struct View3D *v3d, struct ARegion **r_region); bool ED_operator_rv3d_user_region_poll(struct bContext *C); +/** + * Most of the time this isn't needed since you could assume the view matrix was + * set while drawing, however when functions like mesh_foreachScreenVert are + * called by selection tools, we can't be sure this object was the last. + * + * for example, transparent objects are drawn after edit-mode and will cause + * the rv3d mat's to change and break selection. + * + * 'ED_view3d_init_mats_rv3d' should be called before + * view3d_project_short_clip and view3d_project_short_noclip in cases where + * these functions are not used during draw_object + */ void ED_view3d_init_mats_rv3d(const struct Object *ob, struct RegionView3D *rv3d); void ED_view3d_init_mats_rv3d_gl(const struct Object *ob, struct RegionView3D *rv3d); #ifdef DEBUG +/** + * Ensure we correctly initialize. + */ void ED_view3d_clear_mats_rv3d(struct RegionView3D *rv3d); void ED_view3d_check_mats_rv3d(struct RegionView3D *rv3d); #else @@ -705,6 +1009,9 @@ void ED_draw_object_facemap(struct Depsgraph *depsgraph, struct RenderEngineType *ED_view3d_engine_type(const struct Scene *scene, int drawtype); bool ED_view3d_context_activate(struct bContext *C); +/** + * Set the correct matrices + */ void ED_view3d_draw_setup_view(const struct wmWindowManager *wm, struct wmWindow *win, struct Depsgraph *depsgraph, @@ -715,13 +1022,22 @@ void ED_view3d_draw_setup_view(const struct wmWindowManager *wm, const float winmat[4][4], const struct rcti *rect); +/** + * `mval` comes from event->mval, only use within region handlers. + */ struct Base *ED_view3d_give_base_under_cursor(struct bContext *C, const int mval[2]); struct Object *ED_view3d_give_object_under_cursor(struct bContext *C, const int mval[2]); struct Object *ED_view3d_give_material_slot_under_cursor(struct bContext *C, const int mval[2], int *r_material_slot); bool ED_view3d_is_object_under_cursor(struct bContext *C, const int mval[2]); +/** + * 'clip' is used to know if our clip setting has changed. + */ void ED_view3d_quadview_update(struct ScrArea *area, struct ARegion *region, bool do_clip); +/** + * \note keep this synced with #ED_view3d_mats_rv3d_backup/#ED_view3d_mats_rv3d_restore + */ void ED_view3d_update_viewmat(struct Depsgraph *depsgraph, const struct Scene *scene, struct View3D *v3d, @@ -744,23 +1060,48 @@ void ED_view3d_datamask(const struct bContext *C, const struct Scene *scene, const struct View3D *v3d, struct CustomData_MeshMasks *r_cddata_masks); +/** + * Goes over all modes and view3d settings. + */ void ED_view3d_screen_datamask(const struct bContext *C, const struct Scene *scene, const struct bScreen *screen, struct CustomData_MeshMasks *r_cddata_masks); bool ED_view3d_offset_lock_check(const struct View3D *v3d, const struct RegionView3D *rv3d); +/** + * For viewport operators that exit camera perspective. + * + * \note This differs from simply setting `rv3d->persp = persp` because it + * sets the `ofs` and `dist` values of the viewport so it matches the camera, + * otherwise switching out of camera view may jump to a different part of the scene. + */ void ED_view3d_persp_switch_from_camera(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d, const char persp); +/** + * Action to take when rotating the view, + * handle auto-perspective and logic for switching out of views. + * + * shared with NDOF. + */ bool ED_view3d_persp_ensure(const struct Depsgraph *depsgraph, struct View3D *v3d, struct ARegion *region); -/* camera lock functions */ +/* Camera lock functions */ + +/** + * \return true when the 3D Viewport is locked to its camera. + */ bool ED_view3d_camera_lock_check(const struct View3D *v3d, const struct RegionView3D *rv3d); -/* copy the camera to the view before starting a view transformation */ +/** + * Copy the camera to the view before starting a view transformation. + * + * Apply the camera object transformation to the 3D Viewport. + * (needed so we can use regular 3D Viewport manipulation operators, that sync back to the camera). + */ void ED_view3d_camera_lock_init_ex(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d, @@ -768,7 +1109,13 @@ void ED_view3d_camera_lock_init_ex(const struct Depsgraph *depsgraph, void ED_view3d_camera_lock_init(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d); -/* copy the view to the camera, return true if */ +/** + * Copy the view to the camera, return true if. + * + * Apply the 3D Viewport transformation back to the camera object. + * + * \return true if the camera is moved. + */ bool ED_view3d_camera_lock_sync(const struct Depsgraph *depsgraph, struct View3D *v3d, struct RegionView3D *rv3d); @@ -778,6 +1125,12 @@ bool ED_view3d_camera_autokey(const struct Scene *scene, struct bContext *C, const bool do_rotate, const bool do_translate); +/** + * Call after modifying a locked view. + * + * \note Not every view edit currently auto-keys (numeric-pad for eg), + * this is complicated because of smooth-view. + */ bool ED_view3d_camera_lock_autokey(struct View3D *v3d, struct RegionView3D *rv3d, struct bContext *C, @@ -789,14 +1142,41 @@ void ED_view3d_lock_clear(struct View3D *v3d); #define VIEW3D_MARGIN 1.4f #define VIEW3D_DIST_FALLBACK 1.0f +/** + * This function solves the problem of having to switch between camera and non-camera views. + * + * When viewing from the perspective of \a mat, and having the view center \a ofs, + * this calculates a distance from \a ofs to the matrix \a mat. + * Using \a fallback_dist when the distance would be too small. + * + * \param mat: A matrix use for the view-point (typically the camera objects matrix). + * \param ofs: Orbit center (negated), matching #RegionView3D.ofs, which is typically passed in. + * \param fallback_dist: The distance to use if the object is too near or in front of \a ofs. + * \returns A newly calculated distance or the fallback. + */ float ED_view3d_offset_distance(const float mat[4][4], const float ofs[3], const float fallback_dist); +/** + * Set the dist without moving the view (compensate with #RegionView3D.ofs) + * + * \note take care that #RegionView3d.viewinv is up to date, #ED_view3d_update_viewmat first. + */ void ED_view3d_distance_set(struct RegionView3D *rv3d, const float dist); +/** + * Change the distance & offset to match the depth of \a dist_co along the view axis. + * + * \param dist_co: A world-space location to use for the new depth. + * \param dist_min: Resulting distances below this will be ignored. + * \return Success if the distance was set. + */ bool ED_view3d_distance_set_from_location(struct RegionView3D *rv3d, const float dist_co[3], const float dist_min); +/** + * Could move this elsewhere, but tied into #ED_view3d_grid_scale + */ float ED_scene_grid_scale(const struct Scene *scene, const char **r_grid_unit); float ED_view3d_grid_scale(const struct Scene *scene, struct View3D *v3d, @@ -805,14 +1185,24 @@ void ED_view3d_grid_steps(const struct Scene *scene, struct View3D *v3d, struct RegionView3D *rv3d, float r_grid_steps[8]); +/** + * Simulates the grid scale that is actually viewed. + * The actual code is seen in `object_grid_frag.glsl` (see `grid_res`). + * Currently the simulation is only done when RV3D_VIEW_IS_AXIS. + */ float ED_view3d_grid_view_scale(struct Scene *scene, struct View3D *v3d, struct ARegion *region, const char **r_grid_unit); +/** + * \note The info that this uses is updated in #ED_refresh_viewport_fps, + * which currently gets called during #SCREEN_OT_animation_step. + */ void ED_scene_draw_fps(const struct Scene *scene, int xoffset, int *yoffset); -/* render */ +/* Render */ + void ED_view3d_stop_render_preview(struct wmWindowManager *wm, struct ARegion *region); void ED_view3d_shade_update(struct Main *bmain, struct View3D *v3d, struct ScrArea *area); @@ -825,7 +1215,10 @@ void ED_view3d_shade_update(struct Main *bmain, struct View3D *v3d, struct ScrAr #define XRAY_ACTIVE(v3d) (XRAY_ENABLED(v3d) && ((v3d)->shading.type < OB_MATERIAL)) /* view3d_draw_legacy.c */ -/* Try avoid using these more move out of legacy. */ + +/** + * Try avoid using these more move out of legacy. + */ void ED_view3d_draw_bgpic_test(const struct Scene *scene, struct Depsgraph *depsgraph, struct ARegion *region, @@ -834,6 +1227,7 @@ void ED_view3d_draw_bgpic_test(const struct Scene *scene, const bool do_camera_frame); /* view3d_gizmo_preselect_type.c */ + void ED_view3d_gizmo_mesh_preselect_get_active(struct bContext *C, struct wmGizmo *gz, struct Base **r_base, @@ -841,11 +1235,17 @@ void ED_view3d_gizmo_mesh_preselect_get_active(struct bContext *C, void ED_view3d_gizmo_mesh_preselect_clear(struct wmGizmo *gz); /* space_view3d.c */ + void ED_view3d_buttons_region_layout_ex(const struct bContext *C, struct ARegion *region, const char *category_override); /* view3d_view.c */ + +/** + * See if current UUID is valid, otherwise set a valid UUID to v3d, + * Try to keep the same UUID previously used to allow users to quickly toggle back and forth. + */ bool ED_view3d_local_collections_set(struct Main *bmain, struct View3D *v3d); void ED_view3d_local_collections_reset(struct bContext *C, const bool reset_all); diff --git a/source/blender/editors/include/ED_view3d_offscreen.h b/source/blender/editors/include/ED_view3d_offscreen.h index 8b695e61a35..1da0a282697 100644 --- a/source/blender/editors/include/ED_view3d_offscreen.h +++ b/source/blender/editors/include/ED_view3d_offscreen.h @@ -57,6 +57,10 @@ void ED_view3d_draw_offscreen(struct Depsgraph *depsgraph, const bool restore_rv3d_mats, struct GPUOffScreen *ofs, struct GPUViewport *viewport); +/** + * Creates own fake 3d views (wrapping #ED_view3d_draw_offscreen). Similar too + * #ED_view_draw_offscreen_imbuf_simple, but takes view/projection matrices as arguments. + */ void ED_view3d_draw_offscreen_simple(struct Depsgraph *depsgraph, struct Scene *scene, struct View3DShading *shading_override, @@ -76,6 +80,12 @@ void ED_view3d_draw_offscreen_simple(struct Depsgraph *depsgraph, struct GPUOffScreen *ofs, struct GPUViewport *viewport); +/** + * Utility func for ED_view3d_draw_offscreen + * + * \param ofs: Optional off-screen buffer, can be NULL. + * (avoids re-creating when doing multiple GL renders). + */ struct ImBuf *ED_view3d_draw_offscreen_imbuf(struct Depsgraph *depsgraph, struct Scene *scene, eDrawType drawtype, @@ -89,6 +99,14 @@ struct ImBuf *ED_view3d_draw_offscreen_imbuf(struct Depsgraph *depsgraph, const bool restore_rv3d_mats, struct GPUOffScreen *ofs, char err_out[256]); +/** + * Creates own fake 3d views (wrapping #ED_view3d_draw_offscreen_imbuf) + * + * \param ofs: Optional off-screen buffer can be NULL. + * (avoids re-creating when doing multiple GL renders). + * + * \note used by the sequencer + */ struct ImBuf *ED_view3d_draw_offscreen_imbuf_simple(struct Depsgraph *depsgraph, struct Scene *scene, struct View3DShading *shading_override, diff --git a/source/blender/editors/include/UI_icons.h b/source/blender/editors/include/UI_icons.h index c3c296f89ca..4cf606bf98d 100644 --- a/source/blender/editors/include/UI_icons.h +++ b/source/blender/editors/include/UI_icons.h @@ -774,7 +774,7 @@ DEF_ICON_BLANK(276) DEF_ICON_BLANK(277) DEF_ICON_BLANK(772) DEF_ICON_BLANK(773) -DEF_ICON_BLANK(774) +DEF_ICON(CURRENT_FILE) DEF_ICON(HOME) DEF_ICON(DOCUMENTS) DEF_ICON(TEMP) diff --git a/source/blender/editors/include/UI_interface.h b/source/blender/editors/include/UI_interface.h index aa0dc222614..9df5b17975a 100644 --- a/source/blender/editors/include/UI_interface.h +++ b/source/blender/editors/include/UI_interface.h @@ -258,6 +258,8 @@ enum { #define UI_PANEL_CATEGORY_MARGIN_WIDTH (U.widget_unit * 1.0f) +/* Both these margins should be ignored if the panel doesn't show a background (check + * #UI_panel_should_show_background()). */ #define UI_PANEL_MARGIN_X (U.widget_unit * 0.4f) #define UI_PANEL_MARGIN_Y (U.widget_unit * 0.1f) @@ -400,9 +402,8 @@ typedef enum { /** Resize handle (resize uilist). */ UI_BTYPE_GRIP = 57 << 9, UI_BTYPE_DECORATOR = 58 << 9, - UI_BTYPE_DATASETROW = 59 << 9, /* An item in a tree view. Parent items may be collapsible. */ - UI_BTYPE_TREEROW = 60 << 9, + UI_BTYPE_TREEROW = 59 << 9, } eButType; #define BUTTYPE (63 << 9) @@ -450,6 +451,14 @@ int UI_draw_roundbox_corner_get(void); void UI_draw_box_shadow(const struct rctf *rect, unsigned char alpha); void UI_draw_text_underline(int pos_x, int pos_y, int len, int height, const float color[4]); +/** + * Draw title and text safe areas. + * + * \note This function is to be used with the 2D dashed shader enabled. + * + * \param pos: is a #PRIM_FLOAT, 2, #GPU_FETCH_FLOAT vertex attribute. + * \param rect: The offsets for the view, not the zones. + */ void UI_draw_safe_areas(uint pos, const struct rctf *rect, const float title_aspect[2], @@ -461,12 +470,27 @@ enum { UI_SCROLL_ARROWS = 1 << 1, UI_SCROLL_NO_OUTLINE = 1 << 2, }; +/** + * Function in use for buttons and for view2d sliders. + */ void UI_draw_widget_scroll(struct uiWidgetColors *wcol, const struct rcti *rect, const struct rcti *slider, int state); -/* Shortening string helper. */ +/** + * Shortening string helper. + * + * Cut off the middle of the text to fit into the given width. + * + * \note in case this middle clipping would just remove a few chars, + * it rather clips right, which is more readable. + * + * If rpart_sep is not Null, the part of str starting to first occurrence of rpart_sep + * is preserved at all cost. + * Useful for strings with shortcuts + * (like 'AVeryLongFooBarLabelForMenuEntry|Ctrl O' -> 'AVeryLong...MenuEntry|Ctrl O'). + */ float UI_text_clip_middle_ex(const struct uiFontStyle *fstyle, char *str, float okwidth, @@ -502,9 +526,11 @@ typedef int (*uiButCompleteFunc)(struct bContext *C, char *str, void *arg); typedef struct ARegion *(*uiButSearchCreateFn)(struct bContext *C, struct ARegion *butregion, struct uiButSearch *search_but); -/* `is_first` is typically used to ignore search filtering when the menu is first opened in order +/** + * `is_first` is typically used to ignore search filtering when the menu is first opened in order * to display the full list of options. The value will be false after the button's text is edited - * (for every call except the first). */ + * (for every call except the first). + */ typedef void (*uiButSearchUpdateFn)(const struct bContext *C, void *arg, const char *str, @@ -591,6 +617,7 @@ typedef void (*uiFreeArgFunc)(void *arg); /* interface_query.c */ bool UI_but_has_tooltip_label(const uiBut *but); bool UI_but_is_tool(const uiBut *but); +/* file selectors are exempt from utf-8 checks */ bool UI_but_is_utf8(const uiBut *but); #define UI_but_is_decorator(but) ((but)->type == UI_BTYPE_DECORATOR) @@ -612,10 +639,17 @@ struct uiList *UI_list_find_mouse_over(const struct ARegion *region, const struc typedef struct uiPopupMenu uiPopupMenu; uiPopupMenu *UI_popup_menu_begin(struct bContext *C, const char *title, int icon) ATTR_NONNULL(); +/** + * Only return handler, and set optional title. + * \param block_name: Assigned to uiBlock.name (useful info for debugging). + */ uiPopupMenu *UI_popup_menu_begin_ex(struct bContext *C, const char *title, const char *block_name, int icon) ATTR_NONNULL(); +/** + * Set the whole structure to work. + */ void UI_popup_menu_end(struct bContext *C, struct uiPopupMenu *pup); bool UI_popup_menu_end_or_cancel(struct bContext *C, struct uiPopupMenu *head); struct uiLayout *UI_popup_menu_layout(uiPopupMenu *pup); @@ -624,7 +658,14 @@ void UI_popup_menu_reports(struct bContext *C, struct ReportList *reports) ATTR_ int UI_popup_menu_invoke(struct bContext *C, const char *idname, struct ReportList *reports) ATTR_NONNULL(1, 2); +/** + * Allow setting menu return value from externals. + * E.g. WM might need to do this for exiting files correctly. + */ void UI_popup_menu_retval_set(const uiBlock *block, const int retval, const bool enable); +/** + * Setting the button makes the popup open from the button instead of the cursor. + */ void UI_popup_menu_but_set(uiPopupMenu *pup, struct ARegion *butregion, uiBut *but); /* interface_region_popover.c */ @@ -636,8 +677,17 @@ int UI_popover_panel_invoke(struct bContext *C, bool keep_open, struct ReportList *reports); +/** + * Only return handler, and set optional title. + * + * \param from_active_button: Use the active button for positioning, + * use when the popover is activated from an operator instead of directly from the button. + */ uiPopover *UI_popover_begin(struct bContext *C, int menu_width, bool from_active_button) ATTR_NONNULL(1); +/** + * Set the whole structure to work. + */ void UI_popover_end(struct bContext *C, struct uiPopover *pup, struct wmKeyMap *keymap); struct uiLayout *UI_popover_layout(uiPopover *pup); void UI_popover_once_clear(uiPopover *pup); @@ -715,6 +765,9 @@ uiBlock *UI_block_begin(const struct bContext *C, eUIEmbossType emboss); void UI_block_end_ex(const struct bContext *C, uiBlock *block, const int xy[2], int r_xy[2]); void UI_block_end(const struct bContext *C, uiBlock *block); +/** + * Uses local copy of style, to scale things down, and allow widgets to change stuff. + */ void UI_block_draw(const struct bContext *C, struct uiBlock *block); void UI_blocklist_update_window_matrix(const struct bContext *C, const struct ListBase *lb); void UI_blocklist_update_view_for_buttons(const struct bContext *C, const struct ListBase *lb); @@ -729,19 +782,36 @@ void UI_block_theme_style_set(uiBlock *block, char theme_style); eUIEmbossType UI_block_emboss_get(uiBlock *block); void UI_block_emboss_set(uiBlock *block, eUIEmbossType emboss); bool UI_block_is_search_only(const uiBlock *block); +/** + * Use when a block must be searched to give accurate results + * for the whole region but shouldn't be displayed. + */ void UI_block_set_search_only(uiBlock *block, bool search_only); +/** + * Can be called with C==NULL. + */ void UI_block_free(const struct bContext *C, uiBlock *block); -void UI_blocklist_free(const struct bContext *C, struct ListBase *lb); -void UI_blocklist_free_inactive(const struct bContext *C, struct ListBase *lb); -void UI_screen_free_active_but(const struct bContext *C, struct bScreen *screen); +/** + * Can be called with C==NULL. + */ +void UI_blocklist_free(const struct bContext *C, struct ARegion *region); +void UI_blocklist_free_inactive(const struct bContext *C, struct ARegion *region); + +/** + * Is called by notifier. + */ +void UI_screen_free_active_but_highlight(const struct bContext *C, struct bScreen *screen); +void UI_region_free_active_but_all(struct bContext *context, struct ARegion *region); void UI_block_region_set(uiBlock *block, struct ARegion *region); void UI_block_lock_set(uiBlock *block, bool val, const char *lockstr); void UI_block_lock_clear(uiBlock *block); -/* Automatic aligning, horizontal or vertical. */ +/** + * Automatic aligning, horizontal or vertical. + */ void UI_block_align_begin(uiBlock *block); void UI_block_align_end(uiBlock *block); @@ -756,16 +826,34 @@ typedef enum { UI_BLOCK_BOUNDS_PIE_CENTER, } eBlockBoundsCalc; +/** + * Used for various cases. + */ void UI_block_bounds_set_normal(struct uiBlock *block, int addval); +/** + * Used for pull-downs. + */ void UI_block_bounds_set_text(uiBlock *block, int addval); +/** + * Used for block popups. + */ void UI_block_bounds_set_popup(uiBlock *block, int addval, const int bounds_offset[2]); +/** + * Used for menu popups. + */ void UI_block_bounds_set_menu(uiBlock *block, int addval, const int bounds_offset[2]); +/** + * Used for centered popups, i.e. splash. + */ void UI_block_bounds_set_centered(uiBlock *block, int addval); void UI_block_bounds_set_explicit(uiBlock *block, int minx, int miny, int maxx, int maxy); int UI_blocklist_min_y_get(struct ListBase *lb); void UI_block_direction_set(uiBlock *block, char direction); +/** + * This call escapes if there's alignment flags. + */ void UI_block_order_flip(uiBlock *block); void UI_block_flag_enable(uiBlock *block, int flag); void UI_block_flag_disable(uiBlock *block, int flag); @@ -774,7 +862,14 @@ void UI_block_translate(uiBlock *block, int x, int y); int UI_but_return_value_get(uiBut *but); void UI_but_drag_set_id(uiBut *but, struct ID *id); +/** + * Set an image to display while dragging. This works for any drag type (`WM_DRAG_XXX`). + * Not to be confused with #UI_but_drag_set_image(), which sets up dragging of an image. + */ void UI_but_drag_attach_image(uiBut *but, struct ImBuf *imb, const float scale); +/** + * \param asset: May be passed from a temporary variable, drag data only stores a copy of this. + */ void UI_but_drag_set_asset(uiBut *but, const struct AssetHandle *asset, const char *path, @@ -786,11 +881,18 @@ void UI_but_drag_set_asset(uiBut *but, void UI_but_drag_set_rna(uiBut *but, struct PointerRNA *ptr); void UI_but_drag_set_path(uiBut *but, const char *path, const bool use_free); void UI_but_drag_set_name(uiBut *but, const char *name); +/** + * Value from button itself. + */ void UI_but_drag_set_value(uiBut *but); void UI_but_drag_set_image( uiBut *but, const char *path, int icon, struct ImBuf *imb, float scale, const bool use_free); uiBut *UI_but_active_drop_name_button(const struct bContext *C); +/** + * Returns true if highlighted button allows drop of names. + * called in region context. + */ bool UI_but_active_drop_name(const struct bContext *C); bool UI_but_active_drop_color(struct bContext *C); @@ -805,7 +907,13 @@ void UI_but_disable(uiBut *but, const char *disabled_hint); void UI_but_type_set_menu_from_pulldown(uiBut *but); -/* special button case, only draw it when used actively, for outliner etc */ +/** + * Special button case, only draw it when used actively, for outliner etc. + * + * Needed for temporarily rename buttons, such as in outliner or file-select, + * they should keep calling #uiDefBut to keep them alive. + * \return false when button removed. + */ bool UI_but_active_only_ex(const struct bContext *C, struct ARegion *region, uiBlock *block, @@ -815,10 +923,17 @@ bool UI_but_active_only(const struct bContext *C, struct ARegion *region, uiBlock *block, uiBut *but); +/** + * \warning This must run after other handlers have been added, + * otherwise the handler won't be removed, see: T71112. + */ bool UI_block_active_only_flagged_buttons(const struct bContext *C, struct ARegion *region, struct uiBlock *block); +/** + * Simulate button click. + */ void UI_but_execute(const struct bContext *C, struct ARegion *region, uiBut *but); bool UI_but_online_manual_id(const uiBut *but, @@ -1022,6 +1137,9 @@ uiBut *uiDefButO_ptr(uiBlock *block, short height, const char *tip); +/** + * If a1==1.0 then a2 is an extra icon blending factor (alpha 0.0 - 1.0). + */ uiBut *uiDefIconBut(uiBlock *block, int type, int retval, @@ -1207,6 +1325,7 @@ uiBut *uiDefIconButO_ptr(uiBlock *block, uiBut *uiDefButImage( uiBlock *block, void *imbuf, int x, int y, short width, short height, const uchar color[4]); uiBut *uiDefButAlert(uiBlock *block, int icon, int x, int y, short width, short height); +/* Button containing both string label and icon */ uiBut *uiDefIconTextBut(uiBlock *block, int type, int retval, @@ -1477,7 +1596,10 @@ enum { UI_TEMPLATE_ID_FILTER_AVAILABLE = 1, }; +/***************************** ID Utilities *******************************/ + int UI_icon_from_id(const struct ID *id); +/** See: #BKE_report_type_str */ int UI_icon_from_report_type(int type); int UI_icon_colorid_from_report_type(int type); int UI_text_colorid_from_report_type(int type); @@ -1542,6 +1664,9 @@ uiBut *uiDefBlockButN(uiBlock *block, short height, const char *tip); +/** + * Block button containing icon. + */ uiBut *uiDefIconBlockBut(uiBlock *block, uiBlockCreateFunc func, void *arg, @@ -1552,6 +1677,9 @@ uiBut *uiDefIconBlockBut(uiBlock *block, short width, short height, const char *tip); +/** + * Block button containing both string label and icon. + */ uiBut *uiDefIconTextBlockBut(uiBlock *block, uiBlockCreateFunc func, void *arg, @@ -1572,6 +1700,11 @@ uiBut *uiDefKeyevtButS(uiBlock *block, short height, short *spoin, const char *tip); + +/** + * Short pointers hard-coded. + * \param modkeypoin: will be set to #KM_SHIFT, #KM_ALT, #KM_CTRL, #KM_OSKEY bits. + */ uiBut *uiDefHotKeyevtButS(uiBlock *block, int retval, const char *str, @@ -1583,6 +1716,10 @@ uiBut *uiDefHotKeyevtButS(uiBlock *block, const short *modkeypoin, const char *tip); +/** + * \param arg: A pointer to string/name, use #UI_but_func_search_set() below to make this work. + * here `a1` and `a2`, if set, control thumbnail preview rows/cols. + */ uiBut *uiDefSearchBut(uiBlock *block, void *arg, int retval, @@ -1595,6 +1732,10 @@ uiBut *uiDefSearchBut(uiBlock *block, float a1, float a2, const char *tip); +/** + * Same parameters as for #uiDefSearchBut, with additional operator type and properties, + * used by callback to call again the right op with the right options (properties values). + */ uiBut *uiDefSearchButO_ptr(uiBlock *block, struct wmOperatorType *ot, struct IDProperty *properties, @@ -1638,6 +1779,12 @@ uiBut *uiDefAutoButR(uiBlock *block, int y, int width, int height); +/** + * \a check_prop callback filters functions to avoid drawing certain properties, + * in cases where PROP_HIDDEN flag can't be used for a property. + * + * \param prop_activate_init: Property to activate on initial popup (#UI_BUT_ACTIVATE_ON_INIT). + */ eAutoPropButsReturn uiDefAutoButsRNA(uiLayout *layout, struct PointerRNA *ptr, bool (*check_prop)(struct PointerRNA *ptr, @@ -1648,7 +1795,19 @@ eAutoPropButsReturn uiDefAutoButsRNA(uiLayout *layout, eButLabelAlign label_align, const bool compact); -/* use inside searchfunc to add items */ +/** + * Public function exported for functions that use #UI_BTYPE_SEARCH_MENU. + * + * Use inside searchfunc to add items. + * + * \param items: Stores the items. + * \param name: Text to display for the item. + * \param poin: Opaque pointer (for use by the caller). + * \param iconid: The icon, #ICON_NONE for no icon. + * \param state: The buttons state flag, compatible with #uiBut.flag, + * typically #UI_BUT_DISABLED / #UI_BUT_INACTIVE. + * \return false if there is nothing to add. + */ bool UI_search_item_add(uiSearchItems *items, const char *name, void *poin, @@ -1656,6 +1815,21 @@ bool UI_search_item_add(uiSearchItems *items, int state, const uint8_t name_prefix_offset); +/** + * \note The item-pointer (referred to below) is a per search item user pointer + * passed to #UI_search_item_add (stored in #uiSearchItems.pointers). + * + * \param search_create_fn: Function to create the menu. + * \param search_update_fn: Function to refresh search content after the search text has changed. + * \param arg: user value. + * \param free_arg: Set to true if the argument is newly allocated memory for every redraw and + * should be freed when the button is destroyed. + * \param search_arg_free_fn: When non-null, use this function to free \a arg. + * \param search_exec_fn: Function that executes the action, gets \a arg as the first argument. + * The second argument as the active item-pointer + * \param active: When non-null, this item-pointer item will be visible and selected, + * otherwise the first item will be selected. + */ void UI_but_func_search_set(uiBut *but, uiButSearchCreateFn search_create_fn, uiButSearchUpdateFn search_update_fn, @@ -1666,21 +1840,28 @@ void UI_but_func_search_set(uiBut *but, void *active); void UI_but_func_search_set_context_menu(uiBut *but, uiButSearchContextMenuFn context_menu_fn); void UI_but_func_search_set_tooltip(uiBut *but, uiButSearchTooltipFn tooltip_fn); +/** + * \param search_sep_string: when not NULL, this string is used as a separator, + * showing the icon and highlighted text after the last instance of this string. + */ void UI_but_func_search_set_sep_string(uiBut *but, const char *search_sep_string); void UI_but_func_search_set_results_are_suggestions(uiBut *but, const bool value); -/* height in pixels, it's using hardcoded values still */ +/** + * Height in pixels, it's using hard-coded values still. + */ int UI_searchbox_size_y(void); int UI_searchbox_size_x(void); -/* check if a string is in an existing search box */ +/** + * Check if a string is in an existing search box. + */ int UI_search_items_find_index(uiSearchItems *items, const char *name); +/** + * Adds a hint to the button which draws right aligned, grayed out and never clipped. + */ void UI_but_hint_drawstr_set(uiBut *but, const char *string); -void UI_but_datasetrow_indentation_set(uiBut *but, int indentation); -void UI_but_datasetrow_component_set(uiBut *but, uint8_t geometry_component_type); -void UI_but_datasetrow_domain_set(uiBut *but, uint8_t attribute_domain); -uint8_t UI_but_datasetrow_component_get(uiBut *but); -uint8_t UI_but_datasetrow_domain_get(uiBut *but); + void UI_but_treerow_indentation_set(uiBut *but, int indentation); void UI_but_node_link_set(uiBut *but, struct bNodeSocket *socket, const float draw_color[4]); @@ -1708,7 +1889,14 @@ void UI_but_func_drawextra_set( void UI_but_func_menu_step_set(uiBut *but, uiMenuStepFunc func); void UI_but_func_tooltip_set(uiBut *but, uiButToolTipFunc func, void *arg, uiFreeArgFunc free_arg); +/** + * Recreate tool-tip (use to update dynamic tips) + */ void UI_but_tooltip_refresh(struct bContext *C, uiBut *but); +/** + * Removes tool-tip timer from active but + * (meaning tool-tip is disabled until it's re-enabled again). + */ void UI_but_tooltip_timer_remove(struct bContext *C, uiBut *but); bool UI_textbutton_activate_rna(const struct bContext *C, @@ -1717,6 +1905,10 @@ bool UI_textbutton_activate_rna(const struct bContext *C, const char *rna_prop_id); bool UI_textbutton_activate_but(const struct bContext *C, uiBut *but); +/** + * push a new event onto event queue to activate the given button + * (usually a text-field) upon entering a popup + */ void UI_but_focus_on_enter_event(struct wmWindow *win, uiBut *but); void UI_but_func_hold_set(uiBut *but, uiButHandleHoldFunc func, void *argN); @@ -1754,24 +1946,58 @@ int UI_autocomplete_end(AutoComplete *autocpl, char *autoname); void UI_panels_begin(const struct bContext *C, struct ARegion *region); void UI_panels_end(const struct bContext *C, struct ARegion *region, int *r_x, int *r_y); +/** + * Draw panels, selected (panels currently being dragged) on top. + */ void UI_panels_draw(const struct bContext *C, struct ARegion *region); struct Panel *UI_panel_find_by_type(struct ListBase *lb, const struct PanelType *pt); +/** + * \note \a panel should be return value from #UI_panel_find_by_type and can be NULL. + */ struct Panel *UI_panel_begin(struct ARegion *region, struct ListBase *lb, uiBlock *block, struct PanelType *pt, struct Panel *panel, bool *r_open); +/** + * Create the panel header button group, used to mark which buttons are part of + * panel headers for the panel search process that happens later. This Should be + * called before adding buttons for the panel's header layout. + */ void UI_panel_header_buttons_begin(struct Panel *panel); +/** + * Finish the button group for the panel header to avoid putting panel body buttons in it. + */ void UI_panel_header_buttons_end(struct Panel *panel); void UI_panel_end(struct Panel *panel, int width, int height); +/** + * Set a context for this entire panel and its current layout. This should be used whenever panel + * callbacks that are called outside of regular drawing might require context. Currently it affects + * the #PanelType.reorder callback only. + */ +void UI_panel_context_pointer_set(struct Panel *panel, const char *name, struct PointerRNA *ptr); + +/** + * Get the panel's expansion state, taking into account + * expansion set from property search if it applies. + */ bool UI_panel_is_closed(const struct Panel *panel); bool UI_panel_is_active(const struct Panel *panel); +/** + * For button layout next to label. + */ void UI_panel_label_offset(const struct uiBlock *block, int *r_x, int *r_y); +bool UI_panel_should_show_background(const struct ARegion *region, + const struct PanelType *panel_type); int UI_panel_size_y(const struct Panel *panel); bool UI_panel_is_dragging(const struct Panel *panel); +/** + * Find whether a panel or any of its sub-panels contain a property that matches the search filter, + * depending on the search process running in #UI_block_apply_search_filter earlier. + */ bool UI_panel_matches_search_filter(const struct Panel *panel); bool UI_panel_can_be_pinned(const struct Panel *panel); @@ -1784,6 +2010,9 @@ const char *UI_panel_category_active_get(struct ARegion *region, bool set_fallba void UI_panel_category_active_set(struct ARegion *region, const char *idname); void UI_panel_category_active_set_default(struct ARegion *region, const char *idname); void UI_panel_category_clear_all(struct ARegion *region); +/** + * Draw vertical tabs on the left side of the region, one tab per category. + */ void UI_panel_category_draw_all(struct ARegion *region, const char *category_id_active); /* Panel custom data. */ @@ -1793,17 +2022,40 @@ struct PointerRNA *UI_region_panel_custom_data_under_cursor(const struct bContex void UI_panel_custom_data_set(struct Panel *panel, struct PointerRNA *custom_data); /* Polyinstantiated panels for representing a list of data. */ +/** + * Called in situations where panels need to be added dynamically rather than + * having only one panel corresponding to each #PanelType. + */ struct Panel *UI_panel_add_instanced(const struct bContext *C, struct ARegion *region, struct ListBase *panels, const char *panel_idname, struct PointerRNA *custom_data); +/** + * Remove instanced panels from the region's panel list. + * + * \note Can be called with NULL \a C, but it should be avoided because + * handlers might not be removed. + */ void UI_panels_free_instanced(const struct bContext *C, struct ARegion *region); #define INSTANCED_PANEL_UNIQUE_STR_LEN 16 +/** + * Find a unique key to append to the #PanelType.idname for the lookup to the panel's #uiBlock. + * Needed for instanced panels, where there can be multiple with the same type and identifier. + */ void UI_list_panel_unique_str(struct Panel *panel, char *r_name); typedef void (*uiListPanelIDFromDataFunc)(void *data_link, char *r_idname); +/** + * Check if the instanced panels in the region's panels correspond to the list of data the panels + * represent. Returns false if the panels have been reordered or if the types from the list data + * don't match in any way. + * + * \param data: The list of data to check against the instanced panels. + * \param panel_idname_func: Function to find the #PanelType.idname for each item in the data list. + * For a readability and generality, this lookup happens separately for each type of panel list. + */ bool UI_panel_list_matches_data(struct ARegion *region, struct ListBase *data, uiListPanelIDFromDataFunc panel_idname_func); @@ -1828,6 +2080,7 @@ void UI_popup_handlers_remove_all(struct bContext *C, struct ListBase *handlers) * be used to reinitialize some internal state if user preferences change. */ void UI_init(void); +/* after reading userdef file */ void UI_init_userdef(void); void UI_reinit_font(void); void UI_exit(void); @@ -1943,8 +2196,18 @@ uiLayout *UI_block_layout(uiBlock *block, const struct uiStyle *style); void UI_block_layout_set_current(uiBlock *block, uiLayout *layout); void UI_block_layout_resolve(uiBlock *block, int *r_x, int *r_y); +/** + * Used for property search when the layout process needs to be cancelled in order to avoid + * computing the locations for buttons, but the layout items created while adding the buttons + * must still be freed. + */ void UI_block_layout_free(uiBlock *block); +/** + * Apply property search behavior, setting panel flags and deactivating buttons that don't match. + * + * \note Must not be run after #UI_block_layout_resolve. + */ bool UI_block_apply_search_filter(uiBlock *block, const char *search_filter); void UI_region_message_subscribe(struct ARegion *region, struct wmMsgBus *mbus); @@ -1955,11 +2218,23 @@ void uiLayoutSetFunc(uiLayout *layout, uiMenuHandleFunc handlefunc, void *argv); void uiLayoutSetContextPointer(uiLayout *layout, const char *name, struct PointerRNA *ptr); struct bContextStore *uiLayoutGetContextStore(uiLayout *layout); void uiLayoutContextCopy(uiLayout *layout, struct bContextStore *context); +/** + * This is a bit of a hack but best keep it in one place at least. + */ struct wmOperatorType *UI_but_operatortype_get_from_enum_menu(struct uiBut *but, struct PropertyRNA **r_prop); +/** + * This is a bit of a hack but best keep it in one place at least. + */ struct MenuType *UI_but_menutype_get(uiBut *but); +/** + * This is a bit of a hack but best keep it in one place at least. + */ struct PanelType *UI_but_paneltype_get(uiBut *but); void UI_menutype_draw(struct bContext *C, struct MenuType *mt, struct uiLayout *layout); +/** + * Used for popup panels only. + */ void UI_paneltype_draw(struct bContext *C, struct PanelType *pt, struct uiLayout *layout); /* Only for convenience. */ @@ -2001,10 +2276,20 @@ eUIEmbossType uiLayoutGetEmboss(uiLayout *layout); bool uiLayoutGetPropSep(uiLayout *layout); bool uiLayoutGetPropDecorate(uiLayout *layout); -/* layout specifiers */ +/* Layout create functions. */ + uiLayout *uiLayoutRow(uiLayout *layout, bool align); +/** + * See #uiLayoutColumnWithHeading(). + */ uiLayout *uiLayoutRowWithHeading(uiLayout *layout, bool align, const char *heading); uiLayout *uiLayoutColumn(uiLayout *layout, bool align); +/** + * Variant of #uiLayoutColumn() that sets a heading label for the layout if the first item is + * added through #uiItemFullR(). If split layout is used and the item has no string to add to the + * first split-column, the heading is added there instead. Otherwise the heading inserted with a + * new row. + */ uiLayout *uiLayoutColumnWithHeading(uiLayout *layout, bool align, const char *heading); uiLayout *uiLayoutColumnFlow(uiLayout *layout, int number, bool align); uiLayout *uiLayoutGridFlow(uiLayout *layout, @@ -2056,6 +2341,9 @@ void uiTemplateIDPreview(uiLayout *layout, int cols, int filter, const bool hide_buttons); +/** + * Version of #uiTemplateID using tabs. + */ void uiTemplateIDTabs(uiLayout *layout, struct bContext *C, struct PointerRNA *ptr, @@ -2063,11 +2351,23 @@ void uiTemplateIDTabs(uiLayout *layout, const char *newop, const char *menu, int filter); +/** + * This is for selecting the type of ID-block to use, + * and then from the relevant type choosing the block to use. + * + * \param propname: property identifier for property that ID-pointer gets stored to. + * \param proptypename: property identifier for property + * used to determine the type of ID-pointer that can be used. + */ void uiTemplateAnyID(uiLayout *layout, struct PointerRNA *ptr, const char *propname, const char *proptypename, const char *text); +/** + * Search menu to pick an item from a collection. + * A version of uiTemplateID that works for non-ID types. + */ void uiTemplateSearch(uiLayout *layout, struct bContext *C, struct PointerRNA *ptr, @@ -2086,6 +2386,13 @@ void uiTemplateSearchPreview(uiLayout *layout, const char *unlinkop, const int rows, const int cols); +/** + * This is creating/editing RNA-Paths + * + * - ptr: struct which holds the path property + * - propname: property identifier for property that path gets stored to + * - root_ptr: struct that path gets built from + */ void uiTemplatePathBuilder(uiLayout *layout, struct PointerRNA *ptr, const char *propname, @@ -2093,7 +2400,13 @@ void uiTemplatePathBuilder(uiLayout *layout, const char *text); void uiTemplateModifiers(uiLayout *layout, struct bContext *C); void uiTemplateGpencilModifiers(uiLayout *layout, struct bContext *C); +/** + * Check if the shader effect panels don't match the data and rebuild the panels if so. + */ void uiTemplateShaderFx(uiLayout *layout, struct bContext *C); +/** + * Check if the constraint panels don't match the data and rebuild the panels if so. + */ void uiTemplateConstraints(uiLayout *layout, struct bContext *C, bool use_bone_constraints); uiLayout *uiTemplateGpencilModifier(uiLayout *layout, struct bContext *C, struct PointerRNA *ptr); @@ -2120,7 +2433,13 @@ void uiTemplateColorRamp(uiLayout *layout, struct PointerRNA *ptr, const char *propname, bool expand); +/** + * \param icon_scale: Scale of the icon, 1x == button height. + */ void uiTemplateIcon(uiLayout *layout, int icon_value, float icon_scale); +/** + * \param icon_scale: Scale of the icon, 1x == button height. + */ void uiTemplateIconView(uiLayout *layout, struct PointerRNA *ptr, const char *propname, @@ -2138,7 +2457,14 @@ void uiTemplateCurveMapping(uiLayout *layout, bool brush, bool neg_slope, bool tone); +/** + * Template for a path creation widget intended for custom bevel profiles. + * This section is quite similar to #uiTemplateCurveMapping, but with reduced complexity. + */ void uiTemplateCurveProfile(uiLayout *layout, struct PointerRNA *ptr, const char *propname); +/** + * This template now follows User Preference for type - name is not correct anymore. + */ void uiTemplateColorPicker(uiLayout *layout, struct PointerRNA *ptr, const char *propname, @@ -2154,6 +2480,10 @@ void uiTemplateCryptoPicker(uiLayout *layout, struct PointerRNA *ptr, const char *propname, int icon); +/** + * \todo for now, grouping of layers is determined by dividing up the length of + * the array of layer bitflags + */ void uiTemplateLayers(uiLayout *layout, struct PointerRNA *ptr, const char *propname, @@ -2188,6 +2518,11 @@ void uiTemplateOperatorSearch(uiLayout *layout); void UI_but_func_menu_search(uiBut *but); void uiTemplateMenuSearch(uiLayout *layout); +/** + * Draw Operator property buttons for redoing execution with different settings. + * This function does not initialize the layout, + * functions can be called on the layout before and after. + */ void uiTemplateOperatorPropertyButs(const struct bContext *C, uiLayout *layout, struct wmOperator *op, @@ -2273,6 +2608,9 @@ void uiTemplateNodeView(uiLayout *layout, struct bNode *node, struct bNodeSocket *input); void uiTemplateTextureUser(uiLayout *layout, struct bContext *C); +/** + * Button to quickly show texture in Properties Editor texture tab. + */ void uiTemplateTextureShow(uiLayout *layout, const struct bContext *C, struct PointerRNA *ptr, @@ -2329,9 +2667,15 @@ void uiTemplateAssetView(struct uiLayout *layout, const char *drag_opname, struct PointerRNA *r_drag_op_properties); +/** + * \return: A RNA pointer for the operator properties. + */ struct PointerRNA *UI_list_custom_activate_operator_set(struct uiList *ui_list, const char *opname, bool create_properties); +/** + * \return: A RNA pointer for the operator properties. + */ struct PointerRNA *UI_list_custom_drag_operator_set(struct uiList *ui_list, const char *opname, bool create_properties); @@ -2350,6 +2694,9 @@ void uiItemEnumO(uiLayout *layout, int icon, const char *propname, int value); +/** + * For use in cases where we have. + */ void uiItemEnumO_value(uiLayout *layout, const char *name, int icon, @@ -2428,6 +2775,9 @@ void uiItemFullR(uiLayout *layout, int flag, const char *name, int icon); +/** + * Use a wrapper function since re-implementing all the logic in this function would be messy. + */ void uiItemFullR_with_popover(uiLayout *layout, struct PointerRNA *ptr, struct PropertyRNA *prop, @@ -2491,6 +2841,11 @@ void uiItemsFullEnumO(uiLayout *layout, struct IDProperty *properties, wmOperatorCallContext context, int flag); +/** + * Create UI items for enum items in \a item_array. + * + * A version of #uiItemsFullEnumO that takes pre-calculated item array. + */ void uiItemsFullEnumO_items(uiLayout *layout, struct wmOperatorType *ot, struct PointerRNA ptr, @@ -2507,33 +2862,59 @@ typedef struct uiPropertySplitWrapper { uiLayout *decorate_column; } uiPropertySplitWrapper; +/** + * Normally, we handle the split layout in #uiItemFullR(), but there are other cases where the + * logic is needed. Ideally, #uiItemFullR() could just call this, but it currently has too many + * special needs. + */ uiPropertySplitWrapper uiItemPropertySplitWrapperCreate(uiLayout *parent_layout); void uiItemL(uiLayout *layout, const char *name, int icon); /* label */ void uiItemL_ex( uiLayout *layout, const char *name, int icon, const bool highlight, const bool redalert); +/** + * Helper to add a label and creates a property split layout if needed. + */ uiLayout *uiItemL_respect_property_split(uiLayout *layout, const char *text, int icon); -/* label icon for dragging */ +/** + * Label icon for dragging. + */ void uiItemLDrag(uiLayout *layout, struct PointerRNA *ptr, const char *name, int icon); -/* menu */ +/** + * Menu. + */ void uiItemM_ptr(uiLayout *layout, struct MenuType *mt, const char *name, int icon); void uiItemM(uiLayout *layout, const char *menuname, const char *name, int icon); -/* menu contents */ +/** + * Menu contents. + */ void uiItemMContents(uiLayout *layout, const char *menuname); -/* Decorators */ + +/* Decorators. */ + +/** + * Insert a decorator item for a button with the same property as \a prop. + * To force inserting a blank dummy element, NULL can be passed for \a ptr and \a prop. + */ void uiItemDecoratorR_prop(uiLayout *layout, struct PointerRNA *ptr, struct PropertyRNA *prop, int index); +/** + * Insert a decorator item for a button with the same property as \a prop. + * To force inserting a blank dummy element, NULL can be passed for \a ptr and \a propname. + */ void uiItemDecoratorR(uiLayout *layout, struct PointerRNA *ptr, const char *propname, int index); -/* value */ +/** Value item */ void uiItemV(uiLayout *layout, const char *name, int icon, int argval); -/* separator */ +/** Separator item */ void uiItemS(uiLayout *layout); +/** Separator item */ void uiItemS_ex(uiLayout *layout, float factor); -/* Special separator. */ +/** Flexible spacing. */ void uiItemSpacer(uiLayout *layout); +/* popover */ void uiItemPopoverPanel_ptr( uiLayout *layout, const struct bContext *C, struct PanelType *pt, const char *name, int icon); void uiItemPopoverPanel(uiLayout *layout, @@ -2548,7 +2929,13 @@ void uiItemPopoverPanelFromGroup(uiLayout *layout, const char *context, const char *category); +/** + * Level items. + */ void uiItemMenuF(uiLayout *layout, const char *name, int icon, uiMenuCreateFunc func, void *arg); +/** + * Version of #uiItemMenuF that free's `argN`. + */ void uiItemMenuFN(uiLayout *layout, const char *name, int icon, uiMenuCreateFunc func, void *argN); void uiItemMenuEnumFullO_ptr(uiLayout *layout, struct bContext *C, @@ -2586,9 +2973,15 @@ void uiItemTabsEnumR_prop(uiLayout *layout, bool icon_only); /* Only for testing, inspecting layouts. */ +/** + * Evaluate layout items as a Python dictionary. + */ const char *UI_layout_introspect(uiLayout *layout); -/* Helper to add a big icon and create a split layout for alert boxes. */ +/** + * Helper to add a big icon and create a split layout for alert popups. + * Returns the layout to place further items into the alert box. + */ uiLayout *uiItemsAlertBox(uiBlock *block, const int size, const eAlertIcon icon); /* UI Operators */ @@ -2598,6 +2991,9 @@ typedef struct uiDragColorHandle { } uiDragColorHandle; void ED_operatortypes_ui(void); +/** + * \brief User Interface Keymap + */ void ED_keymap_ui(struct wmKeyConfig *keyconf); void ED_dropboxes_ui(void); void ED_uilisttypes_ui(void); @@ -2611,10 +3007,28 @@ bool UI_context_copy_to_selected_list(struct bContext *C, struct ListBase *r_lb, bool *r_use_path_from_id, char **r_path); +bool UI_context_copy_to_selected_check(struct PointerRNA *ptr, + struct PointerRNA *ptr_link, + struct PropertyRNA *prop, + const char *path, + bool use_path_from_id, + struct PointerRNA *r_ptr, + struct PropertyRNA **r_prop); /* Helpers for Operators */ uiBut *UI_context_active_but_get(const struct bContext *C); +/** + * Version of #UI_context_active_get() that uses the result of #CTX_wm_menu() + * if set. Does not traverse into parent menus, which may be wanted in some + * cases. + */ uiBut *UI_context_active_but_get_respect_menu(const struct bContext *C); +/** + * Version of #UI_context_active_but_get that also returns RNA property info. + * Helper function for insert keyframe, reset to default, etc operators. + * + * \return active button, NULL if none found or if it doesn't contain valid RNA data. + */ uiBut *UI_context_active_but_prop_get(const struct bContext *C, struct PointerRNA *r_ptr, struct PropertyRNA **r_prop, @@ -2623,12 +3037,18 @@ void UI_context_active_but_prop_handle(struct bContext *C); void UI_context_active_but_clear(struct bContext *C, struct wmWindow *win, struct ARegion *region); struct wmOperator *UI_context_active_operator_get(const struct bContext *C); +/** + * Helper function for insert keyframe, reset to default, etc operators. + */ void UI_context_update_anim_flag(const struct bContext *C); void UI_context_active_but_prop_get_filebrowser(const struct bContext *C, struct PointerRNA *r_ptr, struct PropertyRNA **r_prop, bool *r_is_undo, bool *r_is_userdef); +/** + * For new/open operators. + */ void UI_context_active_but_prop_get_templateID(struct bContext *C, struct PointerRNA *r_ptr, struct PropertyRNA **r_prop); @@ -2639,6 +3059,9 @@ uiBut *UI_region_but_find_rect_over(const struct ARegion *region, const struct r uiBlock *UI_region_block_find_mouse_over(const struct ARegion *region, const int xy[2], bool only_clip); +/** + * Try to find a search-box region opened from a button in \a button_region. + */ struct ARegion *UI_region_searchbox_region_get(const struct ARegion *button_region); /* uiFontStyle.align */ @@ -2669,12 +3092,24 @@ void UI_fontstyle_draw(const struct uiFontStyle *fs, const char *str, const uchar col[4], const struct uiFontStyleDraw_Params *fs_params); +/** + * Drawn same as above, but at 90 degree angle. + */ void UI_fontstyle_draw_rotated(const struct uiFontStyle *fs, const struct rcti *rect, const char *str, const uchar col[4]); +/** + * Similar to #UI_fontstyle_draw + * but ignore alignment, shadow & no clipping rect. + * + * For drawing on-screen labels. + */ void UI_fontstyle_draw_simple( const struct uiFontStyle *fs, float x, float y, const char *str, const uchar col[4]); +/** + * Same as #UI_fontstyle_draw but draw a colored backdrop. + */ void UI_fontstyle_draw_simple_backdrop(const struct uiFontStyle *fs, float x, float y, @@ -2684,15 +3119,30 @@ void UI_fontstyle_draw_simple_backdrop(const struct uiFontStyle *fs, int UI_fontstyle_string_width(const struct uiFontStyle *fs, const char *str) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); +/** + * Return the width of `str` with the spacing & kerning of `fs` with `aspect` + * (representing #uiBlock.aspect) applied. + * + * When calculating text width, the UI layout logic calculate widths without scale, + * only applying scale when drawing. This causes problems for fonts since kerning at + * smaller sizes often makes them wider than a scaled down version of the larger text. + * Resolve this by calculating the text at the on-screen size, + * returning the result scaled back to 1:1. See T92361. + */ int UI_fontstyle_string_width_with_block_aspect(const struct uiFontStyle *fs, const char *str, const float aspect) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1, 2); int UI_fontstyle_height_max(const struct uiFontStyle *fs); +/** + * Triangle 'icon' for panel header and other cases. + */ void UI_draw_icon_tri(float x, float y, char dir, const float[4]); -const struct uiStyle *UI_style_get(void); /* use for fonts etc */ +/* XXX: read a style configure */ +const struct uiStyle *UI_style_get(void); /* use for fonts etc */ +/* for drawing, scaled with DPI setting */ const struct uiStyle *UI_style_get_dpi(void); /* DPI scaled settings for drawing */ /* linker workaround ack! */ @@ -2701,25 +3151,56 @@ void UI_template_fix_linking(void); /* UI_OT_editsource helpers */ bool UI_editsource_enable_check(void); void UI_editsource_active_but_test(uiBut *but); +/** + * Remove the editsource data for \a old_but and reinsert it for \a new_but. Use when the button + * was reallocated, e.g. to have a new type (#ui_but_change_type()). + */ void UI_editsource_but_replace(const uiBut *old_but, uiBut *new_but); +/** + * Adjust the view so the rectangle of \a but is in view, with some extra margin. + * + * It's important that this is only executed after buttons received their final #uiBut.rect. E.g. + * #UI_panels_end() modifies them, so if that is executed, this function must not be called before + * it. + * + * \param region: The region the button is placed in. Make sure this is actually the one the button + * is placed in, not just the context region. + */ void UI_but_ensure_in_view(const struct bContext *C, struct ARegion *region, const uiBut *but); /* UI_butstore_ helpers */ typedef struct uiButStore uiButStore; typedef struct uiButStoreElem uiButStoreElem; +/** + * Create a new button store, the caller must manage and run #UI_butstore_free + */ uiButStore *UI_butstore_create(uiBlock *block); +/** + * NULL all pointers, don't free since the owner needs to be able to inspect. + */ void UI_butstore_clear(uiBlock *block); +/** + * Map freed buttons from the old block and update pointers. + */ void UI_butstore_update(uiBlock *block); void UI_butstore_free(uiBlock *block, uiButStore *bs); bool UI_butstore_is_valid(uiButStore *bs); bool UI_butstore_is_registered(uiBlock *block, uiBut *but); void UI_butstore_register(uiButStore *bs_handle, uiBut **but_p); +/** + * Update the pointer for a registered button. + */ bool UI_butstore_register_update(uiBlock *block, uiBut *but_dst, const uiBut *but_src); void UI_butstore_unregister(uiButStore *bs_handle, uiBut **but_p); /* ui_interface_region_tooltip.c */ + +/** + * \param is_label: When true, show a small tip that only shows the name, otherwise show the full + * tooltip. + */ struct ARegion *UI_tooltip_create_from_button(struct bContext *C, struct ARegion *butregion, uiBut *but, @@ -2741,6 +3222,13 @@ typedef struct { char hint[UI_MAX_DRAW_STR]; } uiSearchItemTooltipData; +/** + * Create a tooltip from search-item tooltip data \a item_tooltip data. + * To be called from a callback set with #UI_but_func_search_set_tooltip(). + * + * \param item_rect: Rectangle of the search item in search region space (#ui_searchbox_butrect()) + * which is passed to the tooltip callback. + */ struct ARegion *UI_tooltip_create_from_search_item_generic( struct bContext *C, const struct ARegion *searchbox_region, @@ -2759,6 +3247,10 @@ struct ARegion *UI_tooltip_create_from_search_item_generic( /* Typical UI text */ #define UI_FSTYLE_WIDGET (const uiFontStyle *)&(UI_style_get()->widget) +/** + * Returns the best "UI" precision for given floating value, + * so that e.g. 10.000001 rather gets drawn as '10'... + */ int UI_calc_float_precision(int prec, double value); /* widget batched drawing */ @@ -2767,6 +3259,12 @@ void UI_widgetbase_draw_cache_flush(void); void UI_widgetbase_draw_cache_end(void); /* Use for resetting the theme. */ +/** + * Initialize default theme. + * + * \note When you add new colors, created & saved themes need initialized + * use function below, #init_userdef_do_versions. + */ void UI_theme_init_default(void); void UI_style_init_default(void); @@ -2780,12 +3278,28 @@ void UI_interface_tag_script_reload(void); bool UI_tree_view_item_is_active(const uiTreeViewItemHandle *item); bool UI_tree_view_item_matches(const uiTreeViewItemHandle *a, const uiTreeViewItemHandle *b); +/** + * Attempt to start dragging the tree-item \a item_. This will not work if the tree item doesn't + * support dragging, i.e. it won't create a drag-controller upon request. + * \return True if dragging started successfully, otherwise false. + */ bool UI_tree_view_item_drag_start(struct bContext *C, uiTreeViewItemHandle *item_); bool UI_tree_view_item_can_drop(const uiTreeViewItemHandle *item_, const struct wmDrag *drag, const char **r_disabled_hint); char *UI_tree_view_item_drop_tooltip(const uiTreeViewItemHandle *item, const struct wmDrag *drag); -bool UI_tree_view_item_drop_handle(uiTreeViewItemHandle *item_, const struct ListBase *drags); +/** + * Let a tree-view item handle a drop event. + * \return True if the drop was handled by the tree-view item. + */ +bool UI_tree_view_item_drop_handle(struct bContext *C, + const uiTreeViewItemHandle *item_, + const struct ListBase *drags); +/** + * Can \a item_handle be renamed right now? Not that this isn't just a mere wrapper around + * #AbstractTreeViewItem::can_rename(). This also checks if there is another item being renamed, + * and returns false if so. + */ bool UI_tree_view_item_can_rename(const uiTreeViewItemHandle *item_handle); void UI_tree_view_item_begin_rename(uiTreeViewItemHandle *item_handle); @@ -2793,6 +3307,9 @@ void UI_tree_view_item_context_menu_build(struct bContext *C, const uiTreeViewItemHandle *item, uiLayout *column); +/** + * \param xy: Coordinate to find a tree-row item at, in window space. + */ uiTreeViewItemHandle *UI_block_tree_view_find_item_at(const struct ARegion *region, const int xy[2]) ATTR_NONNULL(1, 2); uiTreeViewItemHandle *UI_block_tree_view_find_active_item(const struct ARegion *region); diff --git a/source/blender/editors/include/UI_interface.hh b/source/blender/editors/include/UI_interface.hh index b14ee6c4a59..d18ec009108 100644 --- a/source/blender/editors/include/UI_interface.hh +++ b/source/blender/editors/include/UI_interface.hh @@ -66,6 +66,9 @@ void attribute_search_add_items( } // namespace blender::ui +/** + * Override this for all available tree types. + */ blender::ui::AbstractTreeView *UI_block_add_view( uiBlock &block, blender::StringRef idname, diff --git a/source/blender/editors/include/UI_interface_icons.h b/source/blender/editors/include/UI_interface_icons.h index 37cf7229ffb..242b8504ae1 100644 --- a/source/blender/editors/include/UI_interface_icons.h +++ b/source/blender/editors/include/UI_interface_icons.h @@ -64,23 +64,39 @@ typedef enum eAlertIcon { struct ImBuf *UI_icon_alert_imbuf_get(eAlertIcon icon); -/* +/** * Resizable Icons for Blender */ void UI_icons_init(void); +/** + * Reload the textures for internal icons. + * This function will release the previous textures. + */ void UI_icons_reload_internal_textures(void); +/** + * NOTE: returns unscaled by DPI. + */ int UI_icon_get_width(int icon_id); int UI_icon_get_height(int icon_id); bool UI_icon_get_theme_color(int icon_id, unsigned char color[4]); +/** + * Note that if an ID doesn't support jobs for preview creation, \a use_job will be ignored. + */ void UI_icon_render_id(const struct bContext *C, struct Scene *scene, struct ID *id, const enum eIconSizes size, const bool use_job); +/** + * Render size for preview images and icons + */ int UI_icon_preview_to_render_size(enum eIconSizes size); +/** + * Draws icon with dpi scale factor. + */ void UI_icon_draw(float x, float y, int icon_id); void UI_icon_draw_alpha(float x, float y, int icon_id, float alpha); void UI_icon_draw_preview(float x, float y, int icon_id, float aspect, float alpha, int size); diff --git a/source/blender/editors/include/UI_resources.h b/source/blender/editors/include/UI_resources.h index 61da496d344..98e141c65b5 100644 --- a/source/blender/editors/include/UI_resources.h +++ b/source/blender/editors/include/UI_resources.h @@ -351,7 +351,7 @@ typedef enum ThemeColorID { TH_VERTEX_BEVEL, } ThemeColorID; -/* specific defines per space should have higher define values */ +/* Specific defines per space should have higher define values. */ struct bTheme; @@ -362,93 +362,144 @@ struct bThemeState { /* THE CODERS API FOR THEMES: */ -/* returns one value, not scaled */ +/** + * Get individual values, not scaled. + */ float UI_GetThemeValuef(int colorid); +/** + * Get individual values, not scaled. + */ int UI_GetThemeValue(int colorid); +/* Versions of #UI_GetThemeValue & #UI_GetThemeValuef, which take a space-type */ + float UI_GetThemeValueTypef(int colorid, int spacetype); int UI_GetThemeValueType(int colorid, int spacetype); -/* get three color values, scaled to 0.0-1.0 range */ +/** + * Get three color values, scaled to 0.0-1.0 range. + */ void UI_GetThemeColor3fv(int colorid, float col[3]); void UI_GetThemeColorBlend3ubv(int colorid1, int colorid2, float fac, unsigned char col[3]); void UI_GetThemeColorBlend3f(int colorid1, int colorid2, float fac, float r_col[3]); void UI_GetThemeColorBlend4f(int colorid1, int colorid2, float fac, float r_col[4]); -/* get the color, range 0.0-1.0, complete with shading offset */ +/** + * Get the color, range 0.0-1.0, complete with shading offset. + */ void UI_GetThemeColorShade3fv(int colorid, int offset, float col[3]); void UI_GetThemeColorShade3ubv(int colorid, int offset, unsigned char col[3]); void UI_GetThemeColorShade4ubv(int colorid, int offset, unsigned char col[4]); -/* get three color values, range 0-255, - * complete with shading offset for the RGB components and blending. */ +/** + * Get three color values, range 0-255, + * complete with shading offset for the RGB components and blending. + */ void UI_GetThemeColorBlendShade3ubv( int colorid1, int colorid2, float fac, int offset, unsigned char col[3]); -/* get four color values, scaled to 0.0-1.0 range */ +/** + * Get four color values, scaled to 0.0-1.0 range. + */ void UI_GetThemeColor4fv(int colorid, float col[4]); -/* get four color values from specified space type, scaled to 0.0-1.0 range */ +/** + * Get four color values from specified space type, scaled to 0.0-1.0 range. + */ void UI_GetThemeColorType4fv(int colorid, int spacetype, float col[4]); -/* get four color values, range 0.0-1.0, complete with shading offset for the RGB components */ +/** + * Get four color values, range 0.0-1.0, complete with shading offset for the RGB components. + */ void UI_GetThemeColorShade4fv(int colorid, int offset, float col[4]); void UI_GetThemeColorShadeAlpha4fv(int colorid, int coloffset, int alphaoffset, float col[4]); -/* get four color values ranged between 0 and 255; includes the alpha channel */ +/** + * Get four color values ranged between 0 and 255; includes the alpha channel. + */ void UI_GetThemeColorShadeAlpha4ubv(int colorid, int coloffset, int alphaoffset, unsigned char col[4]); -/* get four color values, range 0.0-1.0, - * complete with shading offset for the RGB components and blending. */ +/** + * Get four color values, range 0.0-1.0, + * complete with shading offset for the RGB components and blending. + */ void UI_GetThemeColorBlendShade3fv( int colorid1, int colorid2, float fac, int offset, float col[3]); void UI_GetThemeColorBlendShade4fv( int colorid1, int colorid2, float fac, int offset, float col[4]); -/* get the 3 or 4 byte values */ +/** + * Get the 3 or 4 byte values. + */ void UI_GetThemeColor3ubv(int colorid, unsigned char col[3]); +/** + * Get the color, in char pointer. + */ void UI_GetThemeColor4ubv(int colorid, unsigned char col[4]); -/* get a theme color from specified space type */ +/** + * Get a theme color from specified space type. + */ void UI_GetThemeColorType3fv(int colorid, int spacetype, float col[3]); void UI_GetThemeColorType3ubv(int colorid, int spacetype, unsigned char col[3]); void UI_GetThemeColorType4ubv(int colorid, int spacetype, unsigned char col[4]); -/* get theme color for coloring monochrome icons */ +/** + * Get theme color for coloring monochrome icons. + */ bool UI_GetIconThemeColor4ubv(int colorid, unsigned char col[4]); -/* shade a 3 byte color (same as UI_GetColorPtrBlendShade3ubv with 0.0 factor) */ +/** + * Shade a 3 byte color (same as UI_GetColorPtrBlendShade3ubv with 0.0 factor). + */ void UI_GetColorPtrShade3ubv(const unsigned char cp1[3], unsigned char col[3], int offset); -/* get a 3 byte color, blended and shaded between two other char color pointers */ +/** + * Get a 3 byte color, blended and shaded between two other char color pointers. + */ void UI_GetColorPtrBlendShade3ubv(const unsigned char cp1[3], const unsigned char cp2[3], unsigned char col[3], float fac, int offset); -/* sets the font color - * (for anything fancy use UI_GetThemeColor[Fancy] then BLF_color) */ +/** + * Sets the font color + * (for anything fancy use UI_GetThemeColor[Fancy] then BLF_color). + */ void UI_FontThemeColor(int fontid, int colorid); -/* Clear the frame-buffer using the input colorid. */ +/** + * Clear the frame-buffer using the input colorid. + */ void UI_ThemeClearColor(int colorid); -/* internal (blender) usage only, for init and set active */ +/** + * Internal (blender) usage only, for init and set active. + */ void UI_SetTheme(int spacetype, int regionid); -/* get current theme */ +/** + * Get current theme. + */ struct bTheme *UI_GetTheme(void); +/** + * For the rare case we need to temp swap in a different theme (off-screen render). + */ void UI_Theme_Store(struct bThemeState *theme_state); void UI_Theme_Restore(struct bThemeState *theme_state); -/* return shadow width outside menus and popups */ +/** + * Return shadow width outside menus and popups. + */ int UI_ThemeMenuShadowWidth(void); -/* only for buttons in theme editor! */ +/** + * Only for buttons in theme editor! + */ const unsigned char *UI_ThemeGetColorPtr(struct bTheme *btheme, int spacetype, int colorid); void UI_make_axis_color(const unsigned char src_col[3], unsigned char dst_col[3], const char axis); diff --git a/source/blender/editors/include/UI_tree_view.hh b/source/blender/editors/include/UI_tree_view.hh index 0d18eedeac9..8208f8daf5d 100644 --- a/source/blender/editors/include/UI_tree_view.hh +++ b/source/blender/editors/include/UI_tree_view.hh @@ -17,8 +17,8 @@ /** \file * \ingroup editorui * - * API for simple creation of tree UIs supporting advanced features. - * https://wiki.blender.org/wiki/Source/Interface/Views + * API for simple creation of tree UIs supporting typically needed features. + * https://wiki.blender.org/wiki/Source/Interface/Views/Tree_Views */ #pragma once @@ -36,7 +36,6 @@ #include "UI_resources.h" struct bContext; -struct PointerRNA; struct uiBlock; struct uiBut; struct uiButTreeRow; @@ -53,14 +52,17 @@ class AbstractTreeViewItemDragController; /* ---------------------------------------------------------------------- */ /** \name Tree-View Item Container + * + * Base class for tree-view and tree-view items, so both can contain children. * \{ */ /** - * Helper base class to expose common child-item data and functionality to both #AbstractTreeView - * and #AbstractTreeViewItem. + * Both the tree-view (as the root of the tree) and the items can have children. This is the base + * class for both, to store and manage child items. Children are owned by their parent container + * (tree-view or item). * - * That means this type can be used whenever either a #AbstractTreeView or a - * #AbstractTreeViewItem is needed. + * That means this type can be used whenever either an #AbstractTreeView or an + * #AbstractTreeViewItem is needed, but the #TreeViewOrItem alias is a better name to use then. */ class TreeViewItemContainer { friend class AbstractTreeView; @@ -112,37 +114,10 @@ class TreeViewItemContainer { ENUM_OPERATORS(TreeViewItemContainer::IterOptions, TreeViewItemContainer::IterOptions::SkipCollapsed); -/** \} */ - -/* ---------------------------------------------------------------------- */ -/** \name Tree-View Builders - * \{ */ - -class TreeViewBuilder { - uiBlock &block_; - - public: - TreeViewBuilder(uiBlock &block); - - void build_tree_view(AbstractTreeView &tree_view); -}; - -class TreeViewLayoutBuilder { - uiBlock &block_; - - friend TreeViewBuilder; - - public: - void build_row(AbstractTreeViewItem &item) const; - uiBlock &block() const; - uiLayout *current_layout() const; - - private: - /* Created through #TreeViewBuilder. */ - TreeViewLayoutBuilder(uiBlock &block); - - static void polish_layout(const uiBlock &block); -}; +/** The container class is the base for both the tree-view and the items. This alias gives it a + * clearer name for handles that accept both. Use whenever something wants to act on child-items, + * irrespective of if they are stored at root level or as children of some other item. */ +using TreeViewOrItem = TreeViewItemContainer; /** \} */ @@ -151,8 +126,8 @@ class TreeViewLayoutBuilder { * \{ */ class AbstractTreeView : public TreeViewItemContainer { - friend AbstractTreeViewItem; - friend TreeViewBuilder; + friend class AbstractTreeViewItem; + friend class TreeViewBuilder; /** * Only one item can be renamed at a time. So the tree is informed about the renaming state to @@ -169,15 +144,16 @@ class AbstractTreeView : public TreeViewItemContainer { /** Only one item can be renamed at a time. */ bool is_renaming() const; + + protected: + virtual void build_tree() = 0; + /** * Check if the tree is fully (re-)constructed. That means, both #build_tree() and * #update_from_old() have finished. */ bool is_reconstructed() const; - protected: - virtual void build_tree() = 0; - private: /** * Match the tree-view against an earlier version of itself (if any) and copy the old UI state @@ -185,10 +161,10 @@ class AbstractTreeView : public TreeViewItemContainer { * #AbstractTreeViewItem.update_from_old(). */ void update_from_old(uiBlock &new_block); - static void update_children_from_old_recursive(const TreeViewItemContainer &new_items, - const TreeViewItemContainer &old_items); + static void update_children_from_old_recursive(const TreeViewOrItem &new_items, + const TreeViewOrItem &old_items); static AbstractTreeViewItem *find_matching_child(const AbstractTreeViewItem &lookup_item, - const TreeViewItemContainer &items); + const TreeViewOrItem &items); /** * Items may want to do additional work when state changes. But these state changes can only be @@ -196,7 +172,6 @@ class AbstractTreeView : public TreeViewItemContainer { * the actual state changes are done in a delayed manner through this function. */ void change_state_delayed(); - void build_layout_from_tree(const TreeViewLayoutBuilder &builder); }; /** \} */ @@ -215,21 +190,18 @@ class AbstractTreeView : public TreeViewItemContainer { class AbstractTreeViewItem : public TreeViewItemContainer { friend class AbstractTreeView; friend class TreeViewLayoutBuilder; - - public: - using IsActiveFn = std::function<bool()>; + /* Higher-level API. */ + friend class TreeViewItemAPIWrapper; private: bool is_open_ = false; bool is_active_ = false; bool is_renaming_ = false; - IsActiveFn is_active_fn_; - protected: - /** This label is used for identifying an item (together with its parent's labels). */ + /** This label is used for identifying an item within its parent. */ std::string label_{}; - /** Every item gets a button of type during the layout building #UI_BTYPE_TREEROW. */ + /** Every visible item gets a button of type #UI_BTYPE_TREEROW during the layout building. */ uiButTreeRow *tree_row_but_ = nullptr; public: @@ -238,33 +210,59 @@ class AbstractTreeViewItem : public TreeViewItemContainer { virtual void build_row(uiLayout &row) = 0; virtual void build_context_menu(bContext &C, uiLayout &column) const; + AbstractTreeView &get_tree_view() const; + + void begin_renaming(); + void toggle_collapsed(); + void set_collapsed(bool collapsed); + /** + * Requires the tree to have completed reconstruction, see #is_reconstructed(). Otherwise we + * can't be sure about the item state. + */ + bool is_collapsed() const; + /** + * Requires the tree to have completed reconstruction, see #is_reconstructed(). Otherwise we + * can't be sure about the item state. + */ + bool is_active() const; + + protected: + /** + * Called when the items state changes from inactive to active. + */ virtual void on_activate(); /** - * Set a custom callback to check if this item should be active. There's a version without - * arguments for checking if the item is currently in an active state. + * If the result is not empty, it controls whether the item should be active or not, + * usually depending on the data that the view represents. */ - virtual void is_active(IsActiveFn is_active_fn); + virtual std::optional<bool> should_be_active() const; /** * Queries if the tree-view item supports renaming in principle. Renaming may still fail, e.g. if * another item is already being renamed. */ - virtual bool can_rename() const; + virtual bool supports_renaming() const; /** * Try renaming the item, or the data it represents. Can assume - * #AbstractTreeViewItem::can_rename() returned true. Sub-classes that override this should - * usually call this, unless they have a custom #AbstractTreeViewItem.matches(). + * #AbstractTreeViewItem::supports_renaming() returned true. Sub-classes that override this + * should usually call this, unless they have a custom #AbstractTreeViewItem.matches(). * * \return True if the renaming was successful. */ virtual bool rename(StringRefNull new_name); /** + * Return whether the item can be collapsed. Used to disable collapsing for items with children. + */ + virtual bool supports_collapsing() const; + + /** * Copy persistent state (e.g. is-collapsed flag, selection, etc.) from a matching item of * the last redraw to this item. If sub-classes introduce more advanced state they should * override this and make it update their state accordingly. */ virtual void update_from_old(const AbstractTreeViewItem &old); + /** * Compare this item to \a other to check if they represent the same data. * Used to recognize an item from a previous redraw, to be able to keep its state (e.g. @@ -288,47 +286,28 @@ class AbstractTreeViewItem : public TreeViewItemContainer { */ virtual std::unique_ptr<AbstractTreeViewItemDropController> create_drop_controller() const; - void begin_renaming(); - void end_renaming(); - - AbstractTreeView &get_tree_view() const; - int count_parents() const; - void deactivate(); /** - * Requires the tree to have completed reconstruction, see #is_reconstructed(). Otherwise we - * can't be sure about the item state. + * Activates this item, deactivates other items, calls the #AbstractTreeViewItem::on_activate() + * function and ensures this item's parents are not collapsed (so the item is visible). + * Requires the tree to have completed reconstruction, see #is_reconstructed(). Otherwise the + * actual item state is unknown, possibly calling state-change update functions incorrectly. */ - bool is_active() const; + void activate(); + void deactivate(); + /** * Can be called from the #AbstractTreeViewItem::build_row() implementation, but not earlier. The * hovered state can't be queried reliably otherwise. * Note that this does a linear lookup in the old block, so isn't too great performance-wise. */ bool is_hovered() const; - void toggle_collapsed(); - /** - * Requires the tree to have completed reconstruction, see #is_reconstructed(). Otherwise we - * can't be sure about the item state. - */ - bool is_collapsed() const; - void set_collapsed(bool collapsed); bool is_collapsible() const; bool is_renaming() const; void ensure_parents_uncollapsed(); - bool matches_including_parents(const AbstractTreeViewItem &other) const; uiButTreeRow *tree_row_button(); - protected: - /** - * Activates this item, deactivates other items, calls the #AbstractTreeViewItem::on_activate() - * function and ensures this item's parents are not collapsed (so the item is visible). - * Requires the tree to have completed reconstruction, see #is_reconstructed(). Otherwise the - * actual item state is unknown, possibly calling state-change update functions incorrectly. - */ - void activate(); - private: static void rename_button_fn(bContext *, void *, char *); static AbstractTreeViewItem *find_tree_item_from_rename_button(const uiBut &but); @@ -338,13 +317,16 @@ class AbstractTreeViewItem : public TreeViewItemContainer { /** See #AbstractTreeView::change_state_delayed() */ void change_state_delayed(); + void end_renaming(); void add_treerow_button(uiBlock &block); void add_indent(uiLayout &row) const; void add_collapse_chevron(uiBlock &block) const; void add_rename_button(uiLayout &row); + bool matches_including_parents(const AbstractTreeViewItem &other) const; bool has_active_child() const; + int count_parents() const; }; /** \} */ @@ -358,11 +340,18 @@ class AbstractTreeViewItem : public TreeViewItemContainer { * custom implementation of #AbstractTreeViewItem::create_drag_controller(). */ class AbstractTreeViewItemDragController { + protected: + AbstractTreeView &tree_view_; + public: + AbstractTreeViewItemDragController(AbstractTreeView &tree_view); virtual ~AbstractTreeViewItemDragController() = default; virtual int get_drag_type() const = 0; virtual void *create_drag_data() const = 0; + virtual void on_drag_start(); + + template<class TreeViewType> inline TreeViewType &tree_view() const; }; /** @@ -398,7 +387,7 @@ class AbstractTreeViewItemDropController { * Execute the logic to apply a drop of the data dragged with \a drag onto/into the item this * controller is for. */ - virtual bool on_drop(const wmDrag &drag) = 0; + virtual bool on_drop(struct bContext *C, const wmDrag &drag) = 0; template<class TreeViewType> inline TreeViewType &tree_view() const; }; @@ -416,6 +405,7 @@ class AbstractTreeViewItemDropController { */ class BasicTreeViewItem : public AbstractTreeViewItem { public: + using IsActiveFn = std::function<bool()>; using ActivateFn = std::function<void(BasicTreeViewItem &new_active)>; BIFIconID icon; @@ -423,7 +413,11 @@ class BasicTreeViewItem : public AbstractTreeViewItem { void build_row(uiLayout &row) override; void add_label(uiLayout &layout, StringRefNull label_override = ""); - void on_activate(ActivateFn fn); + void set_on_activate_fn(ActivateFn fn); + /** + * Set a custom callback to check if this item should be active. + */ + void set_is_active_fn(IsActiveFn fn); protected: /** @@ -433,15 +427,33 @@ class BasicTreeViewItem : public AbstractTreeViewItem { */ ActivateFn activate_fn_; + IsActiveFn is_active_fn_; + private: static void tree_row_click_fn(struct bContext *C, void *arg1, void *arg2); + std::optional<bool> should_be_active() const override; void on_activate() override; }; /** \} */ /* ---------------------------------------------------------------------- */ +/** \name Tree-View Builder + * \{ */ + +class TreeViewBuilder { + uiBlock &block_; + + public: + TreeViewBuilder(uiBlock &block); + + void build_tree_view(AbstractTreeView &tree_view); +}; + +/** \} */ + +/* ---------------------------------------------------------------------- */ template<class ItemT, typename... Args> inline ItemT &TreeViewItemContainer::add_tree_item(Args &&...args) @@ -453,6 +465,13 @@ inline ItemT &TreeViewItemContainer::add_tree_item(Args &&...args) add_tree_item(std::make_unique<ItemT>(std::forward<Args>(args)...))); } +template<class TreeViewType> TreeViewType &AbstractTreeViewItemDragController::tree_view() const +{ + static_assert(std::is_base_of<AbstractTreeView, TreeViewType>::value, + "Type must derive from and implement the AbstractTreeView interface"); + return static_cast<TreeViewType &>(tree_view_); +} + template<class TreeViewType> TreeViewType &AbstractTreeViewItemDropController::tree_view() const { static_assert(std::is_base_of<AbstractTreeView, TreeViewType>::value, diff --git a/source/blender/editors/include/UI_view2d.h b/source/blender/editors/include/UI_view2d.h index 122e5a7d839..37246c2fe8f 100644 --- a/source/blender/editors/include/UI_view2d.h +++ b/source/blender/editors/include/UI_view2d.h @@ -118,21 +118,46 @@ typedef struct View2DScrollers View2DScrollers; /* ----------------------------------------- */ /* Prototypes: */ -/* refresh and validation (of view rects) */ +/** + * Refresh and validation (of view rects). + * + * Initialize all relevant View2D data (including view rects if first time) + * and/or refresh mask sizes after view resize. + * + * - For some of these presets, it is expected that the region will have defined some + * additional settings necessary for the customization of the 2D viewport to its requirements + * - This function should only be called from region init() callbacks, where it is expected that + * this is called before #UI_view2d_size_update(), + * as this one checks that the rects are properly initialized. + */ void UI_view2d_region_reinit(struct View2D *v2d, short type, int winx, int winy); void UI_view2d_curRect_validate(struct View2D *v2d); +/** + * Restore 'cur' rect to standard orientation (i.e. optimal maximum view of tot). + * This does not take into account if zooming the view on an axis + * will improve the view (if allowed). + */ void UI_view2d_curRect_reset(struct View2D *v2d); bool UI_view2d_area_supports_sync(struct ScrArea *area); +/** + * Called by menus to activate it, or by view2d operators + * to make sure 'related' views stay in synchrony. + */ void UI_view2d_sync(struct bScreen *screen, struct ScrArea *area, struct View2D *v2dcur, int flag); -/* Perform all required updates after `v2d->cur` as been modified. +/** + * Perform all required updates after `v2d->cur` as been modified. * This includes like validation view validation (#UI_view2d_curRect_validate). * - * Current intent is to use it from user code, such as view navigation and zoom operations. */ + * Current intent is to use it from user code, such as view navigation and zoom operations. + */ void UI_view2d_curRect_changed(const struct bContext *C, struct View2D *v2d); void UI_view2d_totRect_set(struct View2D *v2d, int width, int height); +/** + * Change the size of the maximum viewable area (i.e. 'tot' rect). + */ void UI_view2d_totRect_set_resize(struct View2D *v2d, int width, int height, bool resize); void UI_view2d_mask_from_win(const struct View2D *v2d, struct rcti *r_mask); @@ -140,16 +165,40 @@ void UI_view2d_mask_from_win(const struct View2D *v2d, struct rcti *r_mask); void UI_view2d_zoom_cache_reset(void); /* view matrix operations */ +/** + * Set view matrices to use 'cur' rect as viewing frame for View2D drawing. + */ void UI_view2d_view_ortho(const struct View2D *v2d); +/** + * Set view matrices to only use one axis of 'cur' only + * + * \param xaxis: if non-zero, only use cur x-axis, + * otherwise use cur-yaxis (mostly this will be used for x). + */ void UI_view2d_view_orthoSpecial(struct ARegion *region, struct View2D *v2d, const bool xaxis); +/** + * Restore view matrices after drawing. + */ void UI_view2d_view_restore(const struct bContext *C); /* grid drawing */ + +/** + * Draw a multi-level grid in given 2d-region. + */ void UI_view2d_multi_grid_draw( const struct View2D *v2d, int colorid, float step, int level_size, int totlevels); +/** + * Draw a multi-level grid of dots, with a dynamic number of levels based on the fading. + * + * \param grid_color_id: The theme color used for the points. Faded dynamically based on zoom. + * \param min_step: The base size of the grid. At different zoom levels, the visible grid may have + * a larger step size. + * \param grid_levels: The maximum grid depth. Larger grid levels will subdivide the grid more. + */ void UI_view2d_dot_grid_draw(const struct View2D *v2d, int grid_color_id, - float step, + float min_step, int grid_levels); void UI_view2d_draw_lines_y__values(const struct View2D *v2d); @@ -171,7 +220,9 @@ float UI_view2d_grid_resolution_x__frames_or_seconds(const struct View2D *v2d, bool display_seconds); float UI_view2d_grid_resolution_y__values(const struct View2D *v2d); -/* scale indicator text drawing */ +/** + * Scale indicator text drawing. + */ void UI_view2d_draw_scale_y__values(const struct ARegion *region, const struct View2D *v2d, const struct rcti *rect, @@ -193,25 +244,52 @@ void UI_view2d_draw_scale_x__frames_or_seconds(const struct ARegion *region, bool display_seconds, int colorid); -/* scrollbar drawing */ +/* Scroll-bar drawing. */ + +/** + * Calculate relevant scroller properties. + */ void UI_view2d_scrollers_calc(struct View2D *v2d, const struct rcti *mask_custom, struct View2DScrollers *r_scrollers); +/** + * Draw scroll-bars in the given 2D-region. + */ void UI_view2d_scrollers_draw(struct View2D *v2d, const struct rcti *mask_custom); -/* list view tools */ +/* List view tools. */ + +/** + * Get the 'cell' (row, column) that the given 2D-view coordinates + * (i.e. in 'tot' rect space) lie in. + * + * \param columnwidth, rowheight: size of each 'cell' + * \param startx, starty: coordinates (in 'tot' rect space) that the list starts from. + * This should be (0,0) for most views. However, for those where the starting row was offsetted + * (like for Animation Editor channel lists, to make the first entry more visible), these will be + * the min-coordinates of the first item. + * \param viewx, viewy: 2D-coordinates (in 2D-view / 'tot' rect space) to get the cell for + * \param r_column, r_row: The 'coordinates' of the relevant 'cell'. + */ void UI_view2d_listview_view_to_cell(float columnwidth, float rowheight, float startx, float starty, float viewx, float viewy, - int *column, - int *row); + int *r_column, + int *r_row); + +/* Coordinate conversion. */ -/* coordinate conversion */ float UI_view2d_region_to_view_x(const struct View2D *v2d, float x); float UI_view2d_region_to_view_y(const struct View2D *v2d, float y); +/** + * Convert from screen/region space to 2d-View space + * + * \param x, y: coordinates to convert + * \param r_view_x, r_view_y: resultant coordinates + */ void UI_view2d_region_to_view( const struct View2D *v2d, float x, float y, float *r_view_x, float *r_view_y) ATTR_NONNULL(); void UI_view2d_region_to_view_rctf(const struct View2D *v2d, @@ -220,9 +298,24 @@ void UI_view2d_region_to_view_rctf(const struct View2D *v2d, float UI_view2d_view_to_region_x(const struct View2D *v2d, float x); float UI_view2d_view_to_region_y(const struct View2D *v2d, float y); +/** + * Convert from 2d-View space to screen/region space + * \note Coordinates are clamped to lie within bounds of region + * + * \param x, y: Coordinates to convert. + * \param r_region_x, r_region_y: Resultant coordinates. + */ bool UI_view2d_view_to_region_clip( const struct View2D *v2d, float x, float y, int *r_region_x, int *r_region_y) ATTR_NONNULL(); +/** + * Convert from 2d-view space to screen/region space + * + * \note Coordinates are NOT clamped to lie within bounds of region. + * + * \param x, y: Coordinates to convert. + * \param r_region_x, r_region_y: Resultant coordinates. + */ void UI_view2d_view_to_region( const struct View2D *v2d, float x, float y, int *r_region_x, int *r_region_y) ATTR_NONNULL(); void UI_view2d_view_to_region_fl(const struct View2D *v2d, @@ -238,21 +331,64 @@ bool UI_view2d_view_to_region_rcti_clip(const struct View2D *v2d, const struct rctf *rect_src, struct rcti *rect_dst) ATTR_NONNULL(); -/* utilities */ +/* Utilities. */ + +/** + * View2D data by default resides in region, so get from region stored in context. + */ struct View2D *UI_view2d_fromcontext(const struct bContext *C); +/** + * Same as above, but it returns region-window. Utility for pull-downs or buttons. + */ struct View2D *UI_view2d_fromcontext_rwin(const struct bContext *C); +/** + * Get scrollbar sizes of the current 2D view. + * The size will be zero if the view has its scrollbars disabled. + */ void UI_view2d_scroller_size_get(const struct View2D *v2d, float *r_x, float *r_y); +/** + * Calculate the scale per-axis of the drawing-area + * + * Is used to inverse correct drawing of icons, etc. that need to follow view + * but not be affected by scale + * + * \param r_x, r_y: scale on each axis + */ void UI_view2d_scale_get(const struct View2D *v2d, float *r_x, float *r_y); float UI_view2d_scale_get_x(const struct View2D *v2d); float UI_view2d_scale_get_y(const struct View2D *v2d); +/** + * Same as `UI_view2d_scale_get() - 1.0f / x, y`. + */ void UI_view2d_scale_get_inverse(const struct View2D *v2d, float *r_x, float *r_y); +/** + * Simple functions for consistent center offset access. + * Used by node editor to shift view center for each individual node tree. + */ void UI_view2d_center_get(const struct View2D *v2d, float *r_x, float *r_y); void UI_view2d_center_set(struct View2D *v2d, float x, float y); +/** + * Simple pan function + * (0.0, 0.0) bottom left + * (0.5, 0.5) center + * (1.0, 1.0) top right. + */ void UI_view2d_offset(struct View2D *v2d, float xfac, float yfac); +/** + * Check if mouse is within scrollers + * + * \param xy: Mouse coordinates in screen (not region) space. + * \param r_scroll: Return argument for the mapped view2d scroll flag. + * + * \return appropriate code for match. + * - 'h' = in horizontal scroller. + * - 'v' = in vertical scroller. + * - 0 = not in scroller. + */ char UI_view2d_mouse_in_scrollers_ex(const struct ARegion *region, const struct View2D *v2d, const int xy[2], @@ -268,13 +404,18 @@ char UI_view2d_rect_in_scrollers(const struct ARegion *region, const struct View2D *v2d, const struct rcti *rect) ATTR_NONNULL(1, 2, 3); -/* cached text drawing in v2d, to allow pixel-aligned draw as post process */ +/** + * Cached text drawing in v2d, to allow pixel-aligned draw as post process. + */ void UI_view2d_text_cache_add(struct View2D *v2d, float x, float y, const char *str, size_t str_len, const unsigned char col[4]); +/** + * No clip (yet). + */ void UI_view2d_text_cache_add_rectf(struct View2D *v2d, const struct rctf *rect_view, const char *str, @@ -282,10 +423,15 @@ void UI_view2d_text_cache_add_rectf(struct View2D *v2d, const unsigned char col[4]); void UI_view2d_text_cache_draw(struct ARegion *region); -/* operators */ +/* Operators. */ + void ED_operatortypes_view2d(void); void ED_keymap_view2d(struct wmKeyConfig *keyconf); +/** + * Will start timer if appropriate. + * the arguments are the desired situation. + */ void UI_view2d_smooth_view(struct bContext *C, struct ARegion *region, const struct rctf *cur, @@ -294,13 +440,16 @@ void UI_view2d_smooth_view(struct bContext *C, #define UI_MARKER_MARGIN_Y (42 * UI_DPI_FAC) #define UI_TIME_SCRUB_MARGIN_Y (23 * UI_DPI_FAC) -/* Gizmo Types */ +/* Gizmo Types. */ /* view2d_gizmo_navigate.c */ -/* Caller passes in own idname. */ + +/** + * Caller defines the name for gizmo group. + */ void VIEW2D_GGT_navigate_impl(struct wmGizmoGroupType *gzgt, const char *idname); -/* Edge pan */ +/* Edge pan. */ /** * Custom-data for view panning operators. @@ -361,11 +510,15 @@ void UI_view2d_edge_pan_init(struct bContext *C, void UI_view2d_edge_pan_reset(struct View2DEdgePanData *vpd); -/* Apply transform to view (i.e. adjust 'cur' rect). */ +/** + * Apply transform to view (i.e. adjust 'cur' rect). + */ void UI_view2d_edge_pan_apply(struct bContext *C, struct View2DEdgePanData *vpd, const int xy[2]) ATTR_NONNULL(1, 2, 3); -/* Apply transform to view using mouse events. */ +/** + * Apply transform to view using mouse events. + */ void UI_view2d_edge_pan_apply_event(struct bContext *C, struct View2DEdgePanData *vpd, const struct wmEvent *event); @@ -382,7 +535,9 @@ void UI_view2d_edge_pan_operator_properties_ex(struct wmOperatorType *ot, float delay, float zoom_influence); -/* Initialize panning data with operator settings. */ +/** + * Initialize panning data with operator settings. + */ void UI_view2d_edge_pan_operator_init(struct bContext *C, struct View2DEdgePanData *vpd, struct wmOperator *op); |