Represents the position of an object. More...

#include <src/dsp/position.h>

Inheritance diagram for zrythm::dsp::Position:

Public Member Functions
	Position (const char *str, int beats_per_bar, int sixteenths_per_beat, FramesPerTick frames_per_tick)
	Parses a position from the given string.
	Position (double ticks, dsp::FramesPerTick frames_per_tick)
	Construct from total number of ticks.
	Position (signed_frame_t frames, TicksPerFrame ticks_per_frame)
	Construct from total number of frames.
void	zero ()
signed_frame_t	get_total_frames () const
	Getter.
double	get_total_ticks () const
	Getter.
bool	ticks_equal (const Position &other) const
bool	is_positive () const
bool	is_between_frames_excluding_2nd (signed_frame_t f1, signed_frame_t f2) const
	Whether the position starts on or after `f1` and before `f2` (ie, the position is between `f1` and `f2`, exclusive of f2).
bool	is_between_excl_2nd (const Position &start, const Position &end) const
	Returns if the position is after or equal to `start` and before `end`.
bool	is_between_incl_2nd (const Position &start, const Position &end) const
	Returns if the position is after or equal to `start` and before or equal to `end` (ie, inclusive of `end`).
bool	is_between_excl_both (const Position &start, const Position &end) const
bool	is_between_excl_1st_incl_2nd (const Position &start, const Position &end) const
void	set_to_bar (int bar, int ticks_per_bar, dsp::FramesPerTick frames_per_tick)
	Sets position to given bar.
void	add_frames (signed_frame_t frames, TicksPerFrame ticks_per_frame)
	Adds the frames to the position and updates the rest of the fields, and makes sure the frames are still accurate.
void	from_seconds (double secs, sample_rate_t sample_rate, TicksPerFrame ticks_per_frame)
	Converts seconds to position and puts the result in the given Position.
void	from_frames (const signed_frame_t frames, TicksPerFrame ticks_per_frame)
void	from_ticks (double ticks, dsp::FramesPerTick frames_per_tick)
	Sets position to the given total tick count.
void	from_ms (const double ms, sample_rate_t sample_rate, TicksPerFrame ticks_per_frame)
void	from_bars (int bars, int ticks_per_bar, dsp::FramesPerTick frames_per_tick)
void	add_bars (int bars, int ticks_per_bar, dsp::FramesPerTick frames_per_tick)
void	add_beats (int beats, int ticks_per_beat, dsp::FramesPerTick frames_per_tick)
void	add_sixteenths (int sixteenths, dsp::FramesPerTick frames_per_tick)
void	add_ticks (double ticks, dsp::FramesPerTick frames_per_tick)
signed_ms_t	to_ms (sample_rate_t sample_rate) const
	Returns the Position in milliseconds.
void	add_ms (double ms, sample_rate_t sample_rate, TicksPerFrame ticks_per_frame)
void	add_minutes (int mins, sample_rate_t sample_rate, TicksPerFrame ticks_per_frame)
void	add_seconds (signed_sec_t seconds, sample_rate_t sample_rate, TicksPerFrame ticks_per_frame)
void	update_ticks_from_frames (TicksPerFrame ticks_per_frame)
	Updates ticks.
void	update_frames_from_ticks (FramesPerTick frames_per_tick)
	Updates frames.
void	set_to_midway_pos (const Position &start_pos, const Position &end_pos, FramesPerTick frames_per_tick)
	Sets the position to the midway point between the two given positions.
std::string	to_string (int beats_per_bar, int sixteenths_per_beat, FramesPerTick frames_per_tick, int decimal_places=4) const
	Creates a string in the form of "0.0.0.0" from the given position.
void	to_string (int beats_per_bar, int sixteenths_per_beat, FramesPerTick frames_per_tick, char *buf, int decimal_places=4) const
void	print (int beats_per_bar, int sixteenths_per_beat, FramesPerTick frames_per_tick) const
	Prints the Position in the "0.0.0.0" form.
int	get_total_bars (bool include_current, int ticks_per_bar, FramesPerTick frames_per_tick) const
	Returns the total number of beats.
