From 61776befc3f88c373e47ccbdf8c75e2ca0f4e987 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 9 Dec 2021 00:55:11 +1100 Subject: Cleanup: move public doc-strings into headers for 'editors' Ref T92709 --- source/blender/editors/include/BIF_glutil.h | 26 + source/blender/editors/include/ED_anim_api.h | 360 +++++++++++--- source/blender/editors/include/ED_buttons.h | 5 + source/blender/editors/include/ED_clip.h | 13 + source/blender/editors/include/ED_curve.h | 24 + source/blender/editors/include/ED_fileselect.h | 29 +- source/blender/editors/include/ED_gizmo_library.h | 10 + source/blender/editors/include/ED_gpencil.h | 266 +++++++++- source/blender/editors/include/ED_image.h | 37 +- source/blender/editors/include/ED_info.h | 5 + source/blender/editors/include/ED_lattice.h | 4 + source/blender/editors/include/ED_mask.h | 49 ++ source/blender/editors/include/ED_mball.h | 18 + source/blender/editors/include/ED_mesh.h | 196 +++++++- source/blender/editors/include/ED_node.h | 46 ++ source/blender/editors/include/ED_numinput.h | 6 + source/blender/editors/include/ED_object.h | 161 +++++- source/blender/editors/include/ED_outliner.h | 17 + source/blender/editors/include/ED_paint.h | 16 + source/blender/editors/include/ED_particle.h | 6 + source/blender/editors/include/ED_render.h | 10 + source/blender/editors/include/ED_scene.h | 7 + source/blender/editors/include/ED_screen.h | 257 +++++++++- source/blender/editors/include/ED_sculpt.h | 9 +- source/blender/editors/include/ED_select_utils.h | 14 +- source/blender/editors/include/ED_sequencer.h | 10 + source/blender/editors/include/ED_space_api.h | 20 +- source/blender/editors/include/ED_text.h | 9 + source/blender/editors/include/ED_transform.h | 17 + .../include/ED_transform_snap_object_context.h | 23 + source/blender/editors/include/ED_undo.h | 49 +- source/blender/editors/include/ED_util.h | 34 ++ source/blender/editors/include/ED_uvedit.h | 14 + source/blender/editors/include/ED_view3d.h | 415 +++++++++++++++- .../blender/editors/include/ED_view3d_offscreen.h | 18 + source/blender/editors/include/UI_interface.h | 541 ++++++++++++++++++++- source/blender/editors/include/UI_interface.hh | 3 + .../blender/editors/include/UI_interface_icons.h | 18 +- source/blender/editors/include/UI_resources.h | 99 +++- source/blender/editors/include/UI_tree_view.hh | 6 + source/blender/editors/include/UI_view2d.h | 187 ++++++- 41 files changed, 2871 insertions(+), 183 deletions(-) (limited to 'source/blender/editors/include') 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 cab4c18211d..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,21 +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); -/* Retrieves the Action associated with this animation channel. */ +/** + * Retrieves the Action associated with this animation channel. + */ bAction *ANIM_channel_action_get(const bAnimListElem *ale); -/* Draw the given channel */ +/** + * 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, @@ -591,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... @@ -626,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, @@ -640,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 { @@ -663,27 +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 indicators for the action. */ +/** + * 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); @@ -697,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, @@ -709,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 -------------- */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Copy/Paste Buffer + * \{ */ -/* free the 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, @@ -759,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 */ @@ -785,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) @@ -837,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); @@ -863,11 +1052,18 @@ 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 */ +/** + * 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, @@ -877,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); /* ************************************************ */ @@ -905,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_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 4fa78eddec4..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); @@ -68,6 +71,9 @@ bool ED_space_clip_get_position(struct SpaceClip *sc, 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_fileselect.h b/source/blender/editors/include/ED_fileselect.h index c1936b2fde5..460de58bdb2 100644 --- a/source/blender/editors/include/ED_fileselect.h +++ b/source/blender/editors/include/ED_fileselect.h @@ -105,13 +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); @@ -124,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); @@ -150,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); @@ -166,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..53c55a7668f 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,6 +469,10 @@ 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, @@ -299,6 +481,9 @@ 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_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_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..e6a064a3f51 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 unselect verts. + * - 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 bContext, called in uvedit. + */ 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 0e03000efba..50d7bfc3960 100644 --- a/source/blender/editors/include/ED_render.h +++ b/source/blender/editors/include/ED_render.h @@ -56,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, @@ -83,6 +90,9 @@ typedef enum 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, 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..5db49357540 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,6 +383,9 @@ 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); Scene *ED_screen_scene_find_with_window(const struct bScreen *screen, @@ -253,31 +396,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-fullscreen layout to switch to that is not 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 +462,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 +476,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 +519,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 +562,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 +583,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 +648,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 +677,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 +713,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 f3aba12a924..d5303904842 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, @@ -217,12 +221,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); @@ -231,9 +240,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 */ @@ -259,6 +270,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..6300c017c95 100644 --- a/source/blender/editors/include/ED_view3d.h +++ b/source/blender/editors/include/ED_view3d.h @@ -107,6 +107,9 @@ 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); +/** + * \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 +127,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,6 +176,9 @@ 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 */ @@ -148,6 +187,14 @@ typedef enum { V3D_DEPTH_GPENCIL_ONLY, V3D_DEPTH_OBJECT_ONLY, } eV3DDepthOverrideMode; +/** + * Redraw the viewport depth buffer. + * + * \param mode: V3D_DEPTH_NO_GPENCIL - Redraw viewport without Grease Pencil and Annotations. + * V3D_DEPTH_GPENCIL_ONLY - Redraw viewport with Grease Pencil and Annotations only. + * V3D_DEPTH_OBJECT_ONLY - Redraw viewport with active object only. + * \param update_cache: If true, store the entire depth buffer in #rv3d->depths. + */ void ED_view3d_depth_override(struct Depsgraph *depsgraph, struct ARegion *region, struct View3D *v3d, @@ -309,6 +356,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 +376,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 +404,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 +419,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 +429,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 +443,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 +468,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 +486,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 +504,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,10 +520,29 @@ 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, @@ -454,6 +550,22 @@ bool ED_view3d_win_to_ray_clipped(struct Depsgraph *depsgraph, float ray_start[3], float ray_normal[3], const bool do_clip); +/** + * 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 esp. with ortho 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, @@ -462,13 +574,38 @@ bool ED_view3d_win_to_ray_clipped_ex(struct Depsgraph *depsgraph, float r_ray_normal[3], float r_ray_start[3], bool do_clip); +/** + * 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 +621,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,12 +639,57 @@ 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, @@ -515,6 +704,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 +720,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 +739,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 +771,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 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: + * + * 
+ *           +
+ * pt --> + /^ radius
+ *         / |
+ *        /  |
+ * view  +   +
+ *        \  |
+ *         \ |
+ *          \|
+ *           +
+ *
+ * + * \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 +833,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 +861,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 +897,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 +939,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 editmode 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 +1008,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 +1021,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 +1059,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 +1108,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 +1124,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 (num-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 +1141,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 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 +1184,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 +1214,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 +1226,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 +1234,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_interface.h b/source/blender/editors/include/UI_interface.h index 023a1a64daf..e29e0d3b150 100644 --- a/source/blender/editors/include/UI_interface.h +++ b/source/blender/editors/include/UI_interface.h @@ -451,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 x1, x2, y1, y2: The offsets for the view, not the zones. + */ void UI_draw_safe_areas(uint pos, const struct rctf *rect, const float title_aspect[2], @@ -462,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, @@ -503,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, @@ -592,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) @@ -613,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); @@ -625,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 */ @@ -637,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); @@ -716,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); @@ -730,12 +782,25 @@ 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); +/** + * 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); @@ -744,7 +809,9 @@ 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); @@ -759,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); @@ -777,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, @@ -789,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); @@ -808,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, @@ -818,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, @@ -1025,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, @@ -1210,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, @@ -1480,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); @@ -1545,6 +1664,9 @@ uiBut *uiDefBlockButN(uiBlock *block, short height, const char *tip); +/** + * Block button containing icon. + */ uiBut *uiDefIconBlockBut(uiBlock *block, uiBlockCreateFunc func, void *arg, @@ -1555,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, @@ -1575,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, @@ -1586,6 +1716,10 @@ uiBut *uiDefHotKeyevtButS(uiBlock *block, const short *modkeypoin, const char *tip); +/** + * \param arg is 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, @@ -1598,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, @@ -1641,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, @@ -1651,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, @@ -1659,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, @@ -1669,15 +1840,26 @@ 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_treerow_indentation_set(uiBut *but, int indentation); @@ -1707,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, @@ -1716,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); @@ -1753,28 +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); @@ -1787,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. */ @@ -1796,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); @@ -1831,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); @@ -1946,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); @@ -1958,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. */ @@ -2004,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, @@ -2059,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, @@ -2066,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, @@ -2089,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, @@ -2096,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); @@ -2123,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, @@ -2141,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, @@ -2157,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, @@ -2191,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, @@ -2276,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, @@ -2332,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); @@ -2353,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, @@ -2431,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, @@ -2494,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, @@ -2510,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, @@ -2551,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, @@ -2589,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 */ @@ -2601,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); @@ -2617,7 +3010,18 @@ bool UI_context_copy_to_selected_list(struct bContext *C, /* 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, @@ -2626,12 +3030,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); @@ -2642,6 +3052,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 */ @@ -2672,12 +3085,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, @@ -2687,15 +3112,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! */ @@ -2704,25 +3144,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, @@ -2744,6 +3215,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, @@ -2762,6 +3240,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 */ @@ -2770,6 +3252,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); @@ -2783,14 +3271,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); +/** + * 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, 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); @@ -2798,6 +3300,9 @@ void UI_tree_view_item_context_menu_build(struct bContext *C, const uiTreeViewItemHandle *item, uiLayout *column); +/** + * \param x, y: 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 0a054101e81..64c2ddc06a7 100644 --- a/source/blender/editors/include/UI_tree_view.hh +++ b/source/blender/editors/include/UI_tree_view.hh @@ -141,6 +141,12 @@ class TreeViewLayoutBuilder { /* Created through #TreeViewBuilder. */ TreeViewLayoutBuilder(uiBlock &block); + /** + * Moves the button following the last added chevron closer to the list item. + * + * Iterates backwards over buttons until finding the tree-row button, which is assumed to be the + * first button added for the row, and can act as a delimiter that way. + */ static void polish_layout(const uiBlock &block); }; diff --git a/source/blender/editors/include/UI_view2d.h b/source/blender/editors/include/UI_view2d.h index 122e5a7d839..c38c4dc1156 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,13 +165,37 @@ 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, @@ -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,13 +244,33 @@ 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, @@ -209,9 +280,16 @@ void UI_view2d_listview_view_to_cell(float columnwidth, int *column, int *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 x, y: Mouse coordinates in screen (not region) space. + * \param r_scroll: 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); -- cgit v1.2.3