Maintains the mapping between clip-native content ticks and project timeline ticks. More...

#include <src/dsp/content_time_warp.h>

Inheritance diagram for zrythm::dsp::ContentTimeWarp:

Collaboration diagram for zrythm::dsp::ContentTimeWarp:

Data Structures
struct	WarpPoint

Signals
void	mapChanged ()

Public Member Functions
	ContentTimeWarp (const TempoMapWrapper &tempo_map_wrapper, const TimelinePosition clip_position, const ContentPosition clip_length, QObject *parent=nullptr)
std::span< const WarpPoint >	warpPoints () const
TimelineTick	contentToTimeline (ContentTick content) const
	Convert content ticks to ABSOLUTE timeline ticks.
Q_INVOKABLE double	contentToTimelineTicksRelative (double contentTicks) const
	Convert content ticks to timeline ticks RELATIVE to the clip's start position.
Q_INVOKABLE double	timelineTicksRelativeToContent (double timelineTicksRelative) const
	Convert timeline ticks RELATIVE to the clip's start position back to content ticks.
units::sample_t	contentToTimelineSamples (ContentTick content) const
	Convert content ticks to ABSOLUTE timeline samples.
ContentTick	timelineToContent (TimelineTick timeline) const
	Convert ABSOLUTE timeline ticks to content ticks.
void	configure_as_project (units::bpm_t source_bpm=units::bpm(0.0))
	Configures Project mode (identity warp — clip follows project tempo).
void	configure_as_source (units::bpm_t source_bpm)
void	configure_as_warped (units::bpm_t source_bpm, std::span< const WarpPoint > user_markers)
bool	is_identity () const
	Returns true if the warp mapping is 1:1 (no timestretch needed).

Detailed Description

Maintains the mapping between clip-native content ticks and project timeline ticks.

Warp points store timeline DELTA ticks (offset from clip start), not absolute positions. contentToTimeline() adds clip_position.ticks() to produce absolute timeline positions.

Empty warp point list means identity delta (content ticks map 1:1 to timeline delta ticks). This is the default for MIDI clips and audio clips in musical mode ON.

contentToTimeline() and contentToTimelineSamples() return ABSOLUTE timeline positions (measured from the timeline origin at 0, not relative to the clip start). contentToTimelineTicksRelative() returns the warp delta only (timeline ticks relative to the clip start).

Main-thread only — not real-time safe.

Definition at line 39 of file content_time_warp.h.

Member Function Documentation

◆ configure_as_project()

void zrythm::dsp::ContentTimeWarp::configure_as_project ( units::bpm_t source_bpm = units::bpm(0.0) )

Configures Project mode (identity warp — clip follows project tempo).

When source_bpm > 0, identity warp points are generated so that to_time_warp_map can derive the sample-space stretch mapping. When source_bpm == 0 (e.g. unknown BPM or MIDI clips), the warp point list stays empty — positioning works but no rendering is possible.

◆ contentToTimeline()

TimelineTick zrythm::dsp::ContentTimeWarp::contentToTimeline ( ContentTick content ) const

Convert content ticks to ABSOLUTE timeline ticks.

Returns the position measured from the timeline origin (tick 0), NOT relative to the clip's start. Computed as: clip_position.ticks() + warp_lookup(content_ticks)

Null-safe in Project/Warped modes: if clip_position is null, treats the clip start as tick 0. Source mode requires clip_position to be non-null (see source_content_to_timeline).

Note: Main-thread only. Traverses warp_points_, which is mutated by rebuild() on the main thread — not real-time safe, no synchronization.

◆ contentToTimelineSamples()

units::sample_t zrythm::dsp::ContentTimeWarp::contentToTimelineSamples ( ContentTick content ) const

Convert content ticks to ABSOLUTE timeline samples.

Returns the sample position measured from the timeline origin (sample 0), NOT relative to the clip's start.

Note: Main-thread only (see contentToTimeline).

◆ contentToTimelineTicksRelative()

Q_INVOKABLE double zrythm::dsp::ContentTimeWarp::contentToTimelineTicksRelative ( double contentTicks ) const

Convert content ticks to timeline ticks RELATIVE to the clip's start position.

Returns only the warp delta (the stretched/compressed offset from the clip start), without adding the clip's absolute position. Used for positioning items inside a clip view.

◆ is_identity()

bool zrythm::dsp::ContentTimeWarp::is_identity ( ) const

Returns true if the warp mapping is 1:1 (no timestretch needed).

Empty warp points (Project mode) or all-delta-equals-content points mean the clip plays at native speed.

◆ timelineTicksRelativeToContent()

Q_INVOKABLE double zrythm::dsp::ContentTimeWarp::timelineTicksRelativeToContent ( double timelineTicksRelative ) const

Convert timeline ticks RELATIVE to the clip's start position back to content ticks.

The inverse of contentToTimelineTicksRelative. Given a position expressed as a timeline offset from the clip start (the warp delta), returns the corresponding position within the clip's content. Used to map mouse positions in a clip-editor ruler back onto the clip's content coordinate space.

Note: Main-thread only (delegates to timelineToContent).

◆ timelineToContent()

ContentTick zrythm::dsp::ContentTimeWarp::timelineToContent ( TimelineTick timeline ) const

Convert ABSOLUTE timeline ticks to content ticks.

The inverse of contentToTimeline. Given a position on the timeline, returns the corresponding position within the clip's content.

Note: Main-thread only (see contentToTimeline).

◆ warpPoints()

std::span< const WarpPoint > zrythm::dsp::ContentTimeWarp::warpPoints ( ) const

inline

Definition at line 59 of file content_time_warp.h.

The documentation for this class was generated from the following file:

src/dsp/content_time_warp.h

Data Structures

Signals

Public Member Functions