int	get_total_beats (bool include_current, int beats_per_bar, int ticks_per_beat, FramesPerTick frames_per_tick) const
	Returns the total number of beats.
int	get_total_sixteenths (bool include_current, dsp::FramesPerTick frames_per_tick) const
	Returns the total number of sixteenths not including the current one.
void	change_sign ()
	Changes the sign of the position.
int	get_bars (bool start_at_one, int ticks_per_bar) const
	Gets the bars of the position.
int	get_beats (bool start_at_one, int beats_per_bar, int ticks_per_beat) const
	Gets the beats of the position.
int	get_sixteenths (bool start_at_one, int beats_per_bar, int sixteenths_per_beat, FramesPerTick frames_per_tick) const
	Gets the sixteenths of the position.
double	get_ticks_part (FramesPerTick frames_per_tick) const
	Gets the ticks of the position.
void	set_to_position (const Position &pos)
Position &	get_closest_position (Position &p1, Position &p2) const
	Returns the closest position.

Static Public Member Functions
static signed_frame_t	compare_frames (const Position &p1, const Position &p2)
	Compares 2 positions based on their frames.
static const Position &	get_min (const Position &p1, const Position &p2)
	Returns minimum of p1 and p2.
static const Position &	get_max (const Position &p1, const Position &p2)
	Returns maximum of p1 and p2.
static signed_frame_t	ms_to_frames (double ms, sample_rate_t sample_rate)
static double	ms_to_ticks (double ms, sample_rate_t sample_rate, TicksPerFrame ticks_per_frame)
static signed_frame_t	get_frames_from_ticks (double ticks, dsp::FramesPerTick frames_per_tick)
	Converts ticks to frames.
static void	print_range (int beats_per_bar, int sixteenths_per_beat, FramesPerTick frames_per_tick, const Position &p1, const Position &p2)

Data Fields
double	ticks_ = 0.0
	Precise total number of ticks.
signed_frame_t	frames_ = 0
	Position in frames (samples).

Static Public Attributes
static constexpr int	TICKS_PER_QUARTER_NOTE = 960
static constexpr int	TICKS_PER_SIXTEENTH_NOTE = 240
static constexpr double	TICKS_PER_QUARTER_NOTE_DBL = 960.0
static constexpr double	TICKS_PER_SIXTEENTH_NOTE_DBL = 240.0
static constexpr double	TICKS_PER_NINETYSIXTH_NOTE_DBL = 40.0
static constexpr int	POSITION_MAX_BAR = 160000

Friends
auto	operator<=> (const Position &lhs, const Position &rhs)
	Note: only checks frames.
bool	operator== (const Position &lhs, const Position &rhs)

Detailed Description

Represents the position of an object.

This class provides various methods for working with positions, including converting between ticks, frames, and other time units, as well as snapping positions to a grid.

The position is stored as both a precise number of ticks and a number of frames (samples). Most calculations should use the frames, while the ticks are used for more precise positioning.

The class also provides various comparison operators and utility functions for working with positions.

Definition at line 71 of file position.h.

Constructor & Destructor Documentation

◆ Position() [1/3]

zrythm::dsp::Position::Position	(	const char *	str,
		int	beats_per_bar,
		int	sixteenths_per_beat,
		FramesPerTick	frames_per_tick )

Parses a position from the given string.

Exceptions

ZrythmException if the string is invalid.

◆ Position() [2/3]

zrythm::dsp::Position::Position	(	double	ticks,
		dsp::FramesPerTick	frames_per_tick )

inline

Construct from total number of ticks.

Definition at line 97 of file position.h.

◆ Position() [3/3]

zrythm::dsp::Position::Position	(	signed_frame_t	frames,
		TicksPerFrame	ticks_per_frame )

inline

Construct from total number of frames.

Definition at line 103 of file position.h.

Member Function Documentation

◆ add_frames()

void zrythm::dsp::Position::add_frames	(	signed_frame_t	frames,
		TicksPerFrame	ticks_per_frame )

inline

