From: ddennedy Date: Tue, 16 Dec 2008 08:36:14 +0000 (+0000) Subject: mlt_producer.c, mlt_playlist.h, mlt_field.h, mlt_playlist.c, mlt_tractor.c, mlt_events.c: X-Git-Url: http://research.m1stereo.tv/gitweb?a=commitdiff_plain;h=793ea0cb67a2766b1294249a0b77508cfb93b35d;p=melted mlt_producer.c, mlt_playlist.h, mlt_field.h, mlt_playlist.c, mlt_tractor.c, mlt_events.c: add doxygen docs for events, field, and playlist. git-svn-id: https://mlt.svn.sourceforge.net/svnroot/mlt/trunk/mlt@1266 d19143bc-622f-0410-bfdd-b5b2a6649095 --- diff --git a/src/framework/mlt_events.c b/src/framework/mlt_events.c index b0efd6b..6732ebd 100644 --- a/src/framework/mlt_events.c +++ b/src/framework/mlt_events.c @@ -28,7 +28,7 @@ #include "mlt_properties.h" #include "mlt_events.h" -/** Memory leak checks. */ +/* Memory leak checks. */ #undef _MLT_EVENT_CHECKS_ @@ -39,6 +39,10 @@ static int events_destroyed = 0; /** \brief Events class * + * Events provide messages and notifications between services and the application. + * A service can register an event and fire/send it upon certain conditions or times. + * Likewise, a service or an application can listen/receive specific events on specific + * services. */ struct mlt_events_struct @@ -63,7 +67,10 @@ struct mlt_event_struct }; /** Increment the reference count on this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_inc_ref( mlt_event this ) { @@ -72,7 +79,10 @@ void mlt_event_inc_ref( mlt_event this ) } /** Increment the block count on this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_block( mlt_event this ) { @@ -81,7 +91,10 @@ void mlt_event_block( mlt_event this ) } /** Decrement the block count on this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_unblock( mlt_event this ) { @@ -90,7 +103,10 @@ void mlt_event_unblock( mlt_event this ) } /** Close this event. -*/ + * + * \public \memberof mlt_event_struct + * \param this an event + */ void mlt_event_close( mlt_event this ) { @@ -117,7 +133,10 @@ static void mlt_events_store( mlt_properties, mlt_events ); static void mlt_events_close( mlt_events ); /** Initialise the events structure. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + */ void mlt_events_init( mlt_properties this ) { @@ -131,7 +150,13 @@ void mlt_events_init( mlt_properties this ) } /** Register an event and transmitter. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param id the name of an event + * \param transmitter the callback function to send an event message + * \return true if there was an error + */ int mlt_events_register( mlt_properties this, char *id, mlt_transmitter transmitter ) { @@ -150,7 +175,13 @@ int mlt_events_register( mlt_properties this, char *id, mlt_transmitter transmit } /** Fire an event. -*/ + * + * This takes a variable number of arguments to supply to the listener. + + * \public \memberof mlt_events_struct + * \param this a properties list + * \param id the name of an event + */ void mlt_events_fire( mlt_properties this, char *id, ... ) { @@ -191,7 +222,14 @@ void mlt_events_fire( mlt_properties this, char *id, ... ) } /** Register a listener. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + * \param id the name of the event to listen for + * \param listener the callback to receive an event message + * \return + */ mlt_event mlt_events_listen( mlt_properties this, void *service, char *id, mlt_listener listener ) { @@ -247,7 +285,11 @@ mlt_event mlt_events_listen( mlt_properties this, void *service, char *id, mlt_l } /** Block all events for a given service. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + */ void mlt_events_block( mlt_properties this, void *service ) { @@ -274,7 +316,11 @@ void mlt_events_block( mlt_properties this, void *service ) } /** Unblock all events for a given service. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + */ void mlt_events_unblock( mlt_properties this, void *service ) { @@ -301,7 +347,11 @@ void mlt_events_unblock( mlt_properties this, void *service ) } /** Disconnect all events for a given service. -*/ + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param service an opaque pointer + */ void mlt_events_disconnect( mlt_properties this, void *service ) { @@ -338,6 +388,13 @@ typedef struct } condition_pair; +/** The event listener callback for the wait functions. + * + * \private \memberof mlt_events_struct + * \param this a properties list + * \param pair a condition pair + */ + static void mlt_events_listen_for( mlt_properties this, condition_pair *pair ) { pthread_mutex_lock( &pair->mutex ); @@ -348,6 +405,14 @@ static void mlt_events_listen_for( mlt_properties this, condition_pair *pair ) } } +/** Prepare to wait for an event. + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param id the name of the event to wait for + * \return an event + */ + mlt_event mlt_events_setup_wait_for( mlt_properties this, char *id ) { condition_pair *pair = malloc( sizeof( condition_pair ) ); @@ -358,6 +423,13 @@ mlt_event mlt_events_setup_wait_for( mlt_properties this, char *id ) return mlt_events_listen( this, pair, id, ( mlt_listener )mlt_events_listen_for ); } +/** Wait for an event. + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param event an event + */ + void mlt_events_wait_for( mlt_properties this, mlt_event event ) { if ( event != NULL ) @@ -367,6 +439,13 @@ void mlt_events_wait_for( mlt_properties this, mlt_event event ) } } +/** Cleanup after waiting for an event. + * + * \public \memberof mlt_events_struct + * \param this a properties list + * \param event an event + */ + void mlt_events_close_wait_for( mlt_properties this, mlt_event event ) { if ( event != NULL ) @@ -381,7 +460,11 @@ void mlt_events_close_wait_for( mlt_properties this, mlt_event event ) } /** Fetch the events object. -*/ + * + * \private \memberof mlt_events_struct + * \param this a properties list + * \return an events object + */ static mlt_events mlt_events_fetch( mlt_properties this ) { @@ -392,7 +475,11 @@ static mlt_events mlt_events_fetch( mlt_properties this ) } /** Store the events object. -*/ + * + * \private \memberof mlt_events_struct + * \param this a properties list + * \param events an events object + */ static void mlt_events_store( mlt_properties this, mlt_events events ) { @@ -401,7 +488,10 @@ static void mlt_events_store( mlt_properties this, mlt_events events ) } /** Close the events object. -*/ + * + * \private \memberof mlt_events_struct + * \param events an events object + */ static void mlt_events_close( mlt_events events ) { @@ -411,4 +501,3 @@ static void mlt_events_close( mlt_events events ) free( events ); } } - diff --git a/src/framework/mlt_field.c b/src/framework/mlt_field.c index a86afa9..89f3824 100644 --- a/src/framework/mlt_field.c +++ b/src/framework/mlt_field.c @@ -36,20 +36,21 @@ struct mlt_field_s { - // This is the producer we're connected to + /// This is the producer we're connected to mlt_service producer; - // Multitrack + /// Multitrack mlt_multitrack multitrack; - // Tractor + /// Tractor mlt_tractor tractor; }; -/** Constructor. - - We construct a multitrack and a tractor here. -*/ +/** Construct a field, mulitrack, and tractor. + * + * \public \memberof mlt_field_s + * \return a new field + */ mlt_field mlt_field_init( ) { @@ -76,6 +77,14 @@ mlt_field mlt_field_init( ) return this; } +/** Construct a field and initialize with supplied multitrack and tractor. + * + * \public \memberof mlt_field_s + * \param multitrack a multitrack + * \param tractor a tractor + * \return a new field + */ + mlt_field mlt_field_new( mlt_multitrack multitrack, mlt_tractor tractor ) { // Initialise the field @@ -102,15 +111,23 @@ mlt_field mlt_field_new( mlt_multitrack multitrack, mlt_tractor tractor ) } /** Get the service associated to this field. -*/ + * + * \public \memberof mlt_field_s + * \param this a field + * \return the tractor as a service + */ mlt_service mlt_field_service( mlt_field this ) { return MLT_TRACTOR_SERVICE( this->tractor ); } -/** Get the multi track. -*/ +/** Get the multitrack. + * + * \public \memberof mlt_field_s + * \param this a field + * \return the multitrack + */ mlt_multitrack mlt_field_multitrack( mlt_field this ) { @@ -118,7 +135,11 @@ mlt_multitrack mlt_field_multitrack( mlt_field this ) } /** Get the tractor. -*/ + * + * \public \memberof mlt_field_s + * \param this a field + * \return the tractor + */ mlt_tractor mlt_field_tractor( mlt_field this ) { @@ -126,7 +147,11 @@ mlt_tractor mlt_field_tractor( mlt_field this ) } /** Get the properties associated to this field. -*/ + * + * \public \memberof mlt_field_s + * \param this a field + * \return a properties list + */ mlt_properties mlt_field_properties( mlt_field this ) { @@ -134,7 +159,13 @@ mlt_properties mlt_field_properties( mlt_field this ) } /** Plant a filter. -*/ + * + * \public \memberof mlt_field_s + * \param this a field + * \param that a filter + * \param track the track index + * \return true if there was an error + */ int mlt_field_plant_filter( mlt_field this, mlt_filter that, int track ) { @@ -158,7 +189,14 @@ int mlt_field_plant_filter( mlt_field this, mlt_filter that, int track ) } /** Plant a transition. -*/ + * + * \public \memberof mlt_field_s + * \param this a field + * \param that a transition + * \param a_track input A's track index + * \param b_track input B's track index + * \return true if there was an error + */ int mlt_field_plant_transition( mlt_field this, mlt_transition that, int a_track, int b_track ) { @@ -182,7 +220,10 @@ int mlt_field_plant_transition( mlt_field this, mlt_transition that, int a_track } /** Close the field. -*/ + * + * \public \memberof mlt_field_s + * \param this a field + */ void mlt_field_close( mlt_field this ) { @@ -194,6 +235,13 @@ void mlt_field_close( mlt_field this ) } } +/** Remove a filter or transition from the field. + * + * \public \memberof mlt_field_s + * \param self a field + * \param service the filter or transition to remove + */ + void mlt_field_disconnect_service( mlt_field self, mlt_service service ) { mlt_service p = mlt_service_producer( service ); diff --git a/src/framework/mlt_playlist.c b/src/framework/mlt_playlist.c index 8cf4338..1710e21 100644 --- a/src/framework/mlt_playlist.c +++ b/src/framework/mlt_playlist.c @@ -46,15 +46,20 @@ struct playlist_entry_s int preservation_hack; }; -/** Forward declarations +/* Forward declarations */ static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int index ); static int mlt_playlist_unmix( mlt_playlist this, int clip ); static int mlt_playlist_resize_mix( mlt_playlist this, int clip, int in, int out ); -/** Constructor. -*/ +/** Construct a playlist. + * + * Sets the resource property to "". + * Set the mlt_type to property to "mlt_producer". + * \public \memberof mlt_playlist_s + * \return a new playlist + */ mlt_playlist mlt_playlist_init( ) { @@ -97,7 +102,12 @@ mlt_playlist mlt_playlist_init( ) } /** Get the producer associated to this playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \return the producer interface + * \see MLT_PLAYLIST_PRODUCER + */ mlt_producer mlt_playlist_producer( mlt_playlist this ) { @@ -105,15 +115,25 @@ mlt_producer mlt_playlist_producer( mlt_playlist this ) } /** Get the service associated to this playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \return the service interface + * \see MLT_PLAYLIST_SERVICE + */ mlt_service mlt_playlist_service( mlt_playlist this ) { return MLT_PRODUCER_SERVICE( &this->parent ); } -/** Get the propertues associated to this playlist. -*/ +/** Get the properties associated to this playlist. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \return the playlist's properties list + * \see MLT_PLAYLIST_PROPERTIES + */ mlt_properties mlt_playlist_properties( mlt_playlist this ) { @@ -121,7 +141,11 @@ mlt_properties mlt_playlist_properties( mlt_playlist this ) } /** Refresh the playlist after a clip has been changed. -*/ + * + * \private \memberof mlt_playlist_s + * \param this a playlist + * \return false + */ static int mlt_playlist_virtual_refresh( mlt_playlist this ) { @@ -178,7 +202,12 @@ static int mlt_playlist_virtual_refresh( mlt_playlist this ) } /** Listener for producers on the playlist. -*/ + * + * Refreshes the playlist whenever an entry receives producer-changed. + * \private \memberof mlt_playlist_s + * \param producer a producer + * \param this a playlist + */ static void mlt_playlist_listener( mlt_producer producer, mlt_playlist this ) { @@ -186,7 +215,14 @@ static void mlt_playlist_listener( mlt_producer producer, mlt_playlist this ) } /** Append to the virtual playlist. -*/ + * + * \private \memberof mlt_playlist_s + * \param this a playlist + * \param source a producer + * \param in the producer's starting time + * \param out the producer's ending time + * \return true if there was an error + */ static int mlt_playlist_virtual_append( mlt_playlist this, mlt_producer source, mlt_position in, mlt_position out ) { @@ -288,6 +324,16 @@ static int mlt_playlist_virtual_append( mlt_playlist this, mlt_producer source, return mlt_playlist_virtual_refresh( this ); } +/** Locate a producer by index. + * + * \private \memberof mlt_playlist_s + * \param this a playlist + * \param[in, out] position the time at which to locate the producer, returns the time relative to the producer's starting point + * \param[out] clip the index of the playlist entry + * \param[out] total the duration of the playlist up to and including this producer + * \return a producer or NULL if not found + */ + static mlt_producer mlt_playlist_locate( mlt_playlist this, mlt_position *position, int *clip, int *total ) { // Default producer to NULL @@ -318,7 +364,17 @@ static mlt_producer mlt_playlist_locate( mlt_playlist this, mlt_position *positi } /** Seek in the virtual playlist. -*/ + * + * This gets the producer at the current position and seeks on the producer + * while doing repeat and end-of-file handling. This is also responsible for + * closing producers previous to the preceding playlist if the autoclose + * property is set. + * \private \memberof mlt_playlist_s + * \param this a playlist + * \param[out] progressive true if the producer should be displayed progressively + * \return the service interface of the producer at the play head + * \see producer_get_frame + */ static mlt_service mlt_playlist_virtual_seek( mlt_playlist this, int *progressive ) { @@ -398,7 +454,12 @@ static mlt_service mlt_playlist_virtual_seek( mlt_playlist this, int *progressiv } /** Invoked when a producer indicates that it has prematurely reached its end. -*/ + * + * \private \memberof mlt_playlist_s + * \param this a playlist + * \return a producer + * \see producer_get_frame + */ static mlt_producer mlt_playlist_virtual_set_out( mlt_playlist this ) { @@ -441,7 +502,11 @@ static mlt_producer mlt_playlist_virtual_set_out( mlt_playlist this ) } /** Obtain the current clips index. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \return the index of the playlist entry at the current position + */ int mlt_playlist_current_clip( mlt_playlist this ) { @@ -469,7 +534,11 @@ int mlt_playlist_current_clip( mlt_playlist this ) } /** Obtain the current clips producer. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \return the producer at the current position + */ mlt_producer mlt_playlist_current( mlt_playlist this ) { @@ -481,7 +550,14 @@ mlt_producer mlt_playlist_current( mlt_playlist this ) } /** Get the position which corresponds to the start of the next clip. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param whence the location from which to make the index relative: + * start of playlist, end of playlist, or current position + * \param index the playlist entry index relative to whence + * \return the time at which the referenced clip starts + */ mlt_position mlt_playlist_clip( mlt_playlist this, mlt_whence whence, int index ) { @@ -519,7 +595,13 @@ mlt_position mlt_playlist_clip( mlt_playlist this, mlt_whence whence, int index } /** Get all the info about the clip specified. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param info a clip info struct + * \param index a playlist entry index + * \return true if there was an error + */ int mlt_playlist_get_clip_info( mlt_playlist this, mlt_playlist_clip_info *info, int index ) { @@ -546,7 +628,11 @@ int mlt_playlist_get_clip_info( mlt_playlist this, mlt_playlist_clip_info *info, } /** Get number of clips in the playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \return the number of playlist entries + */ int mlt_playlist_count( mlt_playlist this ) { @@ -554,7 +640,11 @@ int mlt_playlist_count( mlt_playlist this ) } /** Clear the playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \return true if there was an error + */ int mlt_playlist_clear( mlt_playlist this ) { @@ -569,7 +659,12 @@ int mlt_playlist_clear( mlt_playlist this ) } /** Append a producer to the playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param producer the producer to append + * \return true if there was an error + */ int mlt_playlist_append( mlt_playlist this, mlt_producer producer ) { @@ -578,7 +673,14 @@ int mlt_playlist_append( mlt_playlist this, mlt_producer producer ) } /** Append a producer to the playlist with in/out points. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param producer the producer to append + * \param in the starting point on the producer + * \param out the ending point on the producer + * \return true if there was an error + */ int mlt_playlist_append_io( mlt_playlist this, mlt_producer producer, mlt_position in, mlt_position out ) { @@ -590,7 +692,12 @@ int mlt_playlist_append_io( mlt_playlist this, mlt_producer producer, mlt_positi } /** Append a blank to the playlist of a given length. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param length the ending time of the blank entry, not its duration + * \return true if there was an error + */ int mlt_playlist_blank( mlt_playlist this, mlt_position length ) { @@ -602,7 +709,15 @@ int mlt_playlist_blank( mlt_playlist this, mlt_position length ) } /** Insert a producer into the playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param producer the producer to insert + * \param where the producer's playlist entry index + * \param in the starting point on the producer + * \param out the ending point on the producer + * \return true if there was an error + */ int mlt_playlist_insert( mlt_playlist this, mlt_producer producer, int where, mlt_position in, mlt_position out ) { @@ -618,7 +733,12 @@ int mlt_playlist_insert( mlt_playlist this, mlt_producer producer, int where, ml } /** Remove an entry in the playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param where the playlist entry index + * \return true if there was an error + */ int mlt_playlist_remove( mlt_playlist this, int where ) { @@ -692,7 +812,13 @@ int mlt_playlist_remove( mlt_playlist this, int where ) } /** Move an entry in the playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param src an entry index + * \param dest an entry index + * \return false + */ int mlt_playlist_move( mlt_playlist this, int src, int dest ) { @@ -750,7 +876,13 @@ int mlt_playlist_move( mlt_playlist this, int src, int dest ) } /** Repeat the specified clip n times. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip a playlist entry index + * \param repeat the number of times to repeat the clip + * \return true if there was an error + */ int mlt_playlist_repeat_clip( mlt_playlist this, int clip, int repeat ) { @@ -765,7 +897,14 @@ int mlt_playlist_repeat_clip( mlt_playlist this, int clip, int repeat ) } /** Resize the specified clip. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \param in the new starting time on the clip's producer + * \param out the new ending time on the clip's producer + * \return true if there was an error + */ int mlt_playlist_resize_clip( mlt_playlist this, int clip, mlt_position in, mlt_position out ) { @@ -810,7 +949,14 @@ int mlt_playlist_resize_clip( mlt_playlist this, int clip, mlt_position in, mlt_ } /** Split a clip on the playlist at the given position. -*/ + * + * This splits after the specified frame. + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \param position the time at which to split relative to the beginning of the clip or its end if negative + * \return true if there was an error + */ int mlt_playlist_split( mlt_playlist this, int clip, mlt_position position ) { @@ -856,7 +1002,13 @@ int mlt_playlist_split( mlt_playlist this, int clip, mlt_position position ) } /** Split the playlist at the absolute position. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param position the time at which to split relative to the beginning of the clip + * \param left true to split before the frame starting at position + * \return true if there was an error + */ int mlt_playlist_split_at( mlt_playlist this, mlt_position position, int left ) { @@ -887,7 +1039,14 @@ int mlt_playlist_split_at( mlt_playlist this, mlt_position position, int left ) } /** Join 1 or more consecutive clips. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the starting playlist entry index + * \param count the number of entries to merge + * \param merge ignored + * \return true if there was an error + */ int mlt_playlist_join( mlt_playlist this, int clip, int count, int merge ) { @@ -915,7 +1074,14 @@ int mlt_playlist_join( mlt_playlist this, int clip, int count, int merge ) } /** Mix consecutive clips for a specified length and apply transition if specified. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \param length the number of frames over which to create the mix + * \param transition the transition to use for the mix + * \return true if there was an error + */ int mlt_playlist_mix( mlt_playlist this, int clip, int length, mlt_transition transition ) { @@ -1011,7 +1177,13 @@ int mlt_playlist_mix( mlt_playlist this, int clip, int length, mlt_transition tr } /** Add a transition to an existing mix. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \param transition a transition + * \return true if there was an error + */ int mlt_playlist_mix_add( mlt_playlist this, int clip, mlt_transition transition ) { @@ -1029,7 +1201,12 @@ int mlt_playlist_mix_add( mlt_playlist this, int clip, mlt_transition transition } /** Return the clip at the clip index. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of a playlist entry + * \return a producer or NULL if there was an error + */ mlt_producer mlt_playlist_get_clip( mlt_playlist this, int clip ) { @@ -1039,7 +1216,12 @@ mlt_producer mlt_playlist_get_clip( mlt_playlist this, int clip ) } /** Return the clip at the specified position. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param position a time relative to the beginning of the playlist + * \return a producer or NULL if not found + */ mlt_producer mlt_playlist_get_clip_at( mlt_playlist this, mlt_position position ) { @@ -1048,7 +1230,12 @@ mlt_producer mlt_playlist_get_clip_at( mlt_playlist this, mlt_position position } /** Return the clip index of the specified position. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param position a time relative to the beginning of the playlist + * \return the index of the playlist entry + */ int mlt_playlist_get_clip_index_at( mlt_playlist this, mlt_position position ) { @@ -1058,7 +1245,12 @@ int mlt_playlist_get_clip_index_at( mlt_playlist this, mlt_position position ) } /** Determine if the clip is a mix. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \return true if the producer is a mix + */ int mlt_playlist_clip_is_mix( mlt_playlist this, int clip ) { @@ -1069,8 +1261,13 @@ int mlt_playlist_clip_is_mix( mlt_playlist this, int clip ) } /** Remove a mixed clip - ensure that the cuts included in the mix find their way - back correctly on to the playlist. -*/ + * back correctly on to the playlist. + * + * \private \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \return true if there was an error + */ static int mlt_playlist_unmix( mlt_playlist this, int clip ) { @@ -1124,6 +1321,16 @@ static int mlt_playlist_unmix( mlt_playlist this, int clip ) return error; } +/** Resize a mix clip. + * + * \private \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \param in the new starting point + * \param out the new ending point + * \return true if there was an error + */ + static int mlt_playlist_resize_mix( mlt_playlist this, int clip, int in, int out ) { int error = ( clip < 0 || clip >= this->count ); @@ -1168,8 +1375,12 @@ static int mlt_playlist_resize_mix( mlt_playlist this, int clip, int in, int out return error; } -/** Consolodate adjacent blank producers. -*/ +/** Consolidate adjacent blank producers. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param keep_length set false to remove the last entry if it is blank + */ void mlt_playlist_consolidate_blanks( mlt_playlist this, int keep_length ) { @@ -1204,7 +1415,12 @@ void mlt_playlist_consolidate_blanks( mlt_playlist this, int keep_length ) } /** Determine if the specified clip index is a blank. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \return true if there was an error + */ int mlt_playlist_is_blank( mlt_playlist this, int clip ) { @@ -1212,7 +1428,12 @@ int mlt_playlist_is_blank( mlt_playlist this, int clip ) } /** Determine if the specified position is a blank. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param position a time relative to the start or end (negative) of the playlist + * \return true if there was an error + */ int mlt_playlist_is_blank_at( mlt_playlist this, mlt_position position ) { @@ -1220,7 +1441,12 @@ int mlt_playlist_is_blank_at( mlt_playlist this, mlt_position position ) } /** Replace the specified clip with a blank and return the clip. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \return a producer or NULL if there was an error + */ mlt_producer mlt_playlist_replace_with_blank( mlt_playlist this, int clip ) { @@ -1244,6 +1470,14 @@ mlt_producer mlt_playlist_replace_with_blank( mlt_playlist this, int clip ) return producer; } +/** Insert blank space. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the new blank section + * \param length the ending time of the new blank section (duration - 1) + */ + void mlt_playlist_insert_blank( mlt_playlist this, int clip, int length ) { if ( this != NULL && length >= 0 ) @@ -1257,6 +1491,14 @@ void mlt_playlist_insert_blank( mlt_playlist this, int clip, int length ) } } +/** Resize a blank entry. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param position the time at which the blank entry exists relative to the start or end (negative) of the playlist. + * \param length the additional amount of blank frames to add + * \param find true to fist locate the blank after the clip at position + */ void mlt_playlist_pad_blanks( mlt_playlist this, mlt_position position, int length, int find ) { if ( this != NULL && length != 0 ) @@ -1284,6 +1526,16 @@ void mlt_playlist_pad_blanks( mlt_playlist this, mlt_position position, int leng } } +/** Insert a clip at a specific time. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param position the time at which to insert + * \param producer the producer to insert + * \param mode true if you want to overwrite any blank section + * \return true if there was an error + */ + int mlt_playlist_insert_at( mlt_playlist this, mlt_position position, mlt_producer producer, int mode ) { int ret = this == NULL || position < 0 || producer == NULL; @@ -1347,6 +1599,14 @@ int mlt_playlist_insert_at( mlt_playlist this, mlt_position position, mlt_produc return ret; } +/** Get the time at which the clip starts relative to the playlist. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \return the starting time + */ + int mlt_playlist_clip_start( mlt_playlist this, int clip ) { mlt_playlist_clip_info info; @@ -1355,6 +1615,14 @@ int mlt_playlist_clip_start( mlt_playlist this, int clip ) return clip < 0 ? 0 : mlt_producer_get_playtime( MLT_PLAYLIST_PRODUCER( this ) ); } +/** Get the playable duration of the clip. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \return the duration of the playlist entry + */ + int mlt_playlist_clip_length( mlt_playlist this, int clip ) { mlt_playlist_clip_info info; @@ -1363,6 +1631,15 @@ int mlt_playlist_clip_length( mlt_playlist this, int clip ) return 0; } +/** Get the duration of a blank space. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param clip the index of the playlist entry + * \param bounded the maximum number of blank entries or 0 for all + * \return the duration of a blank section + */ + int mlt_playlist_blanks_from( mlt_playlist this, int clip, int bounded ) { int count = 0; @@ -1386,6 +1663,15 @@ int mlt_playlist_blanks_from( mlt_playlist this, int clip, int bounded ) return count; } +/** Remove a portion of the playlist by time. + * + * \public \memberof mlt_playlist_s + * \param this a playlist + * \param position the starting time + * \param length the duration of time to remove + * \return the new entry index at the position + */ + int mlt_playlist_remove_region( mlt_playlist this, mlt_position position, int length ) { int index = mlt_playlist_get_clip_index_at( this, position ); @@ -1424,6 +1710,17 @@ int mlt_playlist_remove_region( mlt_playlist this, mlt_position position, int le return index; } +/** Not implemented + * + * \deprecated not implemented + * \public \memberof mlt_playlist_s + * \param this + * \param position + * \param length + * \param new_position + * \return + */ + int mlt_playlist_move_region( mlt_playlist this, mlt_position position, int length, int new_position ) { if ( this != NULL ) @@ -1433,7 +1730,14 @@ int mlt_playlist_move_region( mlt_playlist this, mlt_position position, int leng } /** Get the current frame. -*/ + * + * The implementation of the get_frame virtual function. + * \private \memberof mlt_playlist_s + * \param producer a producer + * \param frame a frame by reference + * \param index the time at which to get the frame + * \return false + */ static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int index ) { @@ -1509,7 +1813,10 @@ static int producer_get_frame( mlt_producer producer, mlt_frame_ptr frame, int i } /** Close the playlist. -*/ + * + * \public \memberof mlt_playlist_s + * \param this a playlist + */ void mlt_playlist_close( mlt_playlist this ) { diff --git a/src/framework/mlt_playlist.h b/src/framework/mlt_playlist.h index 115cf1d..4ae8bd5 100644 --- a/src/framework/mlt_playlist.h +++ b/src/framework/mlt_playlist.h @@ -30,28 +30,39 @@ typedef struct { - int clip; - mlt_producer producer; - mlt_producer cut; - mlt_position start; - char *resource; - mlt_position frame_in; - mlt_position frame_out; - mlt_position frame_count; - mlt_position length; - float fps; - int repeat; + int clip; /**< the index of the clip within the playlist */ + mlt_producer producer; /**< the clip's producer (or parent producer of a cut) */ + mlt_producer cut; /**< the clips' cut producer */ + mlt_position start; /**< the time this begins relative to the beginning of the playlist */ + char *resource; /**< the file name or address of the clip */ + mlt_position frame_in; /**< the clip's in point */ + mlt_position frame_out; /**< the clip's out point */ + mlt_position frame_count; /**< the duration of the clip */ + mlt_position length; /**< the unedited duration of the clip */ + float fps; /**< the frame rate of the clip */ + int repeat; /**< the number of times the clip is repeated */ } mlt_playlist_clip_info; -/** Private definition. +/** Playlist Entry */ typedef struct playlist_entry_s playlist_entry; /** \brief Playlist class * + * A playlist is a sequential container of producers and blank spaces. The class provides all + * sorts of playlist assembly and manipulation routines. A playlist is also a producer within + * 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," + * which is a way to add filters as a playlist entry - useful only in a multitrack. See FxCut on the wiki. + * \properties \em mix_in + * \properties \em mix_out */ struct mlt_playlist_s diff --git a/src/framework/mlt_producer.c b/src/framework/mlt_producer.c index 6f00734..6646ed8 100644 --- a/src/framework/mlt_producer.c +++ b/src/framework/mlt_producer.c @@ -266,6 +266,7 @@ mlt_service mlt_producer_service( mlt_producer this ) * \public \memberof mlt_producer_s * \param this a producer * \return the producer's property list + * \see MLT_PRODUCER_PROPERTIES */ mlt_properties mlt_producer_properties( mlt_producer this ) @@ -488,7 +489,7 @@ mlt_position mlt_producer_get_playtime( mlt_producer this ) return mlt_producer_get_out( this ) - mlt_producer_get_in( this ) + 1; } -/** Get the total length of the producer. +/** Get the total, unedited length of the producer. * * The value returned by a live streaming producer is unknown. * diff --git a/src/framework/mlt_tractor.c b/src/framework/mlt_tractor.c index 3a3907b..6d9fe1b 100644 --- a/src/framework/mlt_tractor.c +++ b/src/framework/mlt_tractor.c @@ -30,7 +30,7 @@ #include #include -/** Forward references to static methods. +/* Forward references to static methods. */ static int producer_get_frame( mlt_producer this, mlt_frame_ptr frame, int track );