From: ddennedy Date: Mon, 5 Jan 2009 07:54:22 +0000 (+0000) Subject: mlt_filter.[ch], mlt_transition.[ch], mlt_consumer.[ch]: improve doxygen for filter... X-Git-Url: http://research.m1stereo.tv/gitweb?a=commitdiff_plain;h=43b8637d43111412e4de944a4eeb3668ab838f9b;p=melted mlt_filter.[ch], mlt_transition.[ch], mlt_consumer.[ch]: improve doxygen for filter, transition, and consumer git-svn-id: https://mlt.svn.sourceforge.net/svnroot/mlt/trunk/mlt@1304 d19143bc-622f-0410-bfdd-b5b2a6649095 --- diff --git a/src/framework/mlt_consumer.c b/src/framework/mlt_consumer.c index 8ed90c7..57c5b1d 100644 --- a/src/framework/mlt_consumer.c +++ b/src/framework/mlt_consumer.c @@ -31,6 +31,9 @@ #include #include +/** Define this if you want an automatic deinterlace (if necessary) when the + * consumer's producer is not running at normal speed. + */ #undef DEINTERLACE_ON_NOT_NORMAL_SPEED static void mlt_consumer_frame_render( mlt_listener listener, mlt_properties owner, mlt_service this, void **args ); @@ -38,6 +41,16 @@ static void mlt_consumer_frame_show( mlt_listener listener, mlt_properties owner static void mlt_consumer_property_changed( mlt_service owner, mlt_consumer this, char *name ); static void apply_profile_properties( mlt_consumer this, mlt_profile profile, mlt_properties properties ); +/** Initialize a consumer service. + * + * \public \memberof mlt_consumer_s + * \param this the consumer to initialize + * \param child a pointer to the object for the subclass + * \param profile the \p mlt_profile_s to use (optional but recommended, + * uses the environment variable MLT if this is NULL) + * \return true if there was an error + */ + int mlt_consumer_init( mlt_consumer this, void *child, mlt_profile profile ) { int error = 0; @@ -95,6 +108,14 @@ int mlt_consumer_init( mlt_consumer this, void *child, mlt_profile profile ) return error; } +/** Convert the profile into properties on the consumer. + * + * \private \memberof mlt_consumer_s + * \param this a consumer + * \param profile a profile + * \param properties a properties list (typically, the consumer's) + */ + static void apply_profile_properties( mlt_consumer this, mlt_profile profile, mlt_properties properties ) { mlt_event_block( this->event_listener ); @@ -113,6 +134,14 @@ static void apply_profile_properties( mlt_consumer this, mlt_profile profile, ml mlt_event_unblock( this->event_listener ); } +/** The property-changed event listener + * + * \private \memberof mlt_consumer_s + * \param owner the service a service (ignored) + * \param this the consumer + * \param name the name of the property that changed + */ + static void mlt_consumer_property_changed( mlt_service owner, mlt_consumer this, char *name ) { if ( !strcmp( name, "profile" ) ) @@ -224,12 +253,34 @@ static void mlt_consumer_property_changed( mlt_service owner, mlt_consumer this, } } +/** The transmitter for the consumer-frame-show event + * + * Invokes the listener. + * + * \private \memberof mlt_consumer_s + * \param listener a function pointer that will be invoked + * \param owner a properties list that will be passed to \p listener + * \param this a service that will be passed to \p listener + * \param args an array of pointers - the first entry is passed as a string to \p listener + */ + static void mlt_consumer_frame_show( mlt_listener listener, mlt_properties owner, mlt_service this, void **args ) { if ( listener != NULL ) listener( owner, this, ( mlt_frame )args[ 0 ] ); } +/** The transmitter for the consumer-frame-render event + * + * Invokes the listener. + * + * \private \memberof mlt_consumer_s + * \param listener a function pointer that will be invoked + * \param owner a properties list that will be passed to \p listener + * \param this a service that will be passed to \p listener + * \param args an array of pointers - the first entry is passed as a string to \p listener + */ + static void mlt_consumer_frame_render( mlt_listener listener, mlt_properties owner, mlt_service this, void **args ) { if ( listener != NULL ) @@ -237,7 +288,11 @@ static void mlt_consumer_frame_render( mlt_listener listener, mlt_properties own } /** Create a new consumer. -*/ + * + * \public \memberof mlt_consumer_s + * \param profile a profile (optional, but recommended) + * \return a new consumer + */ mlt_consumer mlt_consumer_new( mlt_profile profile ) { @@ -253,7 +308,12 @@ mlt_consumer mlt_consumer_new( mlt_profile profile ) } /** Get the parent service object. -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \return the parent service class + * \see MLT_CONSUMER_SERVICE + */ mlt_service mlt_consumer_service( mlt_consumer this ) { @@ -261,7 +321,12 @@ mlt_service mlt_consumer_service( mlt_consumer this ) } /** Get the consumer properties. -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \return the consumer's properties list + * \see MLT_CONSUMER_PROPERTIES + */ mlt_properties mlt_consumer_properties( mlt_consumer this ) { @@ -269,7 +334,15 @@ mlt_properties mlt_consumer_properties( mlt_consumer this ) } /** Connect the consumer to the producer. -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \param producer a producer + * \return > 0 warning, == 0 success, < 0 serious error, + * 1 = this service does not accept input, + * 2 = the producer is invalid, + * 3 = the producer is already registered with this consumer + */ int mlt_consumer_connect( mlt_consumer this, mlt_service producer ) { @@ -277,7 +350,11 @@ int mlt_consumer_connect( mlt_consumer this, mlt_service producer ) } /** Start the consumer. -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \return true if there was an error + */ int mlt_consumer_start( mlt_consumer this ) { @@ -342,9 +419,15 @@ int mlt_consumer_start( mlt_consumer this ) return 0; } -/** An alternative method to feed frames into the consumer - only valid if - the consumer itself is not connected. -*/ +/** An alternative method to feed frames into the consumer. + * + * Only valid if the consumer itself is not connected. + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \param frame a frame + * \return true (ignore this for now) + */ int mlt_consumer_put_frame( mlt_consumer this, mlt_frame frame ) { @@ -381,7 +464,11 @@ int mlt_consumer_put_frame( mlt_consumer this, mlt_frame frame ) } /** Protected method for consumer to get frames from connected service -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \return a frame + */ mlt_frame mlt_consumer_get_frame( mlt_consumer this ) { @@ -448,6 +535,13 @@ mlt_frame mlt_consumer_get_frame( mlt_consumer this ) return frame; } +/** Compute the time difference between now and a time value. + * + * \private \memberof mlt_consumer_s + * \param time1 a time value to be compared against now + * \return the difference in microseconds + */ + static inline long time_difference( struct timeval *time1 ) { struct timeval time2; @@ -457,6 +551,13 @@ static inline long time_difference( struct timeval *time1 ) return time1->tv_sec * 1000000 + time1->tv_usec - time2.tv_sec * 1000000 - time2.tv_usec; } +/** The thread procedure for asynchronously pulling frames through the service + * network connected to a consumer. + * + * \private \memberof mlt_consumer_s + * \param arg a consumer + */ + static void *consumer_read_ahead_thread( void *arg ) { // The argument is the consumer @@ -643,6 +744,12 @@ static void *consumer_read_ahead_thread( void *arg ) return NULL; } +/** Start the read/render thread. + * + * \private \memberof mlt_consumer_s + * \param this a consumer + */ + static void consumer_read_ahead_start( mlt_consumer this ) { // We're running now @@ -678,6 +785,12 @@ static void consumer_read_ahead_start( mlt_consumer this ) } } +/** Stop the read/render thread. + * + * \private \memberof mlt_consumer_s + * \param this a consumer + */ + static void consumer_read_ahead_stop( mlt_consumer this ) { // Make sure we're running @@ -714,6 +827,12 @@ static void consumer_read_ahead_stop( mlt_consumer this ) } } +/** Flush the read/render thread's buffer. + * + * \public \memberof mlt_consumer_s + * \param this a consumer + */ + void mlt_consumer_purge( mlt_consumer this ) { if ( this->ahead ) @@ -726,6 +845,17 @@ void mlt_consumer_purge( mlt_consumer this ) } } +/** Get the next frame from the producer connected to a consumer. + * + * Typically, one uses this instead of \p mlt_consumer_get_frame to make + * the asynchronous/real-time behavior configurable at runtime. + * You should close the frame returned from this when you are done with it. + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \return a frame + */ + mlt_frame mlt_consumer_rt_frame( mlt_consumer this ) { // Frame to return @@ -771,7 +901,10 @@ mlt_frame mlt_consumer_rt_frame( mlt_consumer this ) } /** Callback for the implementation to indicate a stopped condition. -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + */ void mlt_consumer_stopped( mlt_consumer this ) { @@ -781,7 +914,11 @@ void mlt_consumer_stopped( mlt_consumer this ) } /** Stop the consumer. -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \return true if there was an error + */ int mlt_consumer_stop( mlt_consumer this ) { @@ -819,7 +956,11 @@ int mlt_consumer_stop( mlt_consumer this ) } /** Determine if the consumer is stopped. -*/ + * + * \public \memberof mlt_consumer_s + * \param this a consumer + * \return true if the consumer is stopped + */ int mlt_consumer_is_stopped( mlt_consumer this ) { @@ -830,8 +971,11 @@ int mlt_consumer_is_stopped( mlt_consumer this ) return 0; } -/** Close the consumer. -*/ +/** Close and destroy the consumer. + * + * \public \memberof mlt_consumer_s + * \param this a consumer + */ void mlt_consumer_close( mlt_consumer this ) { diff --git a/src/framework/mlt_consumer.h b/src/framework/mlt_consumer.h index 2245704..0b6bc22 100644 --- a/src/framework/mlt_consumer.h +++ b/src/framework/mlt_consumer.h @@ -29,23 +29,75 @@ /** \brief Consumer abstract service class * + * A consumer is a service that pulls audio and video from the connected + * producers, filters, and transitions. Typically a consumer is used to + * output audio and/or video to a device, file, or socket. + * * \extends mlt_service_s + * \properties \em rescale the scaling algorithm to pass on to all scaling + * filters, defaults to "bilinear" + * \properties \em buffer the number of frames to use in the asynchronous + * render thread, defaults to 25 + * \properties \em frequency the audio sample rate to use in Hertz, defaults to 48000 + * \properties \em channels the number of audio channels to use, defaults to 2 + * \properties \em real_time the asynchronous behavior: 1 (default) for asynchronous + * with frame dropping, -1 for asynchronous without frame dropping, 0 to disable (synchronous) + * \properties \em test_card the name of a resource to use as the test card, defaults to + * environment variable MLT_TEST_CARD. If undefined, the hard-coded default test card is + * white silence. A test card is what appears when nothing is produced. + * \event \em consumer-frame-show Subclass implementations should fire this. + * \event \em consumer-frame-render The abstract class fires this. + * \event \em consumer-stopped + * \properties \em fps video frames per second as floating point (read only) + * \properties \em frame_rate_num the numerator of the video frame rate, overrides \p mlt_profile_s + * \properties \em frame_rate_den the denominator of the video frame rate, overrides \p mlt_profile_s + * \properties \em width the horizontal video resolution, overrides \p mlt_profile_s + * \properties \em height the vertical video resolution, overrides \p mlt_profile_s + * \properties \em progressive a flag that indicates if the video is interlaced + * or progressive, overrides \p mlt_profile_s + * \properties \em aspect_ratio the video sample (pixel) aspect ratio as floating point (read only) + * \properties \em sample_aspect_num the numerator of the sample aspect ratio, overrides \p mlt_profile_s + * \properties \em sample_aspect_den the denominator of the sample aspect ratio, overrides \p mlt_profile_s + * \properties \em display_ratio the video frame aspect ratio as floating point (read only) + * \properties \em display_aspect_num the numerator of the video frame aspect ratio, overrides \p mlt_profile_s + * \properties \em display_aspect_den the denominator of the video frame aspect ratio, overrides \p mlt_profile_s + * */ struct mlt_consumer_s { - /* We're implementing service here */ + /** A consumer is a service. */ struct mlt_service_s parent; - /* public virtual */ + /** Start the consumer to pull frames (virtual function). + * + * \param mlt_consumer a consumer + * \return true if there was an error + */ int ( *start )( mlt_consumer ); + + /** Stop the consumer (virtual function). + * + * \param mlt_consumer a consumer + * \return true if there was an error + */ int ( *stop )( mlt_consumer ); + + /** Get whether the consumer is running or stopped (virtual function). + * + * \param mlt_consumer a consumer + * \return true if the consumer is stopped + */ int ( *is_stopped )( mlt_consumer ); + + /** The destructor virtual function + * + * \param mlt_consumer a consumer + */ void ( *close )( mlt_consumer ); - /* Private data */ - void *local; - void *child; + void *local; /**< \private instance object */ + void *child; /**< \private the object of a subclass */ int real_time; int ahead; diff --git a/src/framework/mlt_filter.c b/src/framework/mlt_filter.c index 3d81429..289a8d4 100644 --- a/src/framework/mlt_filter.c +++ b/src/framework/mlt_filter.c @@ -27,8 +27,13 @@ static int filter_get_frame( mlt_service this, mlt_frame_ptr frame, int index ); -/** Constructor method. -*/ +/** Initialize a new filter. + * + * \public \memberof mlt_filter_s + * \param this a filter + * \param child the object of a subclass + * \return true if there was an error + */ int mlt_filter_init( mlt_filter this, void *child ) { @@ -56,8 +61,11 @@ int mlt_filter_init( mlt_filter this, void *child ) return 1; } -/** Create a new filter. -*/ +/** Create a new filter and initialize it. + * + * \public \memberof mlt_filter_s + * \return a new filter + */ mlt_filter mlt_filter_new( ) { @@ -67,16 +75,26 @@ mlt_filter mlt_filter_new( ) return this; } -/** Get the service associated to this filter -*/ +/** Get the service class interface. + * + * \public \memberof mlt_filter_s + * \param this a filter + * \return the service parent class + * \see MLT_FILTER_SERVICE + */ mlt_service mlt_filter_service( mlt_filter this ) { return this != NULL ? &this->parent : NULL; } -/** Get the properties associated to this filter. -*/ +/** Get the filter properties. + * + * \public \memberof mlt_filter_s + * \param this a filter + * \return the properties list for the filter + * \see MLT_FILTER_PROPERTIES + */ mlt_properties mlt_filter_properties( mlt_filter this ) { @@ -84,13 +102,18 @@ mlt_properties mlt_filter_properties( mlt_filter this ) } /** Connect this filter to a producers track. Note that a filter only operates - on a single track, and by default it operates on the entirety of that track. -*/ + * on a single track, and by default it operates on the entirety of that track. + * + * \public \memberof mlt_filter_s + * \param this a filter + * \param producer the producer to which to connect this filter + * \param index which of potentially multiple producers to this service (0 based) + */ int mlt_filter_connect( mlt_filter this, mlt_service producer, int index ) { int ret = mlt_service_connect_producer( &this->parent, producer, index ); - + // If the connection was successful, grab the producer, track and reset in/out if ( ret == 0 ) { @@ -99,12 +122,18 @@ int mlt_filter_connect( mlt_filter this, mlt_service producer, int index ) mlt_properties_set_position( properties, "out", 0 ); mlt_properties_set_int( properties, "track", index ); } - + return ret; } -/** Tune the in/out points. -*/ +/** Set the starting and ending time. + * + * \public \memberof mlt_filter_s + * \param this a filter + * \param in the time relative to the producer at which start applying the filter + * \param out the time relative to the producer at which to stop applying the filter + */ + void mlt_filter_set_in_and_out( mlt_filter this, mlt_position in, mlt_position out ) { @@ -114,7 +143,12 @@ void mlt_filter_set_in_and_out( mlt_filter this, mlt_position in, mlt_position o } /** Return the track that this filter is operating on. -*/ + * + * \public \memberof mlt_filter_s + * \param this a filter + * \return true on error + */ + int mlt_filter_get_track( mlt_filter this ) { @@ -123,7 +157,12 @@ int mlt_filter_get_track( mlt_filter this ) } /** Get the in point. -*/ + * + * \public \memberof mlt_filter_s + * \param this a filter + * \return the start time for the filter relative to the producer + */ + mlt_position mlt_filter_get_in( mlt_filter this ) { @@ -132,7 +171,12 @@ mlt_position mlt_filter_get_in( mlt_filter this ) } /** Get the out point. -*/ + * + * \public \memberof mlt_filter_s + * \param this a filter + * \return the ending time for the filter relative to the producer + */ + mlt_position mlt_filter_get_out( mlt_filter this ) { @@ -141,7 +185,13 @@ mlt_position mlt_filter_get_out( mlt_filter this ) } /** Process the frame. -*/ + * + * \public \memberof mlt_filter_s + * \param this a filter + * \param frame a frame + * \return a frame + */ + mlt_frame mlt_filter_process( mlt_filter this, mlt_frame frame ) { @@ -153,7 +203,14 @@ mlt_frame mlt_filter_process( mlt_filter this, mlt_frame frame ) } /** Get a frame from this filter. -*/ + * + * \private \memberof mlt_filter_s + * \param service a service + * \param[out] frame a frame by reference + * \param index as determined by the producer + * \return true on error + */ + static int filter_get_frame( mlt_service service, mlt_frame_ptr frame, int index ) { @@ -163,7 +220,7 @@ static int filter_get_frame( mlt_service service, mlt_frame_ptr frame, int index int track = mlt_filter_get_track( this ); int in = mlt_filter_get_in( this ); int out = mlt_filter_get_out( this ); - + // Get the producer this is connected to mlt_service producer = mlt_service_producer( &this->parent ); @@ -190,8 +247,12 @@ static int filter_get_frame( mlt_service service, mlt_frame_ptr frame, int index } } -/** Close the filter. -*/ +/** Close and destroy the filter. + * + * \public \memberof mlt_filter_s + * \param this a filter + */ + void mlt_filter_close( mlt_filter this ) { diff --git a/src/framework/mlt_filter.h b/src/framework/mlt_filter.h index c67c9ab..a42cf55 100644 --- a/src/framework/mlt_filter.h +++ b/src/framework/mlt_filter.h @@ -25,27 +25,27 @@ /** \brief Filter abstract service class * + * A filter is a service that may modify the output of a single producer. + * * \extends mlt_service_s + * \properties \em track the index of the track of a multitrack on which the filter is applied */ struct mlt_filter_s { - /* We're implementing service here */ + /** We're implementing service here */ struct mlt_service_s parent; - /* public virtual */ + /** public virtual */ void ( *close )( mlt_filter ); - /* protected filter method */ + /** protected filter method */ mlt_frame ( *process )( mlt_filter, mlt_frame ); - /* Protected */ + /** Protected */ void *child; }; -/** Public final methods -*/ - #define MLT_FILTER_SERVICE( filter ) ( &( filter )->parent ) #define MLT_FILTER_PROPERTIES( filter ) MLT_SERVICE_PROPERTIES( MLT_FILTER_SERVICE( filter ) ) diff --git a/src/framework/mlt_frame.h b/src/framework/mlt_frame.h index 6850bd9..83300b9 100644 --- a/src/framework/mlt_frame.h +++ b/src/framework/mlt_frame.h @@ -46,6 +46,8 @@ typedef int ( *mlt_get_audio )( mlt_frame self, int16_t **buffer, mlt_audio_form * \properties \em _producer holds a reference to the frame's end producer * \properties \em _speed * \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 */ struct mlt_frame_s diff --git a/src/framework/mlt_multitrack.c b/src/framework/mlt_multitrack.c index 432b90c..a103852 100644 --- a/src/framework/mlt_multitrack.c +++ b/src/framework/mlt_multitrack.c @@ -27,12 +27,11 @@ #include #include -/** Forward reference. -*/ +/* Forward reference. */ static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int index ); -/** Constructor. +/** Construct and initialize a new multitrack. */ mlt_multitrack mlt_multitrack_init( ) diff --git a/src/framework/mlt_multitrack.h b/src/framework/mlt_multitrack.h index 5d272b3..4bd3e7f 100644 --- a/src/framework/mlt_multitrack.h +++ b/src/framework/mlt_multitrack.h @@ -38,6 +38,8 @@ typedef struct mlt_track_s *mlt_track; /** \brief Multitrack class * + * A multitrack is a parallel container of producers that acts a single producer. + * * \extends mlt_producer_s */ diff --git a/src/framework/mlt_producer.c b/src/framework/mlt_producer.c index 6646ed8..2202f55 100644 --- a/src/framework/mlt_producer.c +++ b/src/framework/mlt_producer.c @@ -50,7 +50,6 @@ static int producers_destroyed = 0; * \param this the producer structure to initialize * \param child a pointer to the child object for the subclass * \return true if there was an error - * \todo Document the special properties and events. */ int mlt_producer_init( mlt_producer this, void *child ) diff --git a/src/framework/mlt_service.c b/src/framework/mlt_service.c index 5491c13..a9f5eda 100644 --- a/src/framework/mlt_service.c +++ b/src/framework/mlt_service.c @@ -101,7 +101,9 @@ int mlt_service_init( mlt_service this, void *child ) return error; } -/** The listener for property changes. +/** The transmitter for property changes. + * + * Invokes the listener. * * \private \memberof mlt_service_s * \param listener a function pointer that will be invoked @@ -394,7 +396,6 @@ void mlt_service_apply_filters( mlt_service this, mlt_frame frame, int index ) mlt_service_base *base = this->local; mlt_position position = mlt_frame_get_position( frame ); mlt_position this_in = mlt_properties_get_position( service_properties, "in" ); - /** \properties \em out where to stop playing */ mlt_position this_out = mlt_properties_get_position( service_properties, "out" ); if ( index == 0 || mlt_properties_get_int( service_properties, "_filter_private" ) == 0 ) diff --git a/src/framework/mlt_service.h b/src/framework/mlt_service.h index 96a560a..86cbb96 100644 --- a/src/framework/mlt_service.h +++ b/src/framework/mlt_service.h @@ -42,7 +42,8 @@ * \event \em property-changed * \properties \em mlt_type identifies the subclass * \properties \em resource is either the stream identifier or grandchild-class - * \properties \em in where to start playing + * \properties \em in when to start, what is started is service-specific + * \properties \em out when to stop * \properties \em _filter_private Set this on a service to ensure that attached filters are handled privately. * 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. diff --git a/src/framework/mlt_transition.c b/src/framework/mlt_transition.c index 7ab5f2f..d7e6d5d 100644 --- a/src/framework/mlt_transition.c +++ b/src/framework/mlt_transition.c @@ -27,13 +27,17 @@ #include #include -/** Forward references. -*/ +/* Forward references */ static int transition_get_frame( mlt_service this, mlt_frame_ptr frame, int index ); -/** Constructor. -*/ +/** Initialize a new transition. + * + * \public \memberof mlt_transition_s + * \param this a transition + * \param child the object of a subclass + * \return true on error + */ int mlt_transition_init( mlt_transition this, void *child ) { @@ -58,8 +62,11 @@ int mlt_transition_init( mlt_transition this, void *child ) return 1; } -/** Create a new transition. -*/ +/** Create and initialize a new transition. + * + * \public \memberof mlt_transition_s + * \return a new transition + */ mlt_transition mlt_transition_new( ) { @@ -69,8 +76,13 @@ mlt_transition mlt_transition_new( ) return this; } -/** Get the service associated to the transition. -*/ +/** Get the service class interface. + * + * \public \memberof mlt_transition_s + * \param this a transition + * \return the service class + * \see MLT_TRANSITION_SERVICE + */ mlt_service mlt_transition_service( mlt_transition this ) { @@ -78,7 +90,12 @@ mlt_service mlt_transition_service( mlt_transition this ) } /** Get the properties interface. -*/ + * + * \public \memberof mlt_transition_s + * \param this a transition + * \return the transition's properties + * \see MLT_TRANSITION_PROPERTIES + */ mlt_properties mlt_transition_properties( mlt_transition this ) { @@ -86,7 +103,14 @@ mlt_properties mlt_transition_properties( mlt_transition this ) } /** Connect this transition with a producers a and b tracks. -*/ + * + * \public \memberof mlt_transition_s + * \param this a transition + * \param producer a producer + * \param a_track the track index of the first input + * \param b_track the track index of the second index + * \return true on error + */ int mlt_transition_connect( mlt_transition this, mlt_service producer, int a_track, int b_track ) { @@ -101,8 +125,13 @@ int mlt_transition_connect( mlt_transition this, mlt_service producer, int a_tra return ret; } -/** Set the in and out points. -*/ +/** Set the starting and ending time for when the transition is active. + * + * \public \memberof mlt_transition_s + * \param this a transition + * \param in the starting time + * \param out the ending time + */ void mlt_transition_set_in_and_out( mlt_transition this, mlt_position in, mlt_position out ) { @@ -112,7 +141,11 @@ void mlt_transition_set_in_and_out( mlt_transition this, mlt_position in, mlt_po } /** Get the index of the a track. -*/ + * + * \public \memberof mlt_transition_s + * \param this a transition + * \return the 0-based index of the track of the first producer + */ int mlt_transition_get_a_track( mlt_transition this ) { @@ -120,7 +153,11 @@ int mlt_transition_get_a_track( mlt_transition this ) } /** Get the index of the b track. -*/ + * + * \public \memberof mlt_transition_s + * \param this a transition + * \return the 0-based index of the track of the second producer + */ int mlt_transition_get_b_track( mlt_transition this ) { @@ -128,7 +165,11 @@ int mlt_transition_get_b_track( mlt_transition this ) } /** Get the in point. -*/ + * + * \public \memberof mlt_transition_s + * \param this a transition + * \return the starting time + */ mlt_position mlt_transition_get_in( mlt_transition this ) { @@ -136,7 +177,11 @@ mlt_position mlt_transition_get_in( mlt_transition this ) } /** Get the out point. -*/ + * + * \public \memberof mlt_transition_s + * \param this a transition + * \return the ending time + */ mlt_position mlt_transition_get_out( mlt_transition this ) { @@ -144,9 +189,15 @@ mlt_position mlt_transition_get_out( mlt_transition this ) } /** Process the frame. - - If we have no process method (unlikely), we simply return the a_frame unmolested. -*/ + * + * If we have no process method (unlikely), we simply return the a_frame unmolested. + * + * \public \memberof mlt_transition_s + * \param this a transition + * \param a_frame a frame from the first producer + * \param b_frame a frame from the second producer + * \return a frame + */ mlt_frame mlt_transition_process( mlt_transition this, mlt_frame a_frame, mlt_frame b_frame ) { @@ -163,7 +214,7 @@ mlt_frame mlt_transition_process( mlt_transition this, mlt_frame a_frame, mlt_fr 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: - +
 	+---------+                               +-------+
 	|c1       |                               |c5     | <-- A(0,1) <-- B(0,2) <-- get frame
 	+---------+                     +---------+-+-----+        |          |
