Cleanup: use doxygen comments & sections for animation files

This commit is contained in:
Campbell Barton 2022-03-09 16:29:22 +11:00
parent 136f0910ff
commit 9416004092
3 changed files with 129 additions and 85 deletions

View File

@ -14,49 +14,80 @@ extern ListBase builtin_keyingsets;
/* Operator Define Prototypes ------------------- */
/* Main Keyframe Management operators:
* These handle keyframes management from various spaces. They only make use of
* Keying Sets.
*/
/* -------------------------------------------------------------------- */
/** \name Main Keyframe Management operators
*
* These handle keyframes management from various spaces.
* They only make use of Keying Sets.
* \{ */
void ANIM_OT_keyframe_insert(struct wmOperatorType *ot);
void ANIM_OT_keyframe_delete(struct wmOperatorType *ot);
void ANIM_OT_keyframe_insert_by_name(struct wmOperatorType *ot);
void ANIM_OT_keyframe_delete_by_name(struct wmOperatorType *ot);
/* Main Keyframe Management operators:
* These handle keyframes management from various spaces. They will handle the menus
* required for each space.
*/
/** \} */
/* -------------------------------------------------------------------- */
/** \name Main Keyframe Management operators
*
* These handle keyframes management from various spaces.
* They will handle the menus required for each space.
* \{ */
void ANIM_OT_keyframe_insert_menu(struct wmOperatorType *ot);
void ANIM_OT_keyframe_delete_v3d(struct wmOperatorType *ot);
void ANIM_OT_keyframe_clear_v3d(struct wmOperatorType *ot);
/* Keyframe management operators for UI buttons (RMB menu). */
/** \} */
/* -------------------------------------------------------------------- */
/** \name Keyframe management operators for UI buttons (RMB menu)
* \{ */
void ANIM_OT_keyframe_insert_button(struct wmOperatorType *ot);
void ANIM_OT_keyframe_delete_button(struct wmOperatorType *ot);
void ANIM_OT_keyframe_clear_button(struct wmOperatorType *ot);
/* .......... */
/** \} */
/* -------------------------------------------------------------------- */
/** \name KeyingSet management operators for UI buttons (RMB menu)
* \{ */
/* KeyingSet management operators for UI buttons (RMB menu) */
void ANIM_OT_keyingset_button_add(struct wmOperatorType *ot);
void ANIM_OT_keyingset_button_remove(struct wmOperatorType *ot);
/* KeyingSet management operators for RNA collections/UI buttons */
/** \} */
/* -------------------------------------------------------------------- */
/** \name KeyingSet management operators for RNA collections/UI buttons
* \{ */
void ANIM_OT_keying_set_add(struct wmOperatorType *ot);
void ANIM_OT_keying_set_remove(struct wmOperatorType *ot);
void ANIM_OT_keying_set_path_add(struct wmOperatorType *ot);
void ANIM_OT_keying_set_path_remove(struct wmOperatorType *ot);
/* KeyingSet general operators */
/** \} */
/* -------------------------------------------------------------------- */
/** \name KeyingSet general operators
* \{ */
void ANIM_OT_keying_set_active_set(struct wmOperatorType *ot);
/* .......... */
/** \} */
/* -------------------------------------------------------------------- */
/** \name Driver management operators for UI buttons (RMB menu)
* \{ */
/* Driver management operators for UI buttons (RMB menu) */
void ANIM_OT_driver_button_add(struct wmOperatorType *ot);
void ANIM_OT_driver_button_remove(struct wmOperatorType *ot);
void ANIM_OT_driver_button_edit(struct wmOperatorType *ot);
void ANIM_OT_copy_driver_button(struct wmOperatorType *ot);
void ANIM_OT_paste_driver_button(struct wmOperatorType *ot);
/** \} */

View File

