HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
types.h
Go to the documentation of this file.
1 //
2 // Copyright 2024 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 
8 #ifndef PXR_BASE_TS_TYPES_H
9 #define PXR_BASE_TS_TYPES_H
10 
11 #include "pxr/pxr.h"
12 #include "pxr/base/ts/api.h"
13 
14 #include "pxr/base/gf/interval.h"
15 #include "pxr/base/gf/vec2d.h"
17 
18 #include <cstdint>
19 #include <vector>
20 
22 
23 /// \anchor TS_SPLINE_SUPPORTED_VALUE_TYPES
24 /// Sequence of value types that are supported by the spline system.
25 /// \li <b>double</b>
26 /// \li <b>float</b>
27 /// \li <b>GfHalf</b>
28 /// \hideinitializer
29 #define TS_SPLINE_SUPPORTED_VALUE_TYPES \
30  ((Double, double)) \
31  ((Float, float)) \
32  ((Half, GfHalf))
33 
34 #define TS_SPLINE_SAMPLE_VERTEX_TYPES \
35  ((Vec2d, GfVec2d)) \
36  ((Vec2f, GfVec2f)) \
37  ((Vec2h, GfVec2h))
38 
39 #define TS_SPLINE_VALUE_TYPE_NAME(x) TF_PP_TUPLE_ELEM(0, x)
40 #define TS_SPLINE_VALUE_CPP_TYPE(x) TF_PP_TUPLE_ELEM(1, x)
41 
42 /// \brief True if template parameter T is a supported spline data type.
43 template <class T>
44 inline constexpr bool
46 
47 #define _TS_SUPPORT_DATA_TYPE(unused, tuple) \
48  template <> \
49  inline constexpr bool \
50  TsSplineIsValidDataType< TS_SPLINE_VALUE_CPP_TYPE(tuple) > = true;
52  ~,
54 #undef _TS_SUPPORT_DATA_TYPE
55 
56 /// \brief True if template parameter T is a supported spline sampling vertex
57 /// type.
58 template <class T>
59 inline constexpr bool
60 TsSplineIsValidSampleType = false;
61 
62 #define _TS_SUPPORT_SAMPLE_TYPE(unused, tuple) \
63  template <> \
64  inline constexpr bool \
65  TsSplineIsValidSampleType< TS_SPLINE_VALUE_CPP_TYPE(tuple) > = true;
67  ~,
69 #undef _TS_SUPPORT_SAMPLE_TYPE
70 
71 // Times are encoded as double.
72 using TsTime = double;
73 
74 //////////////////////////////
75 // ** NOTE TO MAINTAINERS **
76 //
77 // The following enum values are used in the binary crate format.
78 // Do not change them; only add.
79 
80 /// Interpolation mode for a spline segment (region between two knots).
81 ///
83 {
84  TsInterpValueBlock = 0, //< No value in this segment.
85  TsInterpHeld = 1, //< Constant value in this segment.
86  TsInterpLinear = 2, //< Linear interpolation.
87  TsInterpCurve = 3 //< Bezier or Hermite, depends on curve type.
88 };
89 
90 /// Type of interpolation for a spline's \c Curve segments.
91 ///
93 {
94  TsCurveTypeBezier = 0, //< Bezier curve, free tangent widths.
95  TsCurveTypeHermite = 1 //< Hermite curve, like Bezier but fixed tan width.
96 };
97 
98 /// Curve-shaping mode for one of a spline's extrapolation regions (before all
99 /// knots and after all knots).
100 ///
102 {
103  TsExtrapValueBlock = 0, //< No value in this region.
104  TsExtrapHeld = 1, //< Constant value in this region.
105  TsExtrapLinear = 2, //< Linear interpolation based on edge knots.
106  TsExtrapSloped = 3, //< Linear interpolation with specified slope.
107  TsExtrapLoopRepeat = 4, //< Knot curve repeated, offset so ends meet.
108  TsExtrapLoopReset = 5, //< Curve repeated exactly, discontinuous joins.
109  TsExtrapLoopOscillate = 6 //< Like Reset, but every other copy reversed.
110 };
111 
112 /// The source for a particular part of a sampled spline. A \c TsSpline can have
113 /// a number of different regions. The source is not important to the values
114 /// that vary over time, but if the spline is sampled and displayed in a user
115 /// interface, the source can be used to highlight different regions of the
116 /// displayed spline.
117 ///
119 {
120  TsSourcePreExtrap, //< Extrapolation before the first knot
121  TsSourcePreExtrapLoop, //< Looped extrapolation before the first knot
122  TsSourceInnerLoopPreEcho, //< Echoed copy of an inner loop prototype
123  TsSourceInnerLoopProto, //< This is the inner loop prototype
124  TsSourceInnerLoopPostEcho, //< Echoed copy of an inner loop prototype
125  TsSourceKnotInterp, //< "Normal" knot interpolation
126  TsSourcePostExtrap, //< Extrapolation after the last knot
127  TsSourcePostExtrapLoop, //< Looped extrapolation after the last knot
128 };
129 
130 /// Inner-loop parameters.
131 ///
132 /// At most one inner-loop region can be specified per spline. Only whole
133 /// numbers of pre- and post-iterations are supported.
134 ///
135 /// The value offset specifies the difference between the values at the starts
136 /// of consecutive iterations.
137 ///
138 /// There must always be a knot at the protoStart time; otherwise the loop
139 /// parameters are invalid and will be ignored.
140 ///
141 /// A copy of the start knot is always made at the end of the prototype region.
142 /// This is true even if there is no post-looping; it ensures that all
143 /// iterations (including pre-loops) match the prototype region exactly.
144 ///
145 /// Enabling inner looping will generally change the shape of the prototype
146 /// interval (and thus all looped copies), because the first knot is echoed as
147 /// the last. Inner looping does not aim to make copies of an existing shape;
148 /// it aims to set up for continuity at loop joins.
149 ///
150 /// When inner looping is applied, any knots specified in the pre-looped or
151 /// post-looped intervals are removed from consideration, though they remain in
152 /// the spline parameters. A knot exactly at the end of the prototype interval
153 /// is not part of the prototype; it will be ignored, and overwritten by the
154 /// start-knot copy.
155 ///
156 /// When protoEnd <= protoStart, inner looping is disabled.
157 ///
158 /// Negative numbers of loops are not meaningful; they are treated the same as
159 /// zero counts. These quantities are signed only so that accidental underflow
160 /// does not result in huge loop counts.
161 ///
163 {
164 public:
165  TsTime protoStart = 0.0;
166  TsTime protoEnd = 0.0;
167  int32_t numPreLoops = 0;
168  int32_t numPostLoops = 0;
169  double valueOffset = 0.0;
170 
171 public:
172  TS_API
173  bool operator==(const TsLoopParams &other) const;
174 
175  TS_API
176  bool operator!=(const TsLoopParams &other) const;
177 
178  /// Returns the prototype region, [protoStart, protoEnd).
179  TS_API
181 
182  /// Returns the union of the prototype region and the echo region(s).
183  TS_API
185 };
186 
187 /// Extrapolation parameters for the ends of a spline beyond the knots.
188 ///
190 {
191 public:
193  double slope = 0.0;
194 
195 public:
196  TS_API
197  TsExtrapolation();
198 
199  TS_API
201 
202  TS_API
203  bool operator==(const TsExtrapolation &other) const;
204 
205  TS_API
206  bool operator!=(const TsExtrapolation &other) const;
207 
208  /// Returns whether our mode is one of the looping extrapolation modes.
209  TS_API
210  bool IsLooping() const;
211 };
212 
213 /// \brief \c TsSplineSamples<Vertex> holds a collection of piecewise linear
214 /// polylines that approximate a \c TsSpline.
215 ///
216 /// The vertex must be one of \c GfVec2d, \c GfVec2f, or \c GfVec2h. Note that
217 /// you may have precision or overflow issues if you use \c GfVec2h.
218 ///
219 /// \sa \ref TsSplineSamplesWithSources and \ref TsSpline::Sample
220 template <typename Vertex>
222 {
223 public:
224  static_assert(TsSplineIsValidSampleType<Vertex>,
225  "The Vertex template parameter to TsSplineSamples must be one"
226  " of GfVec2d, GfVec2f, or GfVec2h.");
227 
228  using Polyline = std::vector<Vertex>;
229 
230  std::vector<Polyline> polylines;
231 };
232 
233 /// \brief \c TsSplineSamplesWithSources<Vertex> is a \c TsSplineSamples<Vertex>
234 /// that also includes source information for each polyline.
235 ///
236 /// The vertex must be one of \c GfVec2d, \c GfVec2f, or \c GfVec2h. Note that
237 /// you may have precision or overflow issues if you use \c GfVec2h.
238 ///
239 /// The \c polylines and \c sources vectors are parallel arrays. In other words,
240 /// the source for the \c Polyline in \c polylines[i] is in \c sources[i] and
241 /// the two vectors have the same size.
242 /// \sa \ref TsSplineSamples and \ref TsSpline::SampleWithSources
243 template <typename Vertex>
245 {
246 public:
247  static_assert(TsSplineIsValidSampleType<Vertex>,
248  "The Vertex template parameter to TsSplineSamplesWithSources"
249  " must be one of GfVec2d, GfVec2f, or GfVec2h.");
250 
251  using Polyline = std::vector<Vertex>;
252 
253  std::vector<Polyline> polylines;
254  std::vector<TsSplineSampleSource> sources;
255 };
256 
257 // Declare sampling classes as extern templates. They are explicitly
258 // instantiated in types.cpp
259 #define TS_SAMPLE_EXTERN_IMPL(unused, tuple) \
260  TS_API_TEMPLATE_CLASS( \
261  TsSplineSamples< TS_SPLINE_VALUE_CPP_TYPE(tuple) >); \
262  TS_API_TEMPLATE_CLASS( \
263  TsSplineSamplesWithSources< TS_SPLINE_VALUE_CPP_TYPE(tuple) >);
265 #undef TS_SAMPLE_EXTERN_IMPL
266 
267 /// Modes for enforcing non-regression in splines.
268 ///
269 /// See \ref page_ts_regression for a general introduction to regression and
270 /// anti-regression.
271 ///
273 {
274  /// Do not enforce. If there is regression, runtime evaluation will use
275  /// KeepRatio.
277 
278  /// Prevent tangents from crossing neighboring knots. This guarantees
279  /// non-regression, but is slightly over-conservative, preventing the
280  /// authoring of some extreme curves that cannot be created without
281  /// non-contained tangents.
283 
284  /// If there is regression in a segment, shorten both of its tangents until
285  /// the regression is just barely prevented (the curve comes to a
286  /// near-standstill at some time). Preserve the ratio of the tangent
287  /// lengths.
289 
290  /// If there is regression in a segment, leave its start tangent alone, and
291  /// shorten its end tangent until the regression is just barely prevented.
292  /// This matches Maya behavior.
294 };
295 
296 
298 
299 #endif
TsAntiRegressionMode
Definition: types.h:272
TsSplineSamplesWithSources<Vertex> is a TsSplineSamples<Vertex> that also includes source information...
Definition: types.h:244
TS_API GfInterval GetLoopedInterval() const
Returns the union of the prototype region and the echo region(s).
std::vector< Vertex > Polyline
Definition: types.h:251
TsTime protoStart
Definition: types.h:165
TsSplineSampleSource
Definition: types.h:118
double slope
Definition: types.h:193
TF_PP_SEQ_FOR_EACH(_TS_SUPPORT_DATA_TYPE,~, TS_SPLINE_SUPPORTED_VALUE_TYPES) template< class T > inline const expr bool TsSplineIsValidSampleType
True if template parameter T is a supported spline sampling vertex type.
TS_API bool operator==(const TsExtrapolation &other) const
TS_API bool operator!=(const TsLoopParams &other) const
std::vector< Polyline > polylines
Definition: types.h:230
#define TS_SPLINE_SAMPLE_VERTEX_TYPES
Definition: types.h:34
TsCurveType
Definition: types.h:92
TS_API GfInterval GetPrototypeInterval() const
Returns the prototype region, [protoStart, protoEnd).
TS_API bool operator!=(const TsExtrapolation &other) const
TS_API bool IsLooping() const
Returns whether our mode is one of the looping extrapolation modes.
TS_API TsExtrapolation()
TsExtrapMode
Definition: types.h:101
#define TS_API
Definition: api.h:24
TsTime protoEnd
Definition: types.h:166
GLenum mode
Definition: glcorearb.h:99
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
int32_t numPreLoops
Definition: types.h:167
std::vector< TsSplineSampleSource > sources
Definition: types.h:254
int32_t numPostLoops
Definition: types.h:168
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
double valueOffset
Definition: types.h:169
TS_API bool operator==(const TsLoopParams &other) const
std::vector< Polyline > polylines
Definition: types.h:253
#define TS_SPLINE_SUPPORTED_VALUE_TYPES
Definition: types.h:29
TsSplineSamples<Vertex> holds a collection of piecewise linear polylines that approximate a TsSpline...
Definition: types.h:221
#define _TS_SUPPORT_DATA_TYPE(unused, tuple)
Definition: types.h:47
std::vector< Vertex > Polyline
Definition: types.h:228
TsInterpMode
Definition: types.h:82
#define TS_SAMPLE_EXTERN_IMPL(unused, tuple)
Definition: types.h:259
constexpr bool TsSplineIsValidDataType
True if template parameter T is a supported spline data type.
Definition: types.h:45
#define _TS_SUPPORT_SAMPLE_TYPE(unused, tuple)
Definition: types.h:62