mlt_tractor.[ch], mlt_multitrack.[ch]: improve doxygen documentation for the tractor...
authorddennedy <ddennedy@d19143bc-622f-0410-bfdd-b5b2a6649095>
Thu, 8 Jan 2009 05:58:58 +0000 (05:58 +0000)
committerddennedy <ddennedy@d19143bc-622f-0410-bfdd-b5b2a6649095>
Thu, 8 Jan 2009 05:58:58 +0000 (05:58 +0000)
git-svn-id: https://mlt.svn.sourceforge.net/svnroot/mlt/trunk/mlt@1309 d19143bc-622f-0410-bfdd-b5b2a6649095

src/framework/mlt_frame.h
src/framework/mlt_multitrack.c
src/framework/mlt_multitrack.h
src/framework/mlt_playlist.h
src/framework/mlt_service.h
src/framework/mlt_tractor.c
src/framework/mlt_tractor.h

index 83300b9..f24ef3e 100644 (file)
@@ -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
index a103852..c554954 100644 (file)
 
 /* 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( )
 {
@@ -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]
-*/
+ *
+ * <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 )
 {
@@ -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.
-*/
+ *
+ * <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 )
 {
@@ -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 )
 {
index 4bd3e7f..5843a6b 100644 (file)
@@ -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;
index 4ae8bd5..f5e02d3 100644 (file)
@@ -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,"
index 86cbb96..c9216c5 100644 (file)
@@ -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
index 6d9fe1b..848f7e4 100644 (file)
 /* 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( )
 {
@@ -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 "<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 );
@@ -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 )
 {
index 52496a4..4df3d94 100644 (file)
 
 /** \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