From 3478acfcf9bf0fce6969483ce2a45a6bc88e902e Mon Sep 17 00:00:00 2001 From: Mads Kiilerich Date: Fri, 18 Nov 2022 22:54:14 +0100 Subject: [PATCH] temporal: clarify timepos_t and timecnt_t comments It tooke me a while to get an understanding of this. It might also be helpful to others to make the description more explicit. --- libs/temporal/temporal/timeline.h | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/libs/temporal/temporal/timeline.h b/libs/temporal/temporal/timeline.h index 09e78965a7..5bac31e928 100644 --- a/libs/temporal/temporal/timeline.h +++ b/libs/temporal/temporal/timeline.h @@ -40,8 +40,16 @@ class timecnt_t; void dump_stats (std::ostream&); -/* 62 bit positional time value. Theoretically signed, but the intent is for to - * always be positive. If the flag bit is set (i.e. ::flagged() is true), the +/* A timepos_t designates an absolute position on the global timeline. It is + * measured since time zero, and it can thus only be positive. It is in one of + * two TimeDomains: AudioTime (wall time measured using superclock, + * proportional to sample count) or BeatTime (counting musical ticks, which are + * subdivided quarternotes or Beats). The ratio between these two is the tempo, + * which might change over time. Conversion between these time domains is thus + * non-trivial and will use the global TempoMap. + * + * Implemented using a 62 bit positional time value, a flag bit, and a sign bit. + * It is is intended to always be positive. If the flag bit is set (i.e. ::flagged() is true), the * numerical value counts musical ticks; otherwise it counts superclocks. */ @@ -57,7 +65,7 @@ class LIBTEMPORAL_API timepos_t : public int62_t { explicit timepos_t (timecnt_t const &); /* will throw() if val is negative */ - /* superclock_t and samplepos_t are the same underlying primitive type, + /* ticks are int64_t, and superclock_t and samplepos_t are both typedefs of int64_t, * which means we cannot use polymorphism to differentiate them. But it * turns out that we more or less never construct timepos_t from an * integer representing superclocks. So, there's a normal constructor @@ -272,12 +280,11 @@ class LIBTEMPORAL_API timepos_t : public int62_t { }; -/** - * a timecnt_t measures a duration in a specified time domain and starting at a - * specific position. - * - * It can be freely converted between time domains, as well as used as the - * subject of most arithmetic operations. +/* A timecnt_t (time count) designates a time distance (duration) with origin + * at a given absolute position on the global timeline (a timepos_t). It thus + * also designates an absolute end position. Both distance and position can + * independently be in one of two TimeDomains: AudioTime or BeatTime. + * Conversion between these time domains will use the global TempoMap. * * An important distinction between timepos_t and timecnt_t can be thought of * this way: a timepos_t ALWAYS refers to a position relative to the origin of