/* Forward reference. */
-static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int index );
+static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int index );
/** Construct and initialize a new multitrack.
-*/
+ *
+ * Sets the resource property to "<multitrack>".
+ *
+ * \public \memberof mlt_multitrack_s
+ * \return a new multitrack
+ */
mlt_multitrack mlt_multitrack_init( )
{
}
/** Get the producer associated to this multitrack.
-*/
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ * \return the producer object
+ * \see MLT_MULTITRACK_PRODUCER
+ */
mlt_producer mlt_multitrack_producer( mlt_multitrack this )
{
}
/** Get the service associated this multitrack.
-*/
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ * \return the service object
+ * \see MLT_MULTITRACK_SERVICE
+ */
mlt_service mlt_multitrack_service( mlt_multitrack this )
{
}
/** Get the properties associated this multitrack.
-*/
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ * \return the multitrack's property list
+ * \see MLT_MULTITRACK_PROPERTIES
+ */
mlt_properties mlt_multitrack_properties( mlt_multitrack this )
{
return MLT_MULTITRACK_PROPERTIES( this );
}
-/** Initialise position related information.
-*/
+/** Initialize position related information.
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ */
void mlt_multitrack_refresh( mlt_multitrack this )
{
}
/** Listener for producers on the playlist.
-*/
+ *
+ * \private \memberof mlt_multitrack_s
+ * \param producer a producer
+ * \param this a multitrack
+ */
static void mlt_multitrack_listener( mlt_producer producer, mlt_multitrack this )
{
}
/** Connect a producer to a given track.
-
- Note that any producer can be connected here, but see special case treatment
- of playlist in clip point determination below.
-*/
+ *
+ * Note that any producer can be connected here, but see special case treatment
+ * of playlist in clip point determination below.
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ * \param producer the producer to connect to the multitrack producer
+ * \param track the 0-based index of the track on which to connect the multitrack
+ * \return true on error
+ */
int mlt_multitrack_connect( mlt_multitrack this, mlt_producer producer, int track )
{
}
/** Get the number of tracks.
-*/
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ * \return the number of tracks
+ */
int mlt_multitrack_count( mlt_multitrack this )
{
}
/** Get an individual track as a producer.
-*/
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ * \param track the 0-based index of the producer to get
+ * \return the producer or NULL if not valid
+ */
mlt_producer mlt_multitrack_track( mlt_multitrack this, int track )
{
return producer;
}
+/** Position comparison function for sorting.
+ *
+ * \private \memberof mlt_multitrack_s
+ * \param p1 a position
+ * \param p2 another position
+ * \return <0 if \p p1 is less than \p p2, 0 if equal, >0 if greater
+ */
+
static int position_compare( const void *p1, const void *p2 )
{
return *( mlt_position * )p1 - *( mlt_position * )p2;
}
+/** Add a position to a set.
+ *
+ * \private \memberof mlt_multitrack_s
+ * \param array an array of positions (the set)
+ * \param size the current number of positions in the array (not the capacity of the array)
+ * \param position the position to add
+ * \return the new size of the array
+ */
+
static int add_unique( mlt_position *array, int size, mlt_position position )
{
int i = 0;
}
/** Determine the clip point.
-
- Special case here: a 'producer' has no concept of multiple clips - only the
- playlist and multitrack producers have clip functionality. Further to that a
- multitrack determines clip information from any connected tracks that happen
- to be playlists.
-
- Additionally, it must locate clips in the correct order, for example, consider
- the following track arrangement:
-
- playlist1 |0.0 |b0.0 |0.1 |0.1 |0.2 |
- playlist2 |b1.0 |1.0 |b1.1 |1.1 |
-
- Note - b clips represent blanks. They are also reported as clip positions.
-
- When extracting clip positions from these playlists, we should get a sequence of:
-
- 0.0, 1.0, b0.0, 0.1, b1.1, 1.1, 0.1, 0.2, [out of playlist2], [out of playlist1]
-*/
+ *
+ * <pre>
+ * Special case here: a 'producer' has no concept of multiple clips - only the
+ * playlist and multitrack producers have clip functionality. Further to that a
+ * multitrack determines clip information from any connected tracks that happen
+ * to be playlists.
+ *
+ * Additionally, it must locate clips in the correct order, for example, consider
+ * the following track arrangement:
+ *
+ * playlist1 |0.0 |b0.0 |0.1 |0.1 |0.2 |
+ * playlist2 |b1.0 |1.0 |b1.1 |1.1 |
+ *
+ * Note - b clips represent blanks. They are also reported as clip positions.
+ *
+ * When extracting clip positions from these playlists, we should get a sequence of:
+ *
+ * 0.0, 1.0, b0.0, 0.1, b1.1, 1.1, 0.1, 0.2, [out of playlist2], [out of playlist1]
+ * </pre>
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ * \param whence from where to extract
+ * \param index the 0-based index of which clip to extract
+ * \return the position of clip \p index relative to \p whence
+ */
mlt_position mlt_multitrack_clip( mlt_multitrack this, mlt_whence whence, int index )
{
}
/** Get frame method.
-
- Special case here: The multitrack must be used in a conjunction with a downstream
- tractor-type service, ie:
-
- Producer1 \
- Producer2 - multitrack - { filters/transitions } - tractor - consumer
- Producer3 /
-
- The get_frame of a tractor pulls frames from it's connected service on all tracks and
- will terminate as soon as it receives a test card with a last_track property. The
- important case here is that the mulitrack does not move to the next frame until all
- tracks have been pulled.
-
- Reasoning: In order to seek on a network such as above, the multitrack needs to ensure
- that all producers are positioned on the same frame. It uses the 'last track' logic
- to determine when to move to the next frame.
-
- Flaw: if a transition is configured to read from a b-track which happens to trigger
- the last frame logic (ie: it's configured incorrectly), then things are going to go
- out of sync.
-
- See playlist logic too.
-*/
+ *
+ * <pre>
+ * Special case here: The multitrack must be used in a conjunction with a downstream
+ * tractor-type service, ie:
+ *
+ * Producer1 \
+ * Producer2 - multitrack - { filters/transitions } - tractor - consumer
+ * Producer3 /
+ *
+ * The get_frame of a tractor pulls frames from it's connected service on all tracks and
+ * will terminate as soon as it receives a test card with a last_track property. The
+ * important case here is that the mulitrack does not move to the next frame until all
+ * tracks have been pulled.
+ *
+ * Reasoning: In order to seek on a network such as above, the multitrack needs to ensure
+ * that all producers are positioned on the same frame. It uses the 'last track' logic
+ * to determine when to move to the next frame.
+ *
+ * Flaw: if a transition is configured to read from a b-track which happens to trigger
+ * the last frame logic (ie: it's configured incorrectly), then things are going to go
+ * out of sync.
+ *
+ * See playlist logic too.
+ * </pre>
+ *
+ * \private \memberof mlt_multitrack_s
+ * \param parent the producer interface to a mulitrack
+ * \param[out] frame a frame by reference
+ * \param index the 0-based track index
+ * \return true if there was an error
+ */
static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int index )
{
return 0;
}
-/** Close this instance.
-*/
+/** Close this instance and free its resources.
+ *
+ * \public \memberof mlt_multitrack_s
+ * \param this a multitrack
+ */
void mlt_multitrack_close( mlt_multitrack this )
{
/* Forward references to static methods.
*/
-static int producer_get_frame( mlt_producer this, mlt_frame_ptr frame, int track );
+static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int track );
static void mlt_tractor_listener( mlt_multitrack tracks, mlt_tractor this );
-/** Constructor for the tractor.
-*/
+/** Construct a tractor without a field or multitrack.
+ *
+ * Sets the resource property to "<tractor>", the mlt_type to "mlt_producer",
+ * and mlt_service to "tractor".
+ *
+ * \public \memberof mlt_tractor_s
+ * \return the new tractor
+ */
mlt_tractor mlt_tractor_init( )
{
return this;
}
+/** Construct a tractor as well as a field and multitrack.
+ *
+ * Sets the resource property to "<tractor>", the mlt_type to "mlt_producer",
+ * and mlt_service to "tractor".
+ *
+ * \public \memberof mlt_tractor_s
+ * \return the new tractor
+ */
+
mlt_tractor mlt_tractor_new( )
{
mlt_tractor this = calloc( sizeof( struct mlt_tractor_s ), 1 );
}
/** Get the service object associated to the tractor.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \return the parent service object
+ * \see MLT_TRACTOR_SERVICE
+ */
mlt_service mlt_tractor_service( mlt_tractor this )
{
}
/** Get the producer object associated to the tractor.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \return the parent producer object
+ * \see MLT_TRACTOR_PRODUCER
+ */
mlt_producer mlt_tractor_producer( mlt_tractor this )
{
}
/** Get the properties object associated to the tractor.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \return the tractor's property list
+ * \see MLT_TRACTOR_PROPERTIES
+ */
mlt_properties mlt_tractor_properties( mlt_tractor this )
{
}
/** Get the field this tractor is harvesting.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \return a field or NULL if there is no field for this tractor
+ */
mlt_field mlt_tractor_field( mlt_tractor this )
{
}
/** Get the multitrack this tractor is pulling.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \return a multitrack or NULL if there is none
+ */
mlt_multitrack mlt_tractor_multitrack( mlt_tractor this )
{
}
/** Ensure the tractors in/out points match the multitrack.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ */
void mlt_tractor_refresh( mlt_tractor this )
{
}
/** Connect the tractor.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \param producer a producer
+ * \return true on error
+ */
int mlt_tractor_connect( mlt_tractor this, mlt_service producer )
{
}
/** Set the producer for a specific track.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \param producer a producer
+ * \param index the 0-based track index
+ * \return true on error
+ */
int mlt_tractor_set_track( mlt_tractor this, mlt_producer producer, int index )
{
}
/** Get the producer for a specific track.
-*/
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ * \param index the 0-based track index
+ * \return the producer for track \p index
+ */
mlt_producer mlt_tractor_get_track( mlt_tractor this, int index )
{
}
/** Get the next frame.
-
- TODO: This function needs to be redesigned...
-*/
+ *
+ * \private \memberof mlt_tractor_s
+ * \param parent the producer interface to the tractor
+ * \param[out] frame a frame by reference
+ * \param track the 0-based track index
+ * \return true on error
+ */
static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int track )
{
}
}
-/** Close the tractor.
-*/
+/** Close the tractor and free its resources.
+ *
+ * \public \memberof mlt_tractor_s
+ * \param this a tractor
+ */
void mlt_tractor_close( mlt_tractor this )
{