Cleanup: Move public docs to BKE_spline.hh header
This commit is contained in:
parent
23ffcb242d
commit
a1f0f2eacb
|
@ -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<blender::float3> 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<int> 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<float> evaluated_mappings() const;
|
||||
blender::Span<blender::float3> 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<blender::float3> 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.
|
||||
*
|
||||
* <pre>
|
||||
* handle_prev handle_next
|
||||
* x----------------x
|
||||
* / \
|
||||
* / x---O---x \
|
||||
* / result \
|
||||
* / \
|
||||
* O O
|
||||
* point_prev point_next
|
||||
* </pre>
|
||||
*/
|
||||
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<SplinePtr> splines() const;
|
||||
blender::MutableSpan<SplinePtr> 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<int> control_point_offsets() const;
|
||||
/**
|
||||
* Exactly like #control_point_offsets, but uses the number of evaluated points instead.
|
||||
*/
|
||||
blender::Array<int> 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<float> 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;
|
||||
};
|
||||
|
||||
|
|
|
@ -50,12 +50,6 @@ blender::MutableSpan<SplinePtr> 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<int> CurveEval::control_point_offsets() const
|
||||
{
|
||||
Array<int> offsets(splines_.size() + 1);
|
||||
|
@ -146,9 +130,6 @@ blender::Array<int> CurveEval::control_point_offsets() const
|
|||
return offsets;
|
||||
}
|
||||
|
||||
/**
|
||||
* Exactly like #control_point_offsets, but uses the number of evaluated points instead.
|
||||
*/
|
||||
blender::Array<int> CurveEval::evaluated_point_offsets() const
|
||||
{
|
||||
Array<int> offsets(splines_.size() + 1);
|
||||
|
@ -161,11 +142,6 @@ blender::Array<int> 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<float> CurveEval::accumulated_spline_lengths() const
|
||||
{
|
||||
Array<float> spline_lengths(splines_.size() + 1);
|
||||
|
@ -361,13 +337,6 @@ std::unique_ptr<CurveEval> 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
|
||||
|
|
|
@ -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<float3> 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.
|
||||
*
|
||||
* <pre>
|
||||
* handle_prev handle_next
|
||||
* x----------------x
|
||||
* / \
|
||||
* / x---O---x \
|
||||
* / result \
|
||||
* / \
|
||||
* O O
|
||||
* point_prev point_next
|
||||
* </pre>
|
||||
*/
|
||||
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<int> BezierSpline::control_point_offsets() const
|
||||
{
|
||||
if (!offset_cache_dirty_) {
|
||||
|
@ -568,12 +522,6 @@ static void calculate_mappings_linear_resolution(Span<int> 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<float> BezierSpline::evaluated_mappings() const
|
||||
{
|
||||
if (!mapping_cache_dirty_) {
|
||||
|
@ -659,11 +607,6 @@ Span<float3> 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
|
||||
{
|
||||
|
|
|
@ -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);
|
||||
|
|
Loading…
Reference in New Issue