@ -244,7 +244,7 @@ FCurve *ED_action_fcurve_ensure(struct Main *bmain,
return fcu;
}
/* Helper for update_autoflags_fcurve() */
/** Helper for #update_autoflags_fcurve(). */
static void update_autoflags_fcurve_direct(FCurve *fcu, PropertyRNA *prop)
{
/* set additional flags for the F-Curve (i.e. only integer values) */
@ -304,7 +304,8 @@ void update_autoflags_fcurve(FCurve *fcu, bContext *C, ReportList *reports, Poin
/* ************************************************** */
/* KEYFRAME INSERTION */
/* Move the point where a key is about to be inserted to be inside the main cycle range.
/**
* Move the point where a key is about to be inserted to be inside the main cycle range.
* Returns the type of the cycle if it is enabled and valid.
*/
static eFCU_Cycle_Type remap_cyclic_keyframe_location(FCurve *fcu, float *px, float *py)
@ -345,7 +346,7 @@ static eFCU_Cycle_Type remap_cyclic_keyframe_location(FCurve *fcu, float *px, fl
return type;
}
/* Used to make curves newly added to a cyclic Action cycle with the correct period. */
/** Used to make curves newly added to a cyclic Action cycle with the correct period. */
static void make_new_fcurve_cyclic(const bAction *act, FCurve *fcu)
{
/* The curve must contain one (newly-added) keyframe. */
@ -652,11 +653,13 @@ enum {
KEYNEEDED_DELNEXT,
} /*eKeyNeededStatus*/;
/* This helper function determines whether a new keyframe is needed */
/* Cases where keyframes should not be added:
* 1. Keyframe to be added between two keyframes with similar values
* 2. Keyframe to be added on frame where two keyframes are already situated
* 3. Keyframe lies at point that intersects the linear line between two keyframes
/**
* This helper function determines whether a new keyframe is needed.
*
* Cases where keyframes should not be added:
* 1. Keyframe to be added between two keyframes with similar values.
* 2. Keyframe to be added on frame where two keyframes are already situated.
* 3. Keyframe lies at point that intersects the linear line between two keyframes.
*/
static short new_key_needed(FCurve *fcu, float cFrame, float nValue)
{
@ -769,7 +772,7 @@ static short new_key_needed(FCurve *fcu, float cFrame, float nValue)
/* ------------------ RNA Data-Access Functions ------------------ */
/* Try to read value using RNA-properties obtained already */
/** Try to read value using RNA-properties obtained already. */
static float *setting_get_rna_values(
PointerRNA *ptr, PropertyRNA *prop, float *buffer, int buffer_size, int *r_count)
{
@ -844,7 +847,8 @@ enum {
VISUALKEY_SCA,
};
/* This helper function determines if visual-keyframing should be used when
/**
* This helper function determines if visual-keyframing should be used when
* inserting keyframes for the given channel. As visual-keyframing only works
* on Object and Pose-Channel blocks, this should only get called for those
* blocktypes, when using "standard" keying but 'Visual Keying' option in Auto-Keying
@ -1012,7 +1016,8 @@ static bool visualkey_can_use(PointerRNA *ptr, PropertyRNA *prop)
return false;
}
/* This helper function extracts the value to use for visual-keyframing
/**
* This helper function extracts the value to use for visual-keyframing
* In the event that it is not possible to perform visual keying, try to fall-back
* to using the default method. Assumes that all data it has been passed is valid.
*/
@ -1305,7 +1310,7 @@ bool insert_keyframe_direct(ReportList *reports,
return insert_keyframe_value(reports, &ptr, prop, fcu, anim_eval_context, curval, keytype, flag);
}
/* Find or create the FCurve based on the given path, and insert the specified value into it. */
/** Find or create the #FCurve based on the given path, and insert the specified value into it. */
static bool insert_keyframe_fcurve_value(Main *bmain,
ReportList *reports,
PointerRNA *ptr,
@ -1829,9 +1834,10 @@ enum {
COMMONKEY_MODE_DELETE,
} /*eCommonModifyKey_Modes*/;
/* Polling callback for use with ANIM_*_keyframe() operators
/**
* Polling callback for use with `ANIM_*_keyframe()` operators
* This is based on the standard ED_operator_areaactive callback,
* except that it does special checks for a few spacetypes too...
* except that it does special checks for a few space-types too.
*/
static bool modify_key_op_poll(bContext *C)
{

View File

@ -51,8 +51,9 @@ struct PropertyRNA;
/** \name Context
* \{ */
/* This struct defines a structure used for animation-specific
* 'context' information
/**
* This struct defines a structure used for animation-specific
* 'context' information.
*/
typedef struct bAnimContext {
/** data to be filtered for use in animation editor */
@ -118,8 +119,9 @@ typedef enum eAnimCont_Types {
/** \name Channels
* \{ */
/* This struct defines a structure used for quick and uniform access for
* channels of animation data
/**
* This struct defines a structure used for quick and uniform access for
* channels of animation data.
*/
typedef struct bAnimListElem {
struct bAnimListElem *next, *prev;
@ -257,7 +259,8 @@ typedef enum eAnim_KeyType {
ALE_GROUP, /* Action Group summary */
} eAnim_KeyType;
/* Flags for specifying the types of updates (i.e. recalculation/refreshing) that
/**
* Flags for specifying the types of updates (i.e. recalculation/refreshing) that
* needs to be performed to the data contained in a channel following editing.
* For use with ANIM_animdata_update()
*/
@ -379,13 +382,13 @@ typedef enum eAnimFilter_Flags {
#define EXPANDED_DRVD(adt) ((adt->flag & ADT_DRIVERS_COLLAPSED) == 0)
/* Actions (also used for Dopesheet) */
/* Action Channel Group */
/** Action Channel Group. */
#define EDITABLE_AGRP(agrp) (((agrp)->flag & AGRP_PROTECTED) == 0)
#define EXPANDED_AGRP(ac, agrp) \
(((!(ac) || ((ac)->spacetype != SPACE_GRAPH)) && ((agrp)->flag & AGRP_EXPANDED)) || \
(((ac) && ((ac)->spacetype == SPACE_GRAPH)) && ((agrp)->flag & AGRP_EXPANDED_G)))
#define SEL_AGRP(agrp) (((agrp)->flag & AGRP_SELECTED) || ((agrp)->flag & AGRP_ACTIVE))
/* F-Curve Channels */
/** F-Curve Channels. */
#define EDITABLE_FCU(fcu) ((fcu->flag & FCURVE_PROTECTED) == 0)
#define SEL_FCU(fcu) (fcu->flag & FCURVE_SELECTED)
@ -394,16 +397,16 @@ typedef enum eAnimFilter_Flags {
#define SEL_SHAPEKEY(kb) (kb->flag & KEYBLOCK_SEL)
/* Grease Pencil only */
/* Grease Pencil datablock settings */
/** Grease Pencil data-block settings. */
#define EXPANDED_GPD(gpd) (gpd->flag & GP_DATA_EXPAND)
/* Grease Pencil Layer settings */
/** Grease Pencil Layer settings. */
#define EDITABLE_GPL(gpl) ((gpl->flag & GP_LAYER_LOCKED) == 0)
#define SEL_GPL(gpl) (gpl->flag & GP_LAYER_SELECT)
/* Mask Only */
/* Grease Pencil datablock settings */
/** Grease Pencil data-block settings. */
#define EXPANDED_MASK(mask) (mask->flag & MASK_ANIMF_EXPAND)
/* Grease Pencil Layer settings */
/** Grease Pencil Layer settings. */
#define EDITABLE_MASK(masklay) ((masklay->flag & MASK_LAYERFLAG_LOCKED) == 0)
#define SEL_MASKLAY(masklay) (masklay->flag & SELECT)
@ -426,20 +429,20 @@ typedef enum eAnimFilter_Flags {
/** \name Channel Defines
* \{ */
/* channel heights */
/** Channel heights. */
#define ACHANNEL_FIRST_TOP(ac) \
(UI_view2d_scale_get_y(&(ac)->region->v2d) * -UI_TIME_SCRUB_MARGIN_Y - ACHANNEL_SKIP)
#define ACHANNEL_HEIGHT(ac) (0.8f * (ac)->yscale_fac * U.widget_unit)
#define ACHANNEL_SKIP (0.1f * U.widget_unit)
#define ACHANNEL_STEP(ac) (ACHANNEL_HEIGHT(ac) + ACHANNEL_SKIP)
/* Additional offset to give some room at the end. */
/** Additional offset to give some room at the end. */
#define ACHANNEL_TOT_HEIGHT(ac, item_amount) \
(-ACHANNEL_FIRST_TOP(ac) + ACHANNEL_STEP(ac) * (item_amount + 1))
/* channel widths */
/** Channel widths. */
#define ACHANNEL_NAMEWIDTH (10 * U.widget_unit)
/* channel toggle-buttons */
/** Channel toggle-buttons. */
#define ACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit)
/** \} */
@ -448,7 +451,7 @@ typedef enum eAnimFilter_Flags {
/** \name NLA Channel Defines
* \{ */
/* NLA channel heights */
/** NLA channel heights */
#define NLACHANNEL_FIRST_TOP(ac) \
(UI_view2d_scale_get_y(&(ac)->region->v2d) * -UI_TIME_SCRUB_MARGIN_Y - NLACHANNEL_SKIP)
#define NLACHANNEL_HEIGHT(snla) \
@ -456,14 +459,14 @@ typedef enum eAnimFilter_Flags {
(1.2f * U.widget_unit))
#define NLACHANNEL_SKIP (0.1f * U.widget_unit)
#define NLACHANNEL_STEP(snla) (NLACHANNEL_HEIGHT(snla) + NLACHANNEL_SKIP)
/* Additional offset to give some room at the end. */
/** Additional offset to give some room at the end. */
#define NLACHANNEL_TOT_HEIGHT(ac, item_amount) \
(-NLACHANNEL_FIRST_TOP(ac) + NLACHANNEL_STEP(((SpaceNla *)(ac)->sl)) * (item_amount + 1))
/* channel widths */
/** Channel widths */
#define NLACHANNEL_NAMEWIDTH (10 * U.widget_unit)
/* channel toggle-buttons */
/** Channel toggle-buttons */
#define NLACHANNEL_BUTTON_WIDTH (0.8f * U.widget_unit)
/** \} */
@ -521,7 +524,7 @@ void ANIM_animdata_freelist(ListBase *anim_data);
/** \name Drawing TypeInfo
* \{ */
/* role or level of animchannel in the hierarchy */
/** Role or level of anim-channel in the hierarchy. */
typedef enum eAnimChannel_Role {
/** datablock expander - a "composite" channel type */
ACHANNEL_ROLE_EXPANDER = -1,
@ -561,7 +564,7 @@ typedef enum eAnimChannel_Settings {
ACHANNEL_SETTING_ALWAYS_VISIBLE = 8,
} eAnimChannel_Settings;
/* Drawing, mouse handling, and flag setting behavior... */
/** Drawing, mouse handling, and flag setting behavior. */
typedef struct bAnimChannelType {
/* -- Type data -- */
/* name of the channel type, for debugging */
@ -570,30 +573,31 @@ typedef struct bAnimChannelType {
eAnimChannel_Role channel_role;
/* -- Drawing -- */
/* get RGB color that is used to draw the majority of the backdrop */
/** Get RGB color that is used to draw the majority of the backdrop. */
void (*get_backdrop_color)(bAnimContext *ac, bAnimListElem *ale, float r_color[3]);
/* draw backdrop strip for channel */
/** Draw backdrop strip for channel. */
void (*draw_backdrop)(bAnimContext *ac, bAnimListElem *ale, float yminc, float ymaxc);
/* get depth of indention (relative to the depth channel is nested at) */
/** Get depth of indention (relative to the depth channel is nested at). */
short (*get_indent_level)(bAnimContext *ac, bAnimListElem *ale);
/* get offset in pixels for the start of the channel (in addition to the indent depth) */
/** Get offset in pixels for the start of the channel (in addition to the indent depth). */
short (*get_offset)(bAnimContext *ac, bAnimListElem *ale);
/* get name (for channel lists) */
/** Get name (for channel lists). */
void (*name)(bAnimListElem *ale, char *name);
/* get RNA property+pointer for editing the name */
/** Get RNA property+pointer for editing the name. */
bool (*name_prop)(bAnimListElem *ale, struct PointerRNA *ptr, struct PropertyRNA **prop);
/* get icon (for channel lists) */
/** Get icon (for channel lists). */
int (*icon)(bAnimListElem *ale);
/* -- Settings -- */
/* check if the given setting is valid in the current context */
/** Check if the given setting is valid in the current context. */
bool (*has_setting)(bAnimContext *ac, bAnimListElem *ale, eAnimChannel_Settings setting);
/* get the flag used for this setting */
/** Get the flag used for this setting. */
int (*setting_flag)(bAnimContext *ac, eAnimChannel_Settings setting, bool *neg);
/* get the pointer to int/short where data is stored,
* with type being sizeof(ptr_data) which should be fine for runtime use...
* - assume that setting has been checked to be valid for current context
/**
* Get the pointer to int/short where data is stored,
* with type being `sizeof(ptr_data)` which should be fine for runtime use.
* - assume that setting has been checked to be valid for current context.
*/
void *(*setting_ptr)(bAnimListElem *ale, eAnimChannel_Settings setting, short *type);
} bAnimChannelType;
@ -720,11 +724,11 @@ bool ANIM_remove_empty_action_from_animdata(struct AnimData *adt);
/* flags for Current Frame Drawing */
typedef enum eAnimEditDraw_CurrentFrame {
/* plain time indicator with no special indicators */
/** Plain time indicator with no special indicators. */
/* DRAWCFRA_PLAIN = 0, */ /* UNUSED */
/* time indication in seconds or frames */
/** Time indication in seconds or frames. */
DRAWCFRA_UNIT_SECONDS = (1 << 0),
/* draw indicator extra wide (for timeline) */
/** Draw indicator extra wide (for timeline). */
DRAWCFRA_WIDE = (1 << 1),
} eAnimEditDraw_CurrentFrame;
@ -784,9 +788,9 @@ struct NlaTrack *ANIM_nla_context_track(const struct bContext *C);
struct NlaStrip *ANIM_nla_context_strip(const struct bContext *C);
struct FCurve *ANIM_graph_context_fcurve(const struct bContext *C);
/* Needed for abstraction between the graph editor and the NLA editor. */
/** Needed for abstraction between the graph editor and the NLA editor. */
typedef bool (*PanelTypePollFn)(const struct bContext *C, struct PanelType *pt);
/* Avoid including "UI_interface.h" here. */
/** Avoid including `UI_interface.h` here. */
typedef void (*uiListPanelIDFromDataFunc)(void *data_link, char *r_idname);
/**
@ -912,20 +916,21 @@ void ED_nla_postop_refresh(bAnimContext *ac);
/* anim_draw.c */
/* flags for conversion mapping */
/** Flags for conversion mapping. */
typedef enum eAnimUnitConv_Flags {
/* restore to original internal values */
/** Restore to original internal values. */
ANIM_UNITCONV_RESTORE = (1 << 0),
/* ignore handles (i.e. only touch main keyframes) */
/** Ignore handles (i.e. only touch main keyframes). */
ANIM_UNITCONV_ONLYKEYS = (1 << 1),
/* only touch selected BezTriples */
/** Only touch selected BezTriples. */
ANIM_UNITCONV_ONLYSEL = (1 << 2),
/* only touch selected vertices */
/** Only touch selected vertices. */
ANIM_UNITCONV_SELVERTS = (1 << 3),
/* ANIM_UNITCONV_SKIPKNOTS = (1 << 4), */ /* UNUSED */
/* Scale FCurve i a way it fits to -1..1 space */
/** Scale FCurve i a way it fits to -1..1 space. */
ANIM_UNITCONV_NORMALIZE = (1 << 5),
/* Only when normalization is used: use scale factor from previous run,
/**
* Only when normalization is used: use scale factor from previous run,
* prevents curves from jumping all over the place when tweaking them.
*/
ANIM_UNITCONV_NORMALIZE_FREEZE = (1 << 6),
@ -953,10 +958,11 @@ float ANIM_unit_mapping_get_factor(
*/
#define BEZKEYTYPE(bezt) ((bezt)->hide)
/* set/clear/toggle macro
* - channel - channel with a 'flag' member that we're setting
* - smode - 0=clear, 1=set, 2=invert
* - sflag - bitflag to set
/**
* Set/Clear/Toggle macro.
* \param channel: Channel with a 'flag' member that we're setting.
* \param smode: 0=clear, 1=set, 2=invert.
* \param sflag: bit-flag to set.
*/
#define ACHANNEL_SET_FLAG(channel, smode, sflag) \
{ \
@ -972,10 +978,11 @@ float ANIM_unit_mapping_get_factor(
} \
((void)0)
/* set/clear/toggle macro, where the flag is negative
* - channel - channel with a 'flag' member that we're setting
* - smode - 0=clear, 1=set, 2=invert
* - sflag - bitflag to set
/**
* Set/Clear/Toggle macro, where the flag is negative.
* \param channel: channel with a 'flag' member that we're setting.
* \param smode: 0=clear, 1=set, 2=invert.
* \param sflag: Bit-flag to set.
*/
#define ACHANNEL_SET_FLAG_NEG(channel, smode, sflag) \
{ \
@ -1067,13 +1074,13 @@ void ED_drivers_editor_init(struct bContext *C, struct ScrArea *area);
/* ************************************************ */
typedef enum eAnimvizCalcRange {
/* Update motion paths at the current frame only. */
/** Update motion paths at the current frame only. */
ANIMVIZ_CALC_RANGE_CURRENT_FRAME,
/* Try to limit updates to a close neighborhood of the current frame. */
/** Try to limit updates to a close neighborhood of the current frame. */
ANIMVIZ_CALC_RANGE_CHANGED,
/* Update an entire range of the motion paths. */
/** Update an entire range of the motion paths. */
ANIMVIZ_CALC_RANGE_FULL,
} eAnimvizCalcRange;