From a1f0f2eacb10d1429611979b1464408e48b800c8 Mon Sep 17 00:00:00 2001 From: Hans Goudey Date: Thu, 2 Dec 2021 09:24:21 -0500 Subject: Cleanup: Move public docs to BKE_spline.hh header --- source/blender/blenkernel/BKE_spline.hh | 101 +++++++++++++++++++++++++++++++- 1 file changed, 99 insertions(+), 2 deletions(-) (limited to 'source/blender/blenkernel/BKE_spline.hh') 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; }; -- cgit v1.2.3