From 984db4a3f9c364445f9a31f282f3614cf5e1e5af Mon Sep 17 00:00:00 2001 From: ddennedy Date: Thu, 8 Jan 2009 05:58:58 +0000 Subject: [PATCH] mlt_tractor.[ch], mlt_multitrack.[ch]: improve doxygen documentation for the tractor and mulitrack classes git-svn-id: https://mlt.svn.sourceforge.net/svnroot/mlt/trunk/mlt@1309 d19143bc-622f-0410-bfdd-b5b2a6649095 --- src/framework/mlt_frame.h | 3 +- src/framework/mlt_multitrack.c | 192 ++++++++++++++++++++++++++++------------ src/framework/mlt_multitrack.h | 3 +- src/framework/mlt_playlist.h | 1 - src/framework/mlt_service.h | 3 + src/framework/mlt_tractor.c | 98 +++++++++++++++++---- src/framework/mlt_tractor.h | 9 ++ 7 files changed, 232 insertions(+), 77 deletions(-) diff --git a/src/framework/mlt_frame.h b/src/framework/mlt_frame.h index 83300b9..f24ef3e 100644 --- a/src/framework/mlt_frame.h +++ b/src/framework/mlt_frame.h @@ -44,7 +44,8 @@ typedef int ( *mlt_get_audio )( mlt_frame self, int16_t **buffer, mlt_audio_form * \properties \em test_image set if the frame holds a "test card" image * \properties \em test_audio set if the frame holds "test card" audio * \properties \em _producer holds a reference to the frame's end producer - * \properties \em _speed + * \properties \em _speed the current speed of the producer that generated the frame + * \properties \em _position the position of the frame * \properties \em meta.* holds metadata * \properties \em hide set to 1 to hide the video, 2 to mute the audio * \properties \em last_track a flag to indicate an end-of-tracks frame diff --git a/src/framework/mlt_multitrack.c b/src/framework/mlt_multitrack.c index a103852..c554954 100644 --- a/src/framework/mlt_multitrack.c +++ b/src/framework/mlt_multitrack.c @@ -29,10 +29,15 @@ /* 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 "". + * + * \public \memberof mlt_multitrack_s + * \return a new multitrack + */ mlt_multitrack mlt_multitrack_init( ) { @@ -65,7 +70,12 @@ 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 ) { @@ -73,7 +83,12 @@ 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 ) { @@ -81,15 +96,23 @@ 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 ) { @@ -129,7 +152,11 @@ 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 ) { @@ -137,10 +164,16 @@ 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 ) { @@ -188,7 +221,11 @@ int mlt_multitrack_connect( mlt_multitrack this, mlt_producer producer, int trac } /** 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 ) { @@ -196,7 +233,12 @@ 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 ) { @@ -208,11 +250,28 @@ 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; @@ -225,24 +284,32 @@ static int add_unique( mlt_position *array, int size, mlt_position position ) } /** 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] -*/ + * + * 
+ * 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]
+ *
+ * + * \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 ) { @@ -323,29 +390,37 @@ mlt_position mlt_multitrack_clip( mlt_multitrack this, mlt_whence whence, int in } /** 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. -*/ + * + * 
+ * 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.
+ *
+ * + * \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 ) { @@ -404,8 +479,11 @@ static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int ind 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 ) { diff --git a/src/framework/mlt_multitrack.h b/src/framework/mlt_multitrack.h index 4bd3e7f..5843a6b 100644 --- a/src/framework/mlt_multitrack.h +++ b/src/framework/mlt_multitrack.h @@ -41,11 +41,12 @@ typedef struct mlt_track_s *mlt_track; * A multitrack is a parallel container of producers that acts a single producer. * * \extends mlt_producer_s + * \properties \em log_id not currently used, but sets it to "mulitrack" */ struct mlt_multitrack_s { - /* We're extending producer here */ + /** We're extending producer here */ struct mlt_producer_s parent; mlt_track *list; int size; diff --git a/src/framework/mlt_playlist.h b/src/framework/mlt_playlist.h index 4ae8bd5..f5e02d3 100644 --- a/src/framework/mlt_playlist.h +++ b/src/framework/mlt_playlist.h @@ -56,7 +56,6 @@ typedef struct playlist_entry_s playlist_entry; * the framework. * * \extends mlt_producer_s - * \properties \em eof This is the behavior for when the end of the playlist is reached, one of: pause (default) or loop. * \properties \em autoclose Set this true if you are doing sequential processing and want to * automatically close producers as they are finished being used to free resources. * \properties \em meta.fx_cut Set true on a producer to indicate that it is a "fx_cut," diff --git a/src/framework/mlt_service.h b/src/framework/mlt_service.h index 86cbb96..c9216c5 100644 --- a/src/framework/mlt_service.h +++ b/src/framework/mlt_service.h @@ -41,6 +41,8 @@ * \event \em service-changed * \event \em property-changed * \properties \em mlt_type identifies the subclass + * \properties \em _mlt_service_hidden a flag that indicates whether to hide the mlt_service + * \properties \em mlt_service is the name of the implementation of the service * \properties \em resource is either the stream identifier or grandchild-class * \properties \em in when to start, what is started is service-specific * \properties \em out when to stop @@ -48,6 +50,7 @@ * See modules/core/filter_region.c and modules/core/filter_watermark.c for examples. * \properties \em disable Set this on a filter to disable it while keeping it in the object model. * \properties \em _profile stores the mlt_profile for a service + * \properties \em _unique_id is a unique identifier */ struct mlt_service_s diff --git a/src/framework/mlt_tractor.c b/src/framework/mlt_tractor.c index 6d9fe1b..848f7e4 100644 --- a/src/framework/mlt_tractor.c +++ b/src/framework/mlt_tractor.c @@ -33,11 +33,17 @@ /* 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 "", 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( ) { @@ -69,6 +75,15 @@ mlt_tractor mlt_tractor_init( ) return this; } +/** Construct a tractor as well as a field and multitrack. + * + * Sets the resource property to "", 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 ); @@ -106,7 +121,12 @@ mlt_tractor mlt_tractor_new( ) } /** 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 ) { @@ -114,7 +134,12 @@ 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 ) { @@ -122,7 +147,12 @@ 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 ) { @@ -130,7 +160,11 @@ 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 ) { @@ -138,7 +172,11 @@ 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 ) { @@ -146,7 +184,10 @@ 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 ) { @@ -169,7 +210,12 @@ static void mlt_tractor_listener( mlt_multitrack tracks, 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 ) { @@ -183,7 +229,13 @@ 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 ) { @@ -191,7 +243,12 @@ 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 ) { @@ -253,9 +310,13 @@ static void destroy_data_queue( void *arg ) } /** 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 ) { @@ -459,8 +520,11 @@ static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int tra } } -/** 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 ) { diff --git a/src/framework/mlt_tractor.h b/src/framework/mlt_tractor.h index 52496a4..4df3d94 100644 --- a/src/framework/mlt_tractor.h +++ b/src/framework/mlt_tractor.h @@ -27,7 +27,16 @@ /** \brief Tractor class * + * The tractor is a convenience class that works with the field class + * to manage a multitrack, track filters, and transitions. + * * \extends mlt_producer_s + * \properties \em multitrack holds a reference to the mulitrack object that a tractor manages + * \properties \em field holds a reference to the field object that a tractor manages + * \properties \em producer holds a reference to an encapsulated producer + * \properties \em global_feed a flag to indicate whether this tractor feeds to the consumer or stops here + * \properties \em global_queue is something for the data_feed functionality in the core module + * \properties \em data_queue is something for the data_feed functionality in the core module */ struct mlt_tractor_s -- 1.7.4.4