diff --git a/source/blender/blenkernel/BKE_spline.hh b/source/blender/blenkernel/BKE_spline.hh index 67eaa7c12c9..b8b18f0b50a 100644 --- a/source/blender/blenkernel/BKE_spline.hh +++ b/source/blender/blenkernel/BKE_spline.hh @@ -286,6 +286,9 @@ class BezierSpline final : public Spline { int resolution() const; void set_resolution(const int value); + /** + * \warning Call #reallocate on the spline's attributes after adding all points. + */ void add_point(const blender::float3 position, const HandleType handle_type_left, const blender::float3 handle_position_left, @@ -321,12 +324,24 @@ class BezierSpline final : public Spline { * uninitialized memory while auto-generating handles. */ blender::MutableSpan handle_positions_right(bool write_only = false); + /** + * Recalculate all #Auto and #Vector handles with positions automatically + * derived from the neighboring control points. + */ void ensure_auto_handles() const; void translate(const blender::float3 &translation) override; void transform(const blender::float4x4 &matrix) override; + /** + * Set positions for the right handle of the control point, ensuring that + * aligned handles stay aligned. Has no effect for auto and vector type handles. + */ void set_handle_position_right(const int index, const blender::float3 &value); + /** + * Set positions for the left handle of the control point, ensuring that + * aligned handles stay aligned. Has no effect for auto and vector type handles. + */ void set_handle_position_left(const int index, const blender::float3 &value); bool point_is_sharp(const int index) const; @@ -334,7 +349,22 @@ class BezierSpline final : public Spline { void mark_cache_invalid() final; int evaluated_points_size() const final; + /** + * Returns access to a cache of offsets into the evaluated point array for each control point. + * While most control point edges generate the number of edges specified by the resolution, + * vector segments only generate one edge. + * + * \note The length of the result is one greater than the number of points, so that the last item + * is the total number of evaluated points. This is useful to avoid recalculating the size of the + * last segment everywhere. + */ blender::Span control_point_offsets() const; + /** + * Returns non-owning access to an array of values containing the information necessary to + * interpolate values from the original control points to evaluated points. The control point + * index is the integer part of each value, and the factor used for interpolating to the next + * control point is the remaining factional part. + */ blender::Span evaluated_mappings() const; blender::Span evaluated_positions() const final; struct InterpolationData { @@ -346,6 +376,11 @@ class BezierSpline final : public Spline { */ float factor; }; + /** + * Convert the data encoded in #evaulated_mappings into its parts-- the information necessary + * to interpolate data from control points to evaluated points between them. The next control + * point index result will not overflow the size of the control point vectors. + */ InterpolationData interpolation_data_from_index_factor(const float index_factor) const; virtual blender::fn::GVArray interpolate_to_evaluated( @@ -354,6 +389,9 @@ class BezierSpline final : public Spline { void evaluate_segment(const int index, const int next_index, blender::MutableSpan positions) const; + /** + * \warning This functional assumes that the spline has more than one point. + */ bool segment_is_vector(const int start_index) const; /** See comment and diagram for #calculate_segment_insertion. */ @@ -364,6 +402,25 @@ class BezierSpline final : public Spline { blender::float3 right_handle; blender::float3 handle_next; }; + /** + * De Casteljau Bezier subdivision. + * \param index: The index of the segment's start control point. + * \param next_index: The index of the control point at the end of the segment. Could be 0, + * if the spline is cyclic. + * \param parameter: The factor along the segment, between 0 and 1. Note that this is used + * directly by the calculation, it doesn't correspond to a portion of the evaluated length. + * + * 
+   *           handle_prev         handle_next
+   *                x----------------x
+   *               /                  \
+   *              /      x---O---x     \
+   *             /        result        \
+   *            /                        \
+   *           O                          O
+   *       point_prev                  point_next
+   *
+ */ InsertResult calculate_segment_insertion(const int index, const int next_index, const float parameter); @@ -460,6 +517,9 @@ class NURBSpline final : public Spline { uint8_t order() const; void set_order(const uint8_t value); + /** + * \warning Call #reallocate on the spline's attributes after adding all points. + */ void add_point(const blender::float3 position, const float radius, const float tilt, @@ -521,6 +581,9 @@ class PolySpline final : public Spline { int size() const final; + /** + * \warning Call #reallocate on the spline's attributes after adding all points. + */ void add_point(const blender::float3 position, const float radius, const float tilt); void resize(const int size) final; @@ -546,8 +609,12 @@ class PolySpline final : public Spline { }; /** - * A #CurveEval corresponds to the #Curve object data. The name is different for clarity, since - * more of the data is stored in the splines, but also just to be different than the name in DNA. + * A collection of #Spline objects with the same attribute types and names. Most data and + * functionality is in splines, but this contains some helpers for working with them as a group. + * + * \note A #CurveEval corresponds to the #Curve object data. The name is different for clarity, + * since more of the data is stored in the splines, but also just to be different than the name in + * DNA. */ struct CurveEval { private: @@ -566,9 +633,18 @@ struct CurveEval { blender::Span splines() const; blender::MutableSpan splines(); + /** + * \return True if the curve contains a spline with the given type. + * + * \note If you are looping over all of the splines in the same scope anyway, + * it's better to avoid calling this function, in case there are many splines. + */ bool has_spline_with_type(const Spline::Type type) const; void resize(const int size); + /** + * \warning Call #reallocate on the spline's attributes after adding all splines. + */ void add_spline(SplinePtr spline); void remove_splines(blender::IndexMask mask); @@ -576,8 +652,22 @@ struct CurveEval { void transform(const blender::float4x4 &matrix); void bounds_min_max(blender::float3 &min, blender::float3 &max, const bool use_evaluated) const; + /** + * Return the start indices for each of the curve spline's control points, if they were part + * of a flattened array. This can be used to facilitate parallelism by avoiding the need to + * accumulate an offset while doing more complex calculations. + * + * \note The result is one longer than the spline count; the last element is the total size. + */ blender::Array control_point_offsets() const; + /** + * Exactly like #control_point_offsets, but uses the number of evaluated points instead. + */ blender::Array evaluated_point_offsets() const; + /** + * Return the accumulated length at the start of every spline in the curve. + * \note The result is one longer than the spline count; the last element is the total length. + */ blender::Array accumulated_spline_lengths() const; float total_length() const; @@ -585,6 +675,13 @@ struct CurveEval { void mark_cache_invalid(); + /** + * Check the invariants that curve control point attributes should always uphold, necessary + * because attributes are stored on splines rather than in a flat array on the curve: + * - The same set of attributes exists on every spline. + * - Attributes with the same name have the same type on every spline. + * - Attributes are in the same order on every spline. + */ void assert_valid_point_attributes() const; }; diff --git a/source/blender/blenkernel/intern/curve_eval.cc b/source/blender/blenkernel/intern/curve_eval.cc index 163f8b02b85..02abb097175 100644 --- a/source/blender/blenkernel/intern/curve_eval.cc +++ b/source/blender/blenkernel/intern/curve_eval.cc @@ -50,12 +50,6 @@ blender::MutableSpan CurveEval::splines() return splines_; } -/** - * \return True if the curve contains a spline with the given type. - * - * \note If you are looping over all of the splines in the same scope anyway, - * it's better to avoid calling this function, in case there are many splines. - */ bool CurveEval::has_spline_with_type(const Spline::Type type) const { for (const SplinePtr &spline : this->splines()) { @@ -72,9 +66,6 @@ void CurveEval::resize(const int size) attributes.reallocate(size); } -/** - * \warning Call #reallocate on the spline's attributes after adding all splines. - */ void CurveEval::add_spline(SplinePtr spline) { splines_.append(std::move(spline)); @@ -127,13 +118,6 @@ int CurveEval::total_control_point_size() const return count; } -/** - * Return the start indices for each of the curve spline's control points, if they were part - * of a flattened array. This can be used to facilitate parallelism by avoiding the need to - * accumulate an offset while doing more complex calculations. - * - * \note The result array is one longer than the spline count; the last element is the total size. - */ blender::Array CurveEval::control_point_offsets() const { Array offsets(splines_.size() + 1); @@ -146,9 +130,6 @@ blender::Array CurveEval::control_point_offsets() const return offsets; } -/** - * Exactly like #control_point_offsets, but uses the number of evaluated points instead. - */ blender::Array CurveEval::evaluated_point_offsets() const { Array offsets(splines_.size() + 1); @@ -161,11 +142,6 @@ blender::Array CurveEval::evaluated_point_offsets() const return offsets; } -/** - * Return the accumulated length at the start of every spline in the curve. - * - * \note The result is one longer than the spline count; the last element is the total length. - */ blender::Array CurveEval::accumulated_spline_lengths() const { Array spline_lengths(splines_.size() + 1); @@ -361,13 +337,6 @@ std::unique_ptr curve_eval_from_dna_curve(const Curve &dna_curve) return curve_eval_from_dna_curve(dna_curve, *BKE_curve_nurbs_get_for_read(&dna_curve)); } -/** - * Check the invariants that curve control point attributes should always uphold, necessary - * because attributes are stored on splines rather than in a flat array on the curve: - * - The same set of attributes exists on every spline. - * - Attributes with the same name have the same type on every spline. - * - Attributes are in the same order on every spline. - */ void CurveEval::assert_valid_point_attributes() const { #ifdef DEBUG diff --git a/source/blender/blenkernel/intern/spline_bezier.cc b/source/blender/blenkernel/intern/spline_bezier.cc index 0cadab998f5..4f854333c8a 100644 --- a/source/blender/blenkernel/intern/spline_bezier.cc +++ b/source/blender/blenkernel/intern/spline_bezier.cc @@ -70,9 +70,6 @@ void BezierSpline::set_resolution(const int value) this->mark_cache_invalid(); } -/** - * \warning Call #reallocate on the spline's attributes after adding all points. - */ void BezierSpline::add_point(const float3 position, const HandleType handle_type_left, const float3 handle_position_left, @@ -203,10 +200,6 @@ static float3 next_position(Span positions, const bool cyclic, const int return positions[i + 1]; } -/** - * Recalculate all #Auto and #Vector handles with positions automatically - * derived from the neighboring control points. - */ void BezierSpline::ensure_auto_handles() const { if (!auto_handles_dirty_) { @@ -315,10 +308,6 @@ static void set_handle_position(const float3 &position, } } -/** - * Set positions for the right handle of the control point, ensuring that - * aligned handles stay aligned. Has no effect for auto and vector type handles. - */ void BezierSpline::set_handle_position_right(const int index, const blender::float3 &value) { set_handle_position(positions_[index], @@ -329,10 +318,6 @@ void BezierSpline::set_handle_position_right(const int index, const blender::flo handle_positions_left_[index]); } -/** - * Set positions for the left handle of the control point, ensuring that - * aligned handles stay aligned. Has no effect for auto and vector type handles. - */ void BezierSpline::set_handle_position_left(const int index, const blender::float3 &value) { set_handle_position(positions_[index], @@ -349,9 +334,6 @@ bool BezierSpline::point_is_sharp(const int index) const ELEM(handle_types_right_[index], HandleType::Vector, HandleType::Free); } -/** - * \warning This functional assumes that the spline has more than one point. - */ bool BezierSpline::segment_is_vector(const int index) const { /* Two control points are necessary to form a segment, that should be checked by the caller. */ @@ -409,25 +391,6 @@ void BezierSpline::correct_end_tangents() const } } -/** - * De Casteljau Bezier subdivision. - * \param index: The index of the segment's start control point. - * \param next_index: The index of the control point at the end of the segment. Could be 0, - * if the spline is cyclic. - * \param parameter: The factor along the segment, between 0 and 1. Note that this is used - * directly by the calculation, it doesn't correspond to a portion of the evaluated length. - * - * 
- *           handle_prev         handle_next
- *                x----------------x
- *               /                  \
- *              /      x---O---x     \
- *             /        result        \
- *            /                        \
- *           O                          O
- *       point_prev                  point_next
- *
- */ BezierSpline::InsertResult BezierSpline::calculate_segment_insertion(const int index, const int next_index, const float parameter) @@ -493,15 +456,6 @@ void BezierSpline::evaluate_segment(const int index, } } -/** - * Returns access to a cache of offsets into the evaluated point array for each control point. - * While most control point edges generate the number of edges specified by the resolution, vector - * segments only generate one edge. - * - * \note The length of the result is one greater than the number of points, so that the last item - * is the total number of evaluated points. This is useful to avoid recalculating the size of the - * last segment everywhere. - */ Span BezierSpline::control_point_offsets() const { if (!offset_cache_dirty_) { @@ -568,12 +522,6 @@ static void calculate_mappings_linear_resolution(Span offsets, } } -/** - * Returns non-owning access to an array of values containing the information necessary to - * interpolate values from the original control points to evaluated points. The control point - * index is the integer part of each value, and the factor used for interpolating to the next - * control point is the remaining factional part. - */ Span BezierSpline::evaluated_mappings() const { if (!mapping_cache_dirty_) { @@ -659,11 +607,6 @@ Span BezierSpline::evaluated_positions() const return positions; } -/** - * Convert the data encoded in #evaulated_mappings into its parts-- the information necessary - * to interpolate data from control points to evaluated points between them. The next control - * point index result will not overflow the size of the control point vectors. - */ BezierSpline::InterpolationData BezierSpline::interpolation_data_from_index_factor( const float index_factor) const { diff --git a/source/blender/blenkernel/intern/spline_poly.cc b/source/blender/blenkernel/intern/spline_poly.cc index d495c977285..b5aca0357be 100644 --- a/source/blender/blenkernel/intern/spline_poly.cc +++ b/source/blender/blenkernel/intern/spline_poly.cc @@ -45,9 +45,6 @@ int PolySpline::size() const return size; } -/** - * \warning Call #reallocate on the spline's attributes after adding all points. - */ void PolySpline::add_point(const float3 position, const float radius, const float tilt) { positions_.append(position);