Adds the frames to the position and updates the rest of the fields, and makes sure the frames are still accurate.

Definition at line 196 of file position.h.

◆ add_minutes()

void zrythm::dsp::Position::add_minutes	(	int	mins,
		sample_rate_t	sample_rate,
		TicksPerFrame	ticks_per_frame )

inline

Definition at line 283 of file position.h.

◆ add_ms()

void zrythm::dsp::Position::add_ms	(	double	ms,
		sample_rate_t	sample_rate,
		TicksPerFrame	ticks_per_frame )

inline

Definition at line 277 of file position.h.

◆ add_seconds()

void zrythm::dsp::Position::add_seconds	(	signed_sec_t	seconds,
		sample_rate_t	sample_rate,
		TicksPerFrame	ticks_per_frame )

inline

Definition at line 288 of file position.h.

◆ add_sixteenths()

void zrythm::dsp::Position::add_sixteenths	(	int	sixteenths,
		dsp::FramesPerTick	frames_per_tick )

inline

Definition at line 247 of file position.h.

◆ add_ticks()

void zrythm::dsp::Position::add_ticks	(	double	ticks,
		dsp::FramesPerTick	frames_per_tick )

inline

Definition at line 252 of file position.h.

◆ change_sign()

void zrythm::dsp::Position::change_sign ( )

inline

Changes the sign of the position.

For example, 4.2.1.21 would become -4.2.1.21.

Definition at line 401 of file position.h.

◆ compare_frames()

signed_frame_t zrythm::dsp::Position::compare_frames	(	const Position &	p1,
		const Position &	p2 )

inlinestatic

Compares 2 positions based on their frames.

negative = p1 is earlier 0 = equal positive = p2 is earlier

Definition at line 127 of file position.h.

◆ from_bars()

void zrythm::dsp::Position::from_bars	(	int	bars,
		int	ticks_per_bar,
		dsp::FramesPerTick	frames_per_tick )

inline

Definition at line 235 of file position.h.

◆ from_frames()

void zrythm::dsp::Position::from_frames	(	const signed_frame_t	frames,
		TicksPerFrame	ticks_per_frame )

inline

Definition at line 210 of file position.h.

◆ from_ms()

void zrythm::dsp::Position::from_ms	(	const double	ms,
		sample_rate_t	sample_rate,
		TicksPerFrame	ticks_per_frame )

inline

Definition at line 225 of file position.h.

◆ from_ticks()

void zrythm::dsp::Position::from_ticks	(	double	ticks,
		dsp::FramesPerTick	frames_per_tick )

inline

Sets position to the given total tick count.

Definition at line 219 of file position.h.

◆ get_bars()

int zrythm::dsp::Position::get_bars	(	bool	start_at_one,
		int	ticks_per_bar ) const

Gets the bars of the position.

Eg, if the position is equivalent to 4.1.2.42, this will return 4.

Parameters

start_at_one Start at 1 or -1 instead of 0.

◆ get_beats()

int zrythm::dsp::Position::get_beats	(	bool	start_at_one,
		int	beats_per_bar,
		int	ticks_per_beat ) const

Gets the beats of the position.

Eg, if the position is equivalent to 4.1.2.42, this will return 1.

Parameters

start_at_one Start at 1 or -1 instead of 0.

◆ get_closest_position()

Position & zrythm::dsp::Position::get_closest_position	(	Position &	p1,
		Position &	p2 ) const

inline

Returns the closest position.

Parameters

p1	Snap point 1.
p2	Snap point 2.

Definition at line 458 of file position.h.

◆ get_frames_from_ticks()

signed_frame_t zrythm::dsp::Position::get_frames_from_ticks	(	double	ticks,
		dsp::FramesPerTick	frames_per_tick )

static

Converts ticks to frames.

Parameters

frames_per_tick If zero, AudioEngine.frames_per_tick will be used instead.

◆ get_max()

const Position & zrythm::dsp::Position::get_max	(	const Position &	p1,
		const Position &	p2 )

inlinestatic

Returns maximum of p1 and p2.

Definition at line 145 of file position.h.

◆ get_min()

