-/** Get a frame from this filter.
-
- The logic is complex here. A transition is applied to frames on the a and b tracks
- specified in the connect method above. Since all frames are obtained via this
- method for all tracks, we have to take special care that we only obtain the a and
- b frames once - we do this on the first call to get a frame from either a or b.
-
- After that, we have 2 cases to resolve:
-
- 1) if the track is the a_track and we're in the time zone, then we need to call the
- process method to do the effect on the frame and remember we've passed it on
- otherwise, we pass on the a_frame unmolested;
- 2) For all other tracks, we get the frames on demand.
-*/
+/** Get a frame from a transition.
+
+ The logic is complex here. A transition is typically applied to frames on the a and
+ b tracks specified in the connect method above and only if both contain valid info
+ for the transition type (this is either audio or image).
+
+ However, the fixed a_track may not always contain data of the correct type, eg:
+<pre>
+ +---------+ +-------+
+ |c1 | |c5 | <-- A(0,1) <-- B(0,2) <-- get frame
+ +---------+ +---------+-+-----+ | |
+ |c4 | <------+ |
+ +----------+-----------+-+---------+ |
+ |c2 |c3 | <-----------------+
+ +----------+-------------+
+</pre>
+ During the overlap of c1 and c2, there is nothing for the A transition to do, so this
+ results in a no operation, but B is triggered. During the overlap of c2 and c3, again,
+ the A transition is inactive and because the B transition is pointing at track 0,
+ it too would be inactive. This isn't an ideal situation - it's better if the B
+ transition simply treats the frames from c3 as though they're the a track.
+
+ For this to work, we cache all frames coming from all tracks between the a and b
+ tracks. Before we process, we determine that the b frame contains someting of the
+ right type and then we determine which frame to use as the a frame (selecting a
+ matching frame from a_track to b_track - 1). If both frames contain data of the
+ correct type, we process the transition.
+
+ This method is invoked for each track and we return the cached frames as needed.
+ We clear the cache only when the requested frame is flagged as a 'last_track' frame.
+
+ * \private \memberof mlt_transition_s
+ * \param service a service
+ * \param[out] frame a frame by reference
+ * \param index 0-based track index
+ * \return true on error
+ */