From ffc4c126f5416b04a01653e7a03451797b98aba4 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Tue, 7 Dec 2021 17:19:15 +1100 Subject: 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 --- source/blender/blenkernel/BKE_curve.h | 104 ++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) (limited to 'source/blender/blenkernel/BKE_curve.h') diff --git a/source/blender/blenkernel/BKE_curve.h b/source/blender/blenkernel/BKE_curve.h index 2f7569b1f03..713ee8cac01 100644 --- a/source/blender/blenkernel/BKE_curve.h +++ b/source/blender/blenkernel/BKE_curve.h @@ -86,6 +86,9 @@ typedef struct CVKeyIndex { #define CU_DO_2DFILL(cu) (CU_IS_2D(cu) && (((cu)->flag & (CU_FRONT | CU_BACK)) != 0)) /* ** Curve ** */ +/** + * Frees edit-curve entirely. + */ void BKE_curve_editfont_free(struct Curve *cu); void BKE_curve_init(struct Curve *cu, const short curve_type); struct Curve *BKE_curve_add(struct Main *bmain, const char *name, int type); @@ -98,6 +101,8 @@ struct BoundBox *BKE_curve_boundbox_get(struct Object *ob); void BKE_curve_texspace_calc(struct Curve *cu); void BKE_curve_texspace_ensure(struct Curve *cu); +/* Basic vertex data functions. */ + bool BKE_curve_minmax(struct Curve *cu, bool use_radius, float min[3], float max[3]); bool BKE_curve_center_median(struct Curve *cu, float cent[3]); bool BKE_curve_center_bounds(struct Curve *cu, float cent[3]); @@ -119,14 +124,26 @@ void BKE_curve_material_remap(struct Curve *cu, const unsigned int *remap, unsig void BKE_curve_smooth_flag_set(struct Curve *cu, const bool use_smooth); +/** + * \return edit-nurbs or normal nurbs list. + */ ListBase *BKE_curve_nurbs_get(struct Curve *cu); const ListBase *BKE_curve_nurbs_get_for_read(const struct Curve *cu); int BKE_curve_nurb_vert_index_get(const struct Nurb *nu, const void *vert); void BKE_curve_nurb_active_set(struct Curve *cu, const struct Nurb *nu); struct Nurb *BKE_curve_nurb_active_get(struct Curve *cu); +/** + * Get active vert for curve. + */ void *BKE_curve_vert_active_get(struct Curve *cu); +/** + * Set active nurb and active vert for curve. + */ void BKE_curve_nurb_vert_active_set(struct Curve *cu, const struct Nurb *nu, const void *vert); +/** + * Get points to the active nurb and active vert for curve. + */ bool BKE_curve_nurb_vert_active_get(struct Curve *cu, struct Nurb **r_nu, void **r_vert); void BKE_curve_nurb_vert_active_validate(struct Curve *cu); @@ -152,6 +169,9 @@ void BKE_curve_nurbs_key_vert_tilts_apply(struct ListBase *lb, const float *key) void BKE_curve_editNurb_keyIndex_delCV(struct GHash *keyindex, const void *cv); void BKE_curve_editNurb_keyIndex_free(struct GHash **keyindex); void BKE_curve_editNurb_free(struct Curve *cu); +/** + * Get list of nurbs from edit-nurbs structure. + */ struct ListBase *BKE_curve_editNurbs_get(struct Curve *cu); const struct ListBase *BKE_curve_editNurbs_get_for_read(const struct Curve *cu); @@ -159,8 +179,14 @@ void BKE_curve_bevelList_free(struct ListBase *bev); void BKE_curve_bevelList_make(struct Object *ob, const struct ListBase *nurbs, bool for_render); ListBase BKE_curve_bevel_make(const struct Curve *curve); +/** + * Forward differencing method for bezier curve. + */ void BKE_curve_forward_diff_bezier( float q0, float q1, float q2, float q3, float *p, int it, int stride); +/** + * Forward differencing method for first derivative of cubic bezier curve. + */ void BKE_curve_forward_diff_tangent_bezier( float q0, float q1, float q2, float q3, float *p, int it, int stride); @@ -168,6 +194,10 @@ void BKE_curve_rect_from_textbox(const struct Curve *cu, const struct TextBox *tb, struct rctf *r_rect); +/** + * This function is almost the same as #BKE_fcurve_correct_bezpart, + * but doesn't allow as large a tangent. + */ void BKE_curve_correct_bezpart(const float v1[2], float v2[2], float v3[2], const float v4[2]); /* ** Nurbs ** */ @@ -179,6 +209,15 @@ int BKE_nurbList_verts_count_without_handles(const struct ListBase *nurb); void BKE_nurbList_free(struct ListBase *lb); void BKE_nurbList_duplicate(struct ListBase *lb1, const struct ListBase *lb2); +/** + * \param code: + * - 1 (#HD_AUTO): set auto-handle. + * - 2 (#HD_VECT): set vector-handle. + * - 3 (#HD_ALIGN) it toggle, vector-handles become #HD_FREE. + * + * - 5: Set align, like 3 but no toggle. + * - 6: Clear align (setting #HD_FREE), like 3 but no toggle. + */ void BKE_nurbList_handles_set(struct ListBase *editnurb, const char code); void BKE_nurbList_handles_recalculate(struct ListBase *editnurb, const bool calc_length, @@ -186,18 +225,36 @@ void BKE_nurbList_handles_recalculate(struct ListBase *editnurb, void BKE_nurbList_handles_autocalc(ListBase *editnurb, uint8_t flag); void BKE_nurbList_flag_set(ListBase *editnurb, uint8_t flag, bool set); +/** + * Set \a flag for every point that already has \a from_flag set. + */ bool BKE_nurbList_flag_set_from_flag(ListBase *editnurb, uint8_t from_flag, uint8_t flag); void BKE_nurb_free(struct Nurb *nu); struct Nurb *BKE_nurb_duplicate(const struct Nurb *nu); +/** + * Copy the nurb but allow for different number of points (to be copied after this). + */ struct Nurb *BKE_nurb_copy(struct Nurb *src, int pntsu, int pntsv); void BKE_nurb_project_2d(struct Nurb *nu); +/** + * if use_radius is truth, minmax will take points' radius into account, + * which will make bound-box closer to beveled curve. + */ void BKE_nurb_minmax(const struct Nurb *nu, bool use_radius, float min[3], float max[3]); float BKE_nurb_calc_length(const struct Nurb *nu, int resolution); +/** + * \param coord_array: has to be `(3 * 4 * resolu * resolv)` in size, and zero-ed. + */ void BKE_nurb_makeFaces( const struct Nurb *nu, float *coord_array, int rowstride, int resolu, int resolv); +/** + * \param coord_array: Has to be `(3 * 4 * pntsu * resolu)` in size and zero-ed + * \param tilt_array: set when non-NULL + * \param radius_array: set when non-NULL + */ void BKE_nurb_makeCurve(const struct Nurb *nu, float *coord_array, float *tilt_array, @@ -206,10 +263,19 @@ void BKE_nurb_makeCurve(const struct Nurb *nu, int resolu, int stride); +/** + * Calculate the length for arrays filled in by #BKE_curve_calc_coords_axis. + */ unsigned int BKE_curve_calc_coords_axis_len(const unsigned int bezt_array_len, const unsigned int resolu, const bool is_cyclic, const bool use_cyclic_duplicate_endpoint); +/** + * Calculate an array for the entire curve (cyclic or non-cyclic). + * \note Call for each axis. + * + * \param use_cyclic_duplicate_endpoint: Duplicate values at the beginning & end of the array. + */ void BKE_curve_calc_coords_axis(const struct BezTriple *bezt_array, const unsigned int bezt_array_len, const unsigned int resolu, @@ -232,11 +298,17 @@ bool BKE_nurb_order_clamp_u(struct Nurb *nu); bool BKE_nurb_order_clamp_v(struct Nurb *nu); void BKE_nurb_direction_switch(struct Nurb *nu); +/** + * \note caller must ensure active vertex remains valid. + */ bool BKE_nurb_type_convert(struct Nurb *nu, const short type, const bool use_handles, const char **r_err_msg); +/** + * Be sure to call #BKE_nurb_knot_calc_u / #BKE_nurb_knot_calc_v after this. + */ void BKE_nurb_points_add(struct Nurb *nu, int number); void BKE_nurb_bezierPoints_add(struct Nurb *nu, int number); @@ -254,17 +326,31 @@ void BKE_nurb_bezt_calc_plane(struct Nurb *nu, struct BezTriple *bezt, float r_p void BKE_nurb_bpoint_calc_normal(struct Nurb *nu, struct BPoint *bp, float r_normal[3]); void BKE_nurb_bpoint_calc_plane(struct Nurb *nu, struct BPoint *bp, float r_plane[3]); +/** + * Recalculate the handles of a nurb bezier-triple. Acts based on handle selection with `SELECT` + * flag. To use a different flag, use #BKE_nurb_handle_calc_ex(). + */ void BKE_nurb_handle_calc(struct BezTriple *bezt, struct BezTriple *prev, struct BezTriple *next, const bool is_fcurve, const char smoothing); +/** + * Variant of #BKE_nurb_handle_calc() that allows calculating based on a different select flag. + * + * \param handle_sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. + * Usually #SELECT, but may want to use a different one at times + * (if caller does not operate on selection). + */ void BKE_nurb_handle_calc_ex(struct BezTriple *bezt, struct BezTriple *prev, struct BezTriple *next, const eBezTriple_Flag__Alias handle_sel_flag, const bool is_fcurve, const char smoothing); +/** + * Similar to #BKE_nurb_handle_calc but for curves and figures out the previous and next for us. + */ void BKE_nurb_handle_calc_simple(struct Nurb *nu, struct BezTriple *bezt); void BKE_nurb_handle_calc_simple_auto(struct Nurb *nu, struct BezTriple *bezt); @@ -272,6 +358,18 @@ void BKE_nurb_handle_smooth_fcurve(struct BezTriple *bezt, int total, bool cycli void BKE_nurb_handles_calc(struct Nurb *nu); void BKE_nurb_handles_autocalc(struct Nurb *nu, uint8_t flag); +/** + * Update selected handle types to ensure valid state, e.g. deduce "Auto" types to concrete ones. + * Thereby \a sel_flag defines what qualifies as selected. + * Use when something has changed handle positions. + * + * The caller needs to recalculate handles. + * + * \param sel_flag: The flag (bezt.f1/2/3) value to use to determine selection. Usually `SELECT`, + * but may want to use a different one at times (if caller does not operate on * selection). + * \param use_handle: Check selection state of individual handles, otherwise always update both + * handles if the key is selected. + */ void BKE_nurb_bezt_handle_test(struct BezTriple *bezt, const eBezTriple_Flag__Alias sel_flag, const bool use_handle, @@ -337,6 +435,12 @@ void BKE_curve_deform_coords_with_editmesh(const struct Object *ob_curve, const short defaxis, struct BMEditMesh *em_target); +/** + * \param orco: Input vec and orco = local coord in curve space + * orco is original not-animated or deformed reference point. + * + * The result written to `vec` and `r_mat`. + */ void BKE_curve_deform_co(const struct Object *ob_curve, const struct Object *ob_target, const float orco[3], -- cgit v1.2.3