const Position & zrythm::dsp::Position::get_min	(	const Position &	p1,
		const Position &	p2 )

inlinestatic

Returns minimum of p1 and p2.

Definition at line 139 of file position.h.

◆ get_sixteenths()

int zrythm::dsp::Position::get_sixteenths	(	bool	start_at_one,
		int	beats_per_bar,
		int	sixteenths_per_beat,
		FramesPerTick	frames_per_tick ) const

Gets the sixteenths of the position.

Eg, if the position is equivalent to 4.1.2.42, this will return 2.

Parameters

start_at_one Start at 1 or -1 instead of 0.

◆ get_ticks_part()

double zrythm::dsp::Position::get_ticks_part ( FramesPerTick frames_per_tick ) const

Gets the ticks of the position.

Ie, if the position is equivalent to 4.1.2.42, this will return 42.

◆ get_total_bars()

int zrythm::dsp::Position::get_total_bars	(	bool	include_current,
		int	ticks_per_bar,
		FramesPerTick	frames_per_tick ) const

Returns the total number of beats.

Parameters

include_current Whether to count the current beat if it is at the beat start.

◆ get_total_beats()

int zrythm::dsp::Position::get_total_beats	(	bool	include_current,
		int	beats_per_bar,
		int	ticks_per_beat,
		FramesPerTick	frames_per_tick ) const

Returns the total number of beats.

Parameters

include_current Whether to count the current beat if it is at the beat start.

◆ get_total_frames()

signed_frame_t zrythm::dsp::Position::get_total_frames ( ) const

inline

Getter.

Definition at line 115 of file position.h.

◆ get_total_ticks()

double zrythm::dsp::Position::get_total_ticks ( ) const

inline

Getter.

Definition at line 118 of file position.h.

◆ is_between_excl_1st_incl_2nd()

bool zrythm::dsp::Position::is_between_excl_1st_incl_2nd	(	const Position &	start,
		const Position &	end ) const

inline

Definition at line 181 of file position.h.

◆ is_between_excl_2nd()

bool zrythm::dsp::Position::is_between_excl_2nd	(	const Position &	start,
		const Position &	end ) const

inline

Returns if the position is after or equal to start and before end.

Definition at line 163 of file position.h.

◆ is_between_excl_both()

bool zrythm::dsp::Position::is_between_excl_both	(	const Position &	start,
		const Position &	end ) const

inline

Definition at line 175 of file position.h.

◆ is_between_frames_excluding_2nd()

bool zrythm::dsp::Position::is_between_frames_excluding_2nd	(	signed_frame_t	f1,
		signed_frame_t	f2 ) const

inline

Whether the position starts on or after f1 and before f2 (ie, the position is between f1 and f2, exclusive of f2).

Definition at line 157 of file position.h.

◆ is_between_incl_2nd()

bool zrythm::dsp::Position::is_between_incl_2nd	(	const Position &	start,
		const Position &	end ) const

inline

Returns if the position is after or equal to start and before or equal to end (ie, inclusive of end).

Definition at line 170 of file position.h.

◆ is_positive()

bool zrythm::dsp::Position::is_positive ( ) const

inline

Definition at line 150 of file position.h.

◆ ms_to_ticks()

double zrythm::dsp::Position::ms_to_ticks	(	double	ms,
		sample_rate_t	sample_rate,
		TicksPerFrame	ticks_per_frame )

inlinestatic

Definition at line 266 of file position.h.

◆ set_to_midway_pos()

void zrythm::dsp::Position::set_to_midway_pos	(	const Position &	start_pos,
		const Position &	end_pos,
		FramesPerTick	frames_per_tick )

inline

Sets the position to the midway point between the two given positions.

Parameters

pos	Position to set to.

Definition at line 326 of file position.h.

◆ set_to_position()

void zrythm::dsp::Position::set_to_position ( const Position & pos )

inline

Definition at line 446 of file position.h.

◆ ticks_equal()

bool zrythm::dsp::Position::ticks_equal ( const Position & other ) const

inline

Definition at line 132 of file position.h.