@@ -171,7 +222,7 @@ mlt_frame mlt_transition_process( mlt_transition this, mlt_frame a_frame, mlt_fr
 	         +----------+-----------+-+---------+                         |
 	         |c2        |c3           |                 <-----------------+
 	         +----------+-------------+
-
+
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, @@ -186,7 +237,13 @@ mlt_frame mlt_transition_process( mlt_transition this, mlt_frame a_frame, mlt_fr 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 + */ static int transition_get_frame( mlt_service service, mlt_frame_ptr frame, int index ) { @@ -304,8 +361,11 @@ static int transition_get_frame( mlt_service service, mlt_frame_ptr frame, int i return error; } -/** Close the transition. -*/ +/** Close and destroy the transition. + * + * \public \memberof mlt_transition_s + * \param this a transition + */ void mlt_transition_close( mlt_transition this ) { diff --git a/src/framework/mlt_transition.h b/src/framework/mlt_transition.h index 0a38157..7f11c3b 100644 --- a/src/framework/mlt_transition.h +++ b/src/framework/mlt_transition.h @@ -27,34 +27,38 @@ /** \brief Transition abstract service class * + * A transition may modify the output of a producer based on the output of a second producer. + * * \extends mlt_service_s + * \properties \em a_track the track index (0-based) of a multitrack of the first producer + * \properties \em b_track the track index (0-based) of a multitrack of the second producer + * \properties \em accepts_blanks a flag to indicate if the transition should accept blank frames + * \properties \em always_active a flag to indicate that the in and out points do not apply + * \properties \em _transition_type 1 for video, 2 for audio */ struct mlt_transition_s { - /* We're implementing service here */ + /** We're implementing service here */ struct mlt_service_s parent; - /* public virtual */ + /** public virtual */ void ( *close )( mlt_transition ); - /* protected transition method */ + /** protected transition method */ mlt_frame ( *process )( mlt_transition, mlt_frame, mlt_frame ); - /* Protected */ + /** Protected */ void *child; - /* track and in/out points */ + /** track and in/out points */ mlt_service producer; - /* Private */ + /** Private */ mlt_frame *frames; int held; }; -/** Public final methods -*/ - #define MLT_TRANSITION_SERVICE( transition ) ( &( transition )->parent ) #define MLT_TRANSITION_PROPERTIES( transition ) MLT_SERVICE_PROPERTIES( MLT_TRANSITION_SERVICE( transition ) )