diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:19:15 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:38:48 +0300 |
commit | ffc4c126f5416b04a01653e7a03451797b98aba4 (patch) | |
tree | ac63d70d33aae5ab1666c9c2f62058c9c1eebd5c /source/blender/blenkernel/BKE_mask.h | |
parent | f159d49f56cedccd509ee93f5a5fb51f4f39eeb8 (diff) |
Cleanup: move public doc-strings into headers for 'blenkernel'
- Added space below non doc-string comments to make it clear
these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.
Ref T92709
Diffstat (limited to 'source/blender/blenkernel/BKE_mask.h')
-rw-r--r-- | source/blender/blenkernel/BKE_mask.h | 128 |
1 files changed, 118 insertions, 10 deletions
diff --git a/source/blender/blenkernel/BKE_mask.h b/source/blender/blenkernel/BKE_mask.h index 8e2f6e6f10c..2a2b080217c 100644 --- a/source/blender/blenkernel/BKE_mask.h +++ b/source/blender/blenkernel/BKE_mask.h @@ -56,16 +56,20 @@ typedef enum { MASK_HANDLE_MODE_INDIVIDUAL_HANDLES = 2, } eMaskhandleMode; -struct MaskSplinePoint *BKE_mask_spline_point_array(struct MaskSpline *spline); -struct MaskSplinePoint *BKE_mask_spline_point_array_from_point( - struct MaskSpline *spline, const struct MaskSplinePoint *point_ref); +/* -------------------------------------------------------------------- */ +/** \name Mask Layers + * \{ */ -/* mask layers */ struct MaskLayer *BKE_mask_layer_new(struct Mask *mask, const char *name); +/** + * \note The returned mask-layer may be hidden, caller needs to check. + */ struct MaskLayer *BKE_mask_layer_active(struct Mask *mask); void BKE_mask_layer_active_set(struct Mask *mask, struct MaskLayer *masklay); void BKE_mask_layer_remove(struct Mask *mask, struct MaskLayer *masklay); +/** \brief Free all animation keys for a mask layer. + */ void BKE_mask_layer_free_shapes(struct MaskLayer *masklay); void BKE_mask_layer_free(struct MaskLayer *masklay); void BKE_mask_layer_free_list(struct ListBase *masklayers); @@ -83,7 +87,16 @@ void BKE_mask_layer_rename(struct Mask *mask, struct MaskLayer *BKE_mask_layer_copy(const struct MaskLayer *masklay); void BKE_mask_layer_copy_list(struct ListBase *masklayers_new, const struct ListBase *masklayers); -/* splines */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Splines + * \{ */ + +struct MaskSplinePoint *BKE_mask_spline_point_array(struct MaskSpline *spline); +struct MaskSplinePoint *BKE_mask_spline_point_array_from_point( + struct MaskSpline *spline, const struct MaskSplinePoint *point_ref); + struct MaskSpline *BKE_mask_spline_add(struct MaskLayer *masklay); bool BKE_mask_spline_remove(struct MaskLayer *mask_layer, struct MaskSpline *spline); void BKE_mask_point_direction_switch(struct MaskSplinePoint *point); @@ -104,7 +117,12 @@ float BKE_mask_spline_project_co(struct MaskSpline *spline, const float co[2], const eMaskSign sign); -/* point */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Point + * \{ */ + eMaskhandleMode BKE_mask_point_handles_mode_get(const struct MaskSplinePoint *point); void BKE_mask_point_handle(const struct MaskSplinePoint *point, eMaskWhichHandle which_handle, @@ -139,7 +157,12 @@ void BKE_mask_point_select_set_handle(struct MaskSplinePoint *point, const eMaskWhichHandle which_handle, const bool do_select); -/* general */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name General + * \{ */ + struct Mask *BKE_mask_new(struct Main *bmain, const char *name); void BKE_mask_coord_from_frame(float r_co[2], const float co[2], const float frame_size[2]); @@ -151,6 +174,9 @@ void BKE_mask_coord_from_image(struct Image *image, struct ImageUser *iuser, float r_co[2], const float co[2]); +/** + * Inverse of #BKE_mask_coord_from_image. + */ void BKE_mask_coord_to_frame(float r_co[2], const float co[2], const float frame_size[2]); void BKE_mask_coord_to_movieclip(struct MovieClip *clip, struct MovieClipUser *user, @@ -161,7 +187,11 @@ void BKE_mask_coord_to_image(struct Image *image, float r_co[2], const float co[2]); -/* parenting */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Parenting + * \{ */ void BKE_mask_evaluate(struct Mask *mask, const float ctime, const bool do_newframe); void BKE_mask_layer_evaluate(struct MaskLayer *masklay, const float ctime, const bool do_newframe); @@ -169,10 +199,19 @@ void BKE_mask_parent_init(struct MaskParent *parent); void BKE_mask_calc_handle_adjacent_interp(struct MaskSpline *spline, struct MaskSplinePoint *point, const float u); +/** + * Calculates the tangent of a point by its previous and next + * (ignoring handles - as if its a poly line). + */ void BKE_mask_calc_tangent_polyline(struct MaskSpline *spline, struct MaskSplinePoint *point, float t[2]); void BKE_mask_calc_handle_point(struct MaskSpline *spline, struct MaskSplinePoint *point); +/** + * \brief Resets auto handles even for non-auto bezier points + * + * Useful for giving sane defaults. + */ void BKE_mask_calc_handle_point_auto(struct MaskSpline *spline, struct MaskSplinePoint *point, const bool do_recalc_length); @@ -186,20 +225,40 @@ void BKE_mask_point_parent_matrix_get(struct MaskSplinePoint *point, float ctime, float parent_matrix[3][3]); -/* animation */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Animation + * \{ */ + int BKE_mask_layer_shape_totvert(struct MaskLayer *masklay); +/** + * Inverse of #BKE_mask_layer_shape_to_mask + */ void BKE_mask_layer_shape_from_mask(struct MaskLayer *masklay, struct MaskLayerShape *masklay_shape); +/** + * Inverse of #BKE_mask_layer_shape_from_mask + */ void BKE_mask_layer_shape_to_mask(struct MaskLayer *masklay, struct MaskLayerShape *masklay_shape); +/** + * \note Linear interpolation only. + */ void BKE_mask_layer_shape_to_mask_interp(struct MaskLayer *masklay, struct MaskLayerShape *masklay_shape_a, struct MaskLayerShape *masklay_shape_b, const float fac); struct MaskLayerShape *BKE_mask_layer_shape_find_frame(struct MaskLayer *masklay, const int frame); +/** + * When returning 2 - the frame isn't found but before/after frames are. + */ int BKE_mask_layer_shape_find_frame_range(struct MaskLayer *masklay, const float frame, struct MaskLayerShape **r_masklay_shape_a, struct MaskLayerShape **r_masklay_shape_b); +/** + * \note Does *not* add to the list. + */ struct MaskLayerShape *BKE_mask_layer_shape_alloc(struct MaskLayer *masklay, const int frame); void BKE_mask_layer_shape_free(struct MaskLayerShape *masklay_shape); struct MaskLayerShape *BKE_mask_layer_shape_verify_frame(struct MaskLayer *masklay, @@ -214,19 +273,42 @@ bool BKE_mask_layer_shape_spline_from_index(struct MaskLayer *masklay, int *r_index); int BKE_mask_layer_shape_spline_to_index(struct MaskLayer *masklay, struct MaskSpline *spline); +/** + * When a new points added, resizing all shape-key arrays. + */ void BKE_mask_layer_shape_changed_add(struct MaskLayer *masklay, int index, bool do_init, bool do_init_interpolate); +/** + * Move array elements to account for removed point. + */ void BKE_mask_layer_shape_changed_remove(struct MaskLayer *masklay, int index, int count); int BKE_mask_get_duration(struct Mask *mask); -/* clipboard */ +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Clipboard + * \{ */ + +/** + * Free the clipboard. + */ void BKE_mask_clipboard_free(void); +/** + * Copy selected visible splines from the given layer to clipboard. + */ void BKE_mask_clipboard_copy_from_layer(struct MaskLayer *mask_layer); +/** + * Check clipboard is empty. + */ bool BKE_mask_clipboard_is_empty(void); +/** + * Paste the contents of clipboard to given mask layer. + */ void BKE_mask_clipboard_paste_to_layer(struct Main *bmain, struct MaskLayer *mask_layer); #define MASKPOINT_ISSEL_ANY(p) ((((p)->bezt.f1 | (p)->bezt.f2 | (p)->bezt.f3) & SELECT) != 0) @@ -260,9 +342,16 @@ void BKE_mask_clipboard_paste_to_layer(struct Main *bmain, struct MaskLayer *mas } \ (void)0 +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Evaluation + * \{ */ + #define MASK_RESOL_MAX 128 /* mask_evaluate.c */ + unsigned int BKE_mask_spline_resolution(struct MaskSpline *spline, int width, int height); unsigned int BKE_mask_spline_feather_resolution(struct MaskSpline *spline, int width, int height); int BKE_mask_spline_differentiate_calc_total(const struct MaskSpline *spline, @@ -276,6 +365,10 @@ void BKE_mask_spline_feather_collapse_inner_loops(struct MaskSpline *spline, const unsigned int tot_feather_point); float (*BKE_mask_spline_differentiate( struct MaskSpline *spline, int width, int height, unsigned int *r_tot_diff_point))[2]; +/** + * values align with #BKE_mask_spline_differentiate_with_resolution + * when \a resol arguments match. + */ float (*BKE_mask_spline_feather_differentiated_points_with_resolution( struct MaskSpline *spline, const unsigned int resol, @@ -283,6 +376,7 @@ float (*BKE_mask_spline_feather_differentiated_points_with_resolution( unsigned int *r_tot_feather_point))[2]; /* *** mask point functions which involve evaluation *** */ + float (*BKE_mask_spline_feather_points(struct MaskSpline *spline, int *tot_feather_point))[2]; float *BKE_mask_point_segment_diff(struct MaskSpline *spline, @@ -291,6 +385,8 @@ float *BKE_mask_point_segment_diff(struct MaskSpline *spline, int height, unsigned int *r_tot_diff_point); +/* *** mask point functions which involve evaluation *** */ + float *BKE_mask_point_segment_feather_diff(struct MaskSpline *spline, struct MaskSplinePoint *point, int width, @@ -303,7 +399,14 @@ void BKE_mask_layer_evaluate_deform(struct MaskLayer *masklay, const float ctime void BKE_mask_eval_animation(struct Depsgraph *depsgraph, struct Mask *mask); void BKE_mask_eval_update(struct Depsgraph *depsgraph, struct Mask *mask); +/** \} */ + +/* -------------------------------------------------------------------- */ +/** \name Rasterization + * \{ */ + /* mask_rasterize.c */ + struct MaskRasterHandle; typedef struct MaskRasterHandle MaskRasterHandle; @@ -318,11 +421,16 @@ void BKE_maskrasterize_handle_init(MaskRasterHandle *mr_handle, const bool do_feather); float BKE_maskrasterize_handle_sample(MaskRasterHandle *mr_handle, const float xy[2]); +/** + * \brief Rasterize a buffer from a single mask (threaded execution). + */ void BKE_maskrasterize_buffer(MaskRasterHandle *mr_handle, const unsigned int width, const unsigned int height, float *buffer); +/** \} */ + #ifdef __cplusplus } #endif |