◆ update_ticks_from_frames()

void zrythm::dsp::Position::update_ticks_from_frames ( TicksPerFrame ticks_per_frame )

Updates ticks.

Parameters

ticks_per_frame If zero, AudioEngine.ticks_per_frame will be used instead.

◆ zero()

void zrythm::dsp::Position::zero ( )

inline

Definition at line 108 of file position.h.

◆ operator<=>

auto operator<=>	(	const Position &	lhs,
		const Position &	rhs )

friend

Note: only checks frames.

Definition at line 469 of file position.h.

◆ operator==

bool operator==	(	const Position &	lhs,
		const Position &	rhs )

friend

Definition at line 474 of file position.h.

Field Documentation

◆ frames_

signed_frame_t zrythm::dsp::Position::frames_ = 0

Position in frames (samples).

This should be used in most calculations.

Definition at line 491 of file position.h.

◆ POSITION_MAX_BAR

int zrythm::dsp::Position::POSITION_MAX_BAR = 160000

staticconstexpr

Definition at line 79 of file position.h.

◆ ticks_

double zrythm::dsp::Position::ticks_ = 0.0

Precise total number of ticks.

Definition at line 484 of file position.h.

◆ TICKS_PER_NINETYSIXTH_NOTE_DBL

double zrythm::dsp::Position::TICKS_PER_NINETYSIXTH_NOTE_DBL = 40.0

staticconstexpr

Definition at line 78 of file position.h.

◆ TICKS_PER_QUARTER_NOTE

int zrythm::dsp::Position::TICKS_PER_QUARTER_NOTE = 960

staticconstexpr

Definition at line 74 of file position.h.

◆ TICKS_PER_QUARTER_NOTE_DBL

double zrythm::dsp::Position::TICKS_PER_QUARTER_NOTE_DBL = 960.0

staticconstexpr

Definition at line 76 of file position.h.

◆ TICKS_PER_SIXTEENTH_NOTE

int zrythm::dsp::Position::TICKS_PER_SIXTEENTH_NOTE = 240

staticconstexpr

Definition at line 75 of file position.h.

◆ TICKS_PER_SIXTEENTH_NOTE_DBL

double zrythm::dsp::Position::TICKS_PER_SIXTEENTH_NOTE_DBL = 240.0

staticconstexpr

Definition at line 77 of file position.h.

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

src/dsp/position.h

Public Member Functions

Static Public Member Functions

Data Fields

Static Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Position() [1/3]

◆ Position() [2/3]

◆ Position() [3/3]

Member Function Documentation

◆ add_frames()

◆ add_minutes()

◆ add_ms()

◆ add_seconds()

◆ add_sixteenths()

◆ add_ticks()

◆ change_sign()

◆ compare_frames()

◆ from_bars()

◆ from_frames()

◆ from_ms()

◆ from_ticks()

◆ get_bars()

◆ get_beats()

◆ get_closest_position()

◆ get_frames_from_ticks()

◆ get_max()

◆ get_min()

◆ get_sixteenths()

◆ get_ticks_part()

◆ get_total_bars()

◆ get_total_beats()

◆ get_total_frames()

◆ get_total_ticks()

◆ is_between_excl_1st_incl_2nd()

◆ is_between_excl_2nd()

◆ is_between_excl_both()

◆ is_between_frames_excluding_2nd()

◆ is_between_incl_2nd()

◆ is_positive()

◆ ms_to_ticks()

◆ set_to_midway_pos()

◆ set_to_position()

◆ ticks_equal()

◆ update_ticks_from_frames()

◆ zero()

Friends And Related Symbol Documentation

◆ operator<=>

◆ operator==

Field Documentation

◆ frames_

◆ POSITION_MAX_BAR

◆ ticks_

◆ TICKS_PER_NINETYSIXTH_NOTE_DBL

◆ TICKS_PER_QUARTER_NOTE

◆ TICKS_PER_QUARTER_NOTE_DBL

◆ TICKS_PER_SIXTEENTH_NOTE

◆ TICKS_PER_SIXTEENTH_NOTE_DBL