timeline: reworked ripple/edit to behavior and documented some track behavior

app/node/output/track/track.cpp

@@ -225,6 +225,7 @@ QList<Block *> TrackOutput::BlocksAtTimeRange(const TimeRange &range) const
 
   foreach (Block* block, block_cache_) {
     if (block
+        && block->is_enabled()
         && block->out() > range.in()
         && block->in() < range.out()) {
       list.append(block);

app/node/output/track/track.h

@@ -57,29 +57,68 @@ public:
   const int& Index();
   void SetIndex(const int& index);
 
+  /**
+   * @brief Returns the block that starts BEFORE (not AT) and ends AFTER (not AT) a time
+   *
+   * Catches the first block that matches `block.in < time && block.out > time` or nullptr if any
+   * block starts/ends precisely at that time or the time exceeds the track length.
+   */
   Block* BlockContainingTime(const rational& time) const;
 
   /**
-   * @brief Returns the block that starts BEFORE a given time and ends some time AFTER or precisely AT that time
+   * @brief Returns the block that starts BEFORE a given time and ends either AFTER or AT that time
+   *
+   * @return Catches the first block that matches `block.out >= time` or nullptr if this time
+   * exceeds the track length.
    */
   Block* NearestBlockBefore(const rational& time) const;
 
   /**
-   * @brief Returns the block that starts BEFORE a given time OR the block that starts precisely at that time
+   * @brief Returns the block that starts BEFORE or AT a given time.
+   *
+   * @return Catches the first block that matches `block.out > time` or nullptr if this time
+   * exceeds the track length.
    */
   Block* NearestBlockBeforeOrAt(const rational& time) const;
 
   /**
-   * @brief Returns the block that starts either precisely AT a given time or the soonest block AFTER
+   * @brief Returns the block that starts either AT a given time or the soonest block AFTER
+   *
+   * @return Catches the first block that matches `block.in >= time` or nullptr if this time
+   * exceeds the track length.
    */
   Block* NearestBlockAfterOrAt(const rational& time) const;
 
   /**
    * @brief Returns the block that starts AFTER the given time (but never AT the given time)
+   *
+   * @return Catches the first block that matches `block.in > time` or nullptr if this time
+   * exceeds the track length.
    */
   Block* NearestBlockAfter(const rational& time) const;
 
+  /**
+   * @brief Returns the block that should be rendered/visible at a given time
+   *
+   * Use this for any video rendering or determining which block will actually be active at any
+   * time.
+   *
+   * @return Catches the first block that matches `block.in <= time && block.out > time`. Returns
+   * nullptr if the time exceeds the track length, the block active at this time is disabled, or
+   * if IsMuted() is true.
+   */
   Block* BlockAtTime(const rational& time) const;
+
+  /**
+   * @brief Returns a list of blocks that should be rendered/visible during a given time range
+   *
+   * Use this for audio rendering to determine all blocks that will be active throughout a range
+   * of time.
+   *
+   * @return Similar to BlockAtTime() but will match several blocks where
+   * `block.in < range.out && block.out > range.in`. Returns an empty list if IsMuted() or if
+   * `range.in >= track.length`. Blocks that are not enabled will be omitted from the returned list.
+   */
   QList<Block*> BlocksAtTimeRange(const TimeRange& range) const;
 
   const QList<Block *> &Blocks() const;

app/node/output/viewer/viewer.cpp

@@ -130,6 +130,20 @@ rational ViewerOutput::GetLength()
   return last_length_;
 }
 
+QVector<TrackOutput *> ViewerOutput::GetUnlockedTracks() const
+{
+  QVector<TrackOutput*> tracks = GetTracks();
+
+  for (int i=0;i<tracks.size();i++) {
+    if (tracks.at(i)->IsLocked()) {
+      tracks.removeAt(i);
+      i--;
+    }
+  }
+
+  return tracks;
+}
+
 void ViewerOutput::UpdateTrackCache()
 {
   track_cache_.clear();

app/node/output/viewer/viewer.h

@@ -85,6 +85,11 @@ public:
     return track_cache_;
   }
 
+  /**
+   * @brief Same as GetTracks() but omits tracks that are locked.
+   */
+  QVector<TrackOutput *> GetUnlockedTracks() const;
+
   NodeInput* track_input(Timeline::TrackType type) const {
     return track_inputs_.at(type);
   }