UDocumentation UE5.7 10.02.2026 (Source)
API documentation for Unreal Engine 5.7
MovieSceneSequenceTransform.h
Go to the documentation of this file.
1// Copyright Epic Games, Inc. All Rights Reserved.
2
3#pragma once
4
6#include "Containers/Array.h"
7#include "MovieSceneFwd.h"
9#include "Misc/FrameNumber.h"
10#include "Misc/FrameTime.h"
14
15#include "MovieSceneSequenceTransform.generated.h"
16
17template<typename> class TRange;
18
22
23namespace UE::MovieScene
24{
25 struct FInverseTransformTimeParams;
26 struct FTransformTimeParams;
27
28 enum class ETimeWarpChannelDomain : uint8;
29}
30
31
32/*~
33 * This file contains the structures necessary for representing transformations of time between various different
34 * 'spaces' within the Sequencer/MovieScene codebase. Typically these spaces denote root and sub-sequences,
35 * or sub-sub-suquences. 'Lossy' transformations (ie, transformations that are mathematically non-linear)
36 * are supported and typically referred to as 'warping' or 'non-linear' transforms. Such transforms are always
37 * stored as a stack of nested FMovieSceneNestedSequenceTransform structures and cannot be combined mathematically
38 * like FMovieSceneTimeTransform can.
39 *
40 * When dealing with time transformations, it is common to use the following nomenclature interchangably:
41 * - Outer, Untransformed, Unwarped space; and,
42 * - Inner, Transformed, Warped space.
43 *
44 * Inverse transformations are also supported, but via a different, more restrictive API. Where outer->inner transforms
45 * must always map an outer time to an inner time, inverse transformations can fail. This is clearly the case when
46 * attempting to inverse-transform a time of 20 from a loop that only spans [0, 10). The requested time is not present
47 * in the set of times that can result from the outer->inner transform, and so the operation fails.
48 * Similarly, inverse transformations may have zero or more real solutions. Consider the previous example, but with a
49 * time of 5; the operation has an infinite number of solutions (one for each loop, or every t where t%5==0).
50 *
51 * ________ << FMovieSceneInverseSequenceTransform << ___________
52 * / \
53 * ---------------------- -----------------------
54 * | Untransformed space | | Transformed space |
55 * ----------------------- -----------------------
56 * \_____________ >> FMovieSceneSequenceTransform >> _____________/
57 */
58
59
63UENUM()
71
75USTRUCT()
77{
79
80
86
87
92 {
93 return Breadcrumbs[Index];
94 }
95
96
100 int32 Num() const
101 {
102 return Breadcrumbs.Num();
103 }
104
105
110 {
111 return Breadcrumbs.IsValidIndex(Index);
112 }
113
114
118 bool IsSparse() const
119 {
121 }
122
123
128 {
129 return Mode;
130 }
131
132
136 void Reset()
137 {
138 Breadcrumbs.Reset();
139 }
140
141
146 {
147 Breadcrumbs.Add(Breadcrumb);
148 }
149
150
155 {
156 return Breadcrumbs.Pop();
157 }
158
159
164 {
165 // Append the outer breadcrumbs to the head of this list
166 Breadcrumbs.Insert(OuterBreadcrumbs.Breadcrumbs, 0);
167 }
168
169
174 {
176 Result.Breadcrumbs.SetNum(Breadcrumbs.Num());
177 for (FFrameTime& X : Result.Breadcrumbs)
178 {
179 X = InTime;
180 }
181 return Result;
182 }
183
184public:
185
187 TArray<FFrameTime>::RangedForConstIteratorType end () const { return Breadcrumbs.end(); }
188
190
191private:
192
193 UPROPERTY()
194 TArray<FFrameTime> Breadcrumbs;
195
196 UPROPERTY()
198};
199
200
201USTRUCT()
203{
205
206public:
207
209
212
215
217
218 UE_DEPRECATED(5.5, "This function is no longer used. Please update your code to use time-based breadcrumbs instead.")
219 void AddWarpingLevel(uint32 WarpCount)
220 {
221 }
222
223 UE_DEPRECATED(5.5, "This function is no longer used. Please update your code to use time-based breadcrumbs instead.")
224 void AddNonWarpingLevel()
225 {
226 }
227
228 UE_DEPRECATED(5.5, "This function is no longer used. Please update your code to use time-based breadcrumbs instead.")
229 int32 NumWarpCounts() const
230 {
231 return 0;
232 }
233
234 UE_DEPRECATED(5.5, "This function is no longer used. Please update your code to use time-based breadcrumbs instead.")
235 uint32 LastWarpCount() const
236 {
237 return (uint32)(-1);
238 }
239
240 UE_DEPRECATED(5.5, "Warp counts are no longer supported.")
241 TArray<uint32> WarpCounts;
242};
243
244
250USTRUCT()
252{
254
255
260
261
268
269
270
275 : TimeScale(InTimeScale), Offset(InOffset)
276 {}
277
278
279public:
280
281
285 bool IsLinear() const
286 {
287 return TimeScale.GetType() == EMovieSceneTimeWarpType::FixedPlayRate;
288 }
289
290
295 bool NeedsBreadcrumb() const
296 {
297 return !IsLinear();
298 }
299
300
306
307
312
313
323
324
335
336
347 MOVIESCENE_API bool TransformTimeWithinRange(FFrameTime Time, const TFunctionRef<bool(FFrameTime)>& Visitor, FFrameTime UntransformedRangeStart, FFrameTime UntransformedRangeEnd) const;
348
349private:
350
352
354 UPROPERTY()
356
358 UPROPERTY()
360};
361
362
363
369USTRUCT()
371{
373
374
375
379
382
385
387
396
397
404
405
410 : TimeScale(InTimeScale), Offset(InOffset)
411 {}
412
413
418 : TimeScale(MoveTemp(InTimeScale)), Offset(InOffset)
419 {
420 TimeScale.MakeWeakUnsafe();
421 }
422
423
424public:
425
426
430 bool IsLinear() const
431 {
432 return TimeScale.GetType() == EMovieSceneTimeWarpType::FixedPlayRate;
433 }
434
435
441 {
442 return FMovieSceneTimeTransform(Offset, TimeScale.AsFixedPlayRateFloat());
443 }
444
445
450 bool NeedsBreadcrumb() const
451 {
452 return !IsLinear();
453 }
454
455
459 bool IsIdentity() const
460 {
461 return Offset == 0 && TimeScale.GetType() == EMovieSceneTimeWarpType::FixedPlayRate && TimeScale.AsFixedPlayRate() == 1.0;
462 }
463
464
472 MOVIESCENE_API FFrameTime TransformTime(FFrameTime Time) const;
473
474
484
485
490
491
501 MOVIESCENE_API TRange<FFrameTime> ComputeTraversedHull(const TRange<FFrameTime>& Range) const;
502
503
508 MOVIESCENE_API bool SupportsBoundaries() const;
509
510
515
516
527 MOVIESCENE_API bool ExtractBoundariesWithinRange(const TRange<FFrameTime>& UntransformedRange, const TFunctionRef<bool(FFrameTime)>& Visitor) const;
528
529
534
535
540 {
541 return A.TimeScale == B.TimeScale && A.Offset == B.Offset;
542 }
543
544
549 {
550 return A.TimeScale != B.TimeScale || A.Offset != B.Offset;
551 }
552
553 /*~ Begin StructOpsTypeTraits */
554 void PostSerialize(const FArchive& Ar);
555 /*~ End StructOpsTypeTraits */
556
557private:
558
562 UPROPERTY()
564
568 UPROPERTY()
570
571public:
572
573 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Begin API deprecation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
574 UE_DEPRECATED(5.5, "Please update your code to use a FMovieSceneTimeWarpVariant")
578
579 UE_DEPRECATED(5.5, "Please update your code to use a FMovieSceneTimeWarpVariant")
584
585 UE_DEPRECATED(5.5, "Please update your code to check for IsLinear()")
586 bool IsLooping() const
587 {
588 return TimeScale.GetType() == EMovieSceneTimeWarpType::Loop;
589 }
590
591 UE_DEPRECATED(5.5, "Please use Inverse()")
592 FMovieSceneNestedSequenceTransform InverseLinearOnly() const
593 {
594 return IsLinear() ? AsLinear().Inverse() : FMovieSceneNestedSequenceTransform();
595 }
596
597 UE_DEPRECATED(5.5, "Please use Inverse()")
599 {
600 return IsLinear() ? AsLinear().Inverse() : FMovieSceneNestedSequenceTransform();
601 }
602
603 UE_DEPRECATED(5.5, "Warping is now implemented as a variant within TimeScale")
605 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ End API deprecation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
606};
607template<>
615
616
617
618
623USTRUCT()
625{
627
628
629
634
642 : LinearTransform(InOffset, InTimeScale)
643 {}
644
645
654
655
662 {
663 if (InNestedTransform.IsLinear())
664 {
665 LinearTransform = InNestedTransform.AsLinear();
666 }
667 else
668 {
669 NestedTransforms.Emplace(InNestedTransform);
670 }
671 }
672
673
678 {
679 return A.LinearTransform == B.LinearTransform && A.NestedTransforms == B.NestedTransforms;
680 }
681
682
687 {
688 return A.LinearTransform != B.LinearTransform || A.NestedTransforms != B.NestedTransforms;
689 }
690
691
695 bool NeedsBreadcrumbs() const
696 {
697 return !IsLinear();
698 }
699
700
704 bool IsLinear() const
705 {
706 return NestedTransforms.Num() == 0;
707 }
708
709
715 {
716 return LinearTransform;
717 }
718
719
723 MOVIESCENE_API bool IsIdentity() const;
724
725
733 MOVIESCENE_API FFrameTime TransformTime(FFrameTime Time) const;
734
735
745
746
756 MOVIESCENE_API TRange<FFrameTime> ComputeTraversedHull(const TRange<FFrameTime>& Range) const;
757
758
763 MOVIESCENE_API TRange<FFrameTime> ComputeTraversedHull(const TRange<FFrameNumber>& Range) const;
764
765
770
771
772public:
773
774
779
780
781
786
787
792
793
801 MOVIESCENE_API void AddLoop(FFrameNumber Start, FFrameNumber End);
802
803
810
811
817
818
823
824
836 MOVIESCENE_API bool ExtractBoundariesWithinRange(FFrameTime UntransformedStart, FFrameTime UntransformedEnd, const TFunctionRef<bool(FFrameTime)>& Visitor) const;
837
838 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Begin API deprecation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
839 UE_DEPRECATED(5.5, "This function is no longer supported. Please use !IsLinear()")
840 bool IsLooping() const;
841 UE_DEPRECATED(5.5, "Please upgrade your code to use TransformTime that takes breadcrumbs")
843 UE_DEPRECATED(5.5, "Transforms no longer have a constant time scale.")
844 MOVIESCENE_API float GetTimeScale() const;
845 UE_DEPRECATED(5.5, "Please use ComputeTraversedHull or TransformTime")
846 MOVIESCENE_API TRange<FFrameTime> TransformRangePure(const TRange<FFrameTime>& Range) const;
847 UE_DEPRECATED(5.5, "Please use ComputeTraversedHull or TransformTime")
848 MOVIESCENE_API TRange<FFrameTime> TransformRangeUnwarped(const TRange<FFrameTime>& Range) const;
849 UE_DEPRECATED(5.5, "Please use ComputeTraversedHull or TransformTime")
850 MOVIESCENE_API TRange<FFrameTime> TransformRangeConstrained(const TRange<FFrameTime>& Range) const;
851 UE_DEPRECATED(5.5, "Please use ComputeTraversedHull or TransformTime")
852 MOVIESCENE_API TRange<FFrameNumber> TransformRangePure(const TRange<FFrameNumber>& Range) const;
853 UE_DEPRECATED(5.5, "Please use ComputeTraversedHull or TransformTime")
854 MOVIESCENE_API TRange<FFrameNumber> TransformRangeUnwarped(const TRange<FFrameNumber>& Range) const;
855 UE_DEPRECATED(5.5, "Please use ComputeTraversedHull or TransformTime")
856 MOVIESCENE_API TRange<FFrameNumber> TransformRangeConstrained(const TRange<FFrameNumber>& Range) const;
857 UE_DEPRECATED(5.5, "Please use Inverse()")
858 MOVIESCENE_API FMovieSceneSequenceTransform InverseNoLooping() const;
859 UE_DEPRECATED(5.4, "Please use InverseNoLooping instead.")
860 MOVIESCENE_API FMovieSceneTimeTransform InverseLinearOnly() const;
861 UE_DEPRECATED(5.4, "Please use InverseFromAllFirstLoops instead.")
862 MOVIESCENE_API FMovieSceneTimeTransform InverseFromAllFirstWarps() const;
863 UE_DEPRECATED(5.4, "Please use InverseFromLoop instead.")
865 UE_DEPRECATED(5.4, "Please use InverseFromLoop instead.")
866 MOVIESCENE_API FMovieSceneTimeTransform InverseFromWarp(const TArrayView<const uint32>& WarpCounts) const;
867 UE_DEPRECATED(5.5, "Please use Inverse()")
868 MOVIESCENE_API FMovieSceneSequenceTransform InverseFromAllFirstLoops() const;
869 UE_DEPRECATED(5.5, "Please use Inverse()")
871 UE_DEPRECATED(5.5, "Please use Inverse()")
872 FMovieSceneSequenceTransform InverseFromLoop(const TArrayView<const FFrameTime>& Breadcrumbs) const;
873 UE_DEPRECATED(5.5, "Please use Inverse()")
874 MOVIESCENE_API FMovieSceneSequenceTransform InverseFromLoop(const TArrayView<const uint32>& LoopCounts) const;
875 /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ End API deprecation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~*/
876
880 UPROPERTY()
882
887 UPROPERTY()
889};
890
891
892
910USTRUCT()
912{
914
915
916
919 bool IsLinear() const
920 {
921 return NestedTransforms.Num() == 0;
922 }
923
924
929 {
930 check(IsLinear());
931 return LinearTransform;
932 }
933
934
945 MOVIESCENE_API TOptional<FFrameTime> TryTransformTime(FFrameTime Time, const FMovieSceneTransformBreadcrumbs& Breadcrumbs) const;
946
947
960
961
974 MOVIESCENE_API TOptional<FFrameTime> TryTransformTime(FFrameTime Time) const;
975
976
991
1005 MOVIESCENE_API bool TransformTimeWithinRange(FFrameTime Time, const TFunctionRef<bool(FFrameTime)>& Visitor, const FMovieSceneTransformBreadcrumbs& StartBreadcrumbs, const FMovieSceneTransformBreadcrumbs& EndBreadcrumbs) const;
1006
1007
1021 MOVIESCENE_API bool TransformFiniteRangeWithinRange(const TRange<FFrameTime>& Range, TFunctionRef<bool(TRange<FFrameTime>)> Visitor, const FMovieSceneTransformBreadcrumbs& StartBreadcrumbs, const FMovieSceneTransformBreadcrumbs& EndBreadcrumbs) const;
1022
1023
1027 UE_DEPRECATED(5.5, "This function is no longer supported. Please use FMovieSceneInverseSequenceTransform directly.")
1028 MOVIESCENE_API FMovieSceneTimeTransform AsLegacyLinearTimeTransform() const;
1029
1030private:
1031
1032
1036 bool RecursiveTransformTimeWithinRange(int32 NestingIndex, FFrameTime Time, const TFunctionRef<bool(FFrameTime)>& FinalVisitor, TArrayView<const FFrameTime> StartBreadcrumbs, TArrayView<const FFrameTime> EndBreadcrumbs) const;
1037
1038private:
1039
1041
1042
1046 UPROPERTY()
1047 FMovieSceneTimeTransform LinearTransform;
1048
1049
1054 UPROPERTY()
1056};
1057
1065
1073{
1074 InTime = InTime * RHS;
1075 return InTime;
1076}
1077
1080
OODEFFUNC typedef void(OODLE_CALLBACK t_fp_OodleCore_Plugin_Free)(void *ptr)
EGLSurface EGLnsecsANDROID time
Definition AndroidOpenGLFunctions.h:9
#define check(expr)
Definition AssertionMacros.h:314
#define UE_DEPRECATED(Version, Message)
Definition CoreMiscDefines.h:302
FPlatformTypes::int32 int32
A 32-bit signed integer.
Definition Platform.h:1125
UE_FORCEINLINE_HINT TSharedRef< CastToType, Mode > StaticCastSharedRef(TSharedRef< CastFromType, Mode > const &InSharedRef)
Definition SharedPointer.h:127
#define X(Name, Desc)
Definition FormatStringSan.h:47
FString LexToString(const FMovieSceneSequenceTransform &InTransform)
Definition MovieSceneSequenceTransform.cpp:71
MOVIESCENE_API FFrameTime operator*(FFrameTime InTime, const FMovieSceneSequenceTransform &RHS)
Definition MovieSceneSequenceTransform.cpp:119
EMovieSceneBreadcrumbMode
Definition MovieSceneSequenceTransform.h:65
const bool
Definition NetworkReplayStreaming.h:178
#define UPROPERTY(...)
UObject definition macros.
Definition ObjectMacros.h:744
#define GENERATED_BODY(...)
Definition ObjectMacros.h:765
#define UENUM(...)
Definition ObjectMacros.h:749
#define USTRUCT(...)
Definition ObjectMacros.h:746
UE_INTRINSIC_CAST UE_REWRITE constexpr std::remove_reference_t< T > && MoveTemp(T &&Obj) noexcept
Definition UnrealTemplate.h:520
uint32 Offset
Definition VulkanMemory.cpp:4033
uint8_t uint8
Definition binka_ue_file_header.h:8
uint32_t uint32
Definition binka_ue_file_header.h:6
Definition Archive.h:1208
Definition UnrealType.h:3087
Definition ArrayView.h:139
Definition Array.h:670
UE_NODEBUG UE_FORCEINLINE_HINT RangedForIteratorType end()
Definition Array.h:3391
UE_NODEBUG UE_FORCEINLINE_HINT RangedForIteratorType begin()
Definition Array.h:3389
Definition AssetRegistryState.h:50
Definition Range.h:50
Definition StringBuilder.h:79
Definition ConstraintsManager.h:14
ETimeWarpChannelDomain
Definition MovieSceneTimeWarpChannel.h:15
U16 Index
Definition radfft.cpp:71
Definition FrameNumber.h:18
Definition FrameTime.h:16
Definition MovieSceneSequenceTransform.h:252
MOVIESCENE_API FMovieSceneNestedSequenceTransform Inverse() const
FMovieSceneInverseNestedSequenceTransform(const FFrameTime &InOffset, double InTimeScale)
Definition MovieSceneSequenceTransform.h:274
bool NeedsBreadcrumb() const
Definition MovieSceneSequenceTransform.h:295
FMovieSceneInverseNestedSequenceTransform(const FMovieSceneTimeTransform &InLinearTransform)
Definition MovieSceneSequenceTransform.h:265
bool IsLinear() const
Definition MovieSceneSequenceTransform.h:285
Definition MovieSceneSequenceTransform.h:912
FMovieSceneTimeTransform AsLinear() const
Definition MovieSceneSequenceTransform.h:928
Definition MovieSceneSequenceTransform.h:371
FMovieSceneNestedSequenceTransform(FFrameTime InOffset, FMovieSceneTimeWarpVariant &&InTimeScale)
Definition MovieSceneSequenceTransform.h:417
friend bool operator!=(const FMovieSceneNestedSequenceTransform &A, const FMovieSceneNestedSequenceTransform &B)
Definition MovieSceneSequenceTransform.h:548
bool NeedsBreadcrumb() const
Definition MovieSceneSequenceTransform.h:450
MOVIESCENE_API FMovieSceneInverseNestedSequenceTransform Inverse() const
Definition MovieSceneSequenceTransform.cpp:434
bool IsIdentity() const
Definition MovieSceneSequenceTransform.h:459
friend bool operator==(const FMovieSceneNestedSequenceTransform &A, const FMovieSceneNestedSequenceTransform &B)
Definition MovieSceneSequenceTransform.h:539
bool IsLinear() const
Definition MovieSceneSequenceTransform.h:430
FMovieSceneTimeTransform AsLinear() const
Definition MovieSceneSequenceTransform.h:440
FMovieSceneNestedSequenceTransform(FFrameTime InOffset, double InTimeScale)
Definition MovieSceneSequenceTransform.h:409
FMovieSceneNestedSequenceTransform(const FMovieSceneTimeTransform &InLinearTransform)
Definition MovieSceneSequenceTransform.h:401
Definition MovieSceneSequenceTransform.h:625
friend bool operator!=(const FMovieSceneSequenceTransform &A, const FMovieSceneSequenceTransform &B)
Definition MovieSceneSequenceTransform.h:686
FMovieSceneSequenceTransform(FMovieSceneNestedSequenceTransform &&InNestedTransform)
Definition MovieSceneSequenceTransform.h:661
friend bool operator==(const FMovieSceneSequenceTransform &A, const FMovieSceneSequenceTransform &B)
Definition MovieSceneSequenceTransform.h:677
bool NeedsBreadcrumbs() const
Definition MovieSceneSequenceTransform.h:695
FMovieSceneSequenceTransform(FFrameTime InOffset, float InTimeScale=1.f)
Definition MovieSceneSequenceTransform.h:641
FMovieSceneTimeTransform AsLinear() const
Definition MovieSceneSequenceTransform.h:714
bool IsLinear() const
Definition MovieSceneSequenceTransform.h:704
FMovieSceneSequenceTransform(FMovieSceneTimeTransform InLinearTransform)
Definition MovieSceneSequenceTransform.h:651
Definition MovieSceneTimeTransform.h:23
Definition MovieSceneTimeWarpVariant.h:51
void MakeWeakUnsafe()
Definition MovieSceneTimeWarpVariant.h:200
Definition MovieSceneTimeWarping.h:24
Definition MovieSceneSequenceTransform.h:77
bool IsSparse() const
Definition MovieSceneSequenceTransform.h:118
FFrameTime PopBreadcrumb()
Definition MovieSceneSequenceTransform.h:154
void Reset()
Definition MovieSceneSequenceTransform.h:136
void CombineWithOuterBreadcrumbs(const FMovieSceneTransformBreadcrumbs &OuterBreadcrumbs)
Definition MovieSceneSequenceTransform.h:163
EMovieSceneBreadcrumbMode GetMode() const
Definition MovieSceneSequenceTransform.h:127
bool IsValidIndex(int32 Index) const
Definition MovieSceneSequenceTransform.h:109
FMovieSceneTransformBreadcrumbs OverwriteWith(FFrameTime InTime) const
Definition MovieSceneSequenceTransform.h:173
FFrameTime operator[](int32 Index) const
Definition MovieSceneSequenceTransform.h:91
int32 Num() const
Definition MovieSceneSequenceTransform.h:100
void AddBreadcrumb(const FFrameTime &Breadcrumb)
Definition MovieSceneSequenceTransform.h:145
TArray< FFrameTime >::RangedForConstIteratorType end() const
Definition MovieSceneSequenceTransform.h:187
TArray< FFrameTime >::RangedForConstIteratorType begin() const
Definition MovieSceneSequenceTransform.h:186
Definition MovieSceneSequenceTransform.h:203
MOVIESCENE_API FMovieSceneWarpCounter(FMovieSceneWarpCounter &&)
MOVIESCENE_API FMovieSceneWarpCounter()
MOVIESCENE_API ~FMovieSceneWarpCounter()
MOVIESCENE_API FMovieSceneWarpCounter & operator=(FMovieSceneWarpCounter &&)
MOVIESCENE_API FMovieSceneWarpCounter(const FMovieSceneWarpCounter &)
MOVIESCENE_API FMovieSceneWarpCounter & operator=(const FMovieSceneWarpCounter &)
Definition Array.h:206
Definition Optional.h:131
Definition StructOpsTypeTraits.h:11
Definition StructOpsTypeTraits.h:46
Definition MovieSceneTransformTypes.h:78
Definition MovieSceneTransformTypes.h:33