X-Git-Url: http://research.m1stereo.tv/gitweb?a=blobdiff_plain;f=src%2Fframework%2Fmlt_producer.c;h=2a6a4875b3ee81206cd4722cb4edf460c638086c;hb=51f99c29759e71318c4c575f8a68cf1b5d1c5137;hp=5d3963c5e52e42f0413842b5ef5ee6eab54c0043;hpb=a07c3da76259d6ba479d800ffecc5617a9ad158f;p=melted diff --git a/src/framework/mlt_producer.c b/src/framework/mlt_producer.c index 5d3963c..2a6a487 100644 --- a/src/framework/mlt_producer.c +++ b/src/framework/mlt_producer.c @@ -1,7 +1,9 @@ -/* - * mlt_producer.c -- abstraction for all producer services - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_producer.c + * \brief abstraction for all producer services + * + * Copyright (C) 2003-2008 Ushodaya Enterprises Limited + * \author Charles Yates * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -18,34 +20,38 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -#include "config.h" #include "mlt_producer.h" #include "mlt_factory.h" #include "mlt_frame.h" #include "mlt_parser.h" #include "mlt_profile.h" +#include "mlt_log.h" #include #include #include #include -/** Forward references. -*/ +/* Forward references. */ static int producer_get_frame( mlt_service this, mlt_frame_ptr frame, int index ); static void mlt_producer_property_changed( mlt_service owner, mlt_producer this, char *name ); static void mlt_producer_service_changed( mlt_service owner, mlt_producer this ); +/* for debugging */ //#define _MLT_PRODUCER_CHECKS_ 1 - #ifdef _MLT_PRODUCER_CHECKS_ static int producers_created = 0; static int producers_destroyed = 0; #endif -/** Constructor -*/ +/** Initialize a producer service. + * + * \public \memberof mlt_producer_s + * \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 + */ int mlt_producer_init( mlt_producer this, void *child ) { @@ -61,7 +67,7 @@ int mlt_producer_init( mlt_producer this, void *child ) // Initialise the producer memset( this, 0, sizeof( struct mlt_producer_s ) ); - + // Associate with the child this->child = child; @@ -70,7 +76,7 @@ int mlt_producer_init( mlt_producer this, void *child ) { // The parent is the service mlt_service parent = &this->parent; - + // Define the parent close parent->close = ( mlt_destructor )mlt_producer_close; parent->close_object = this; @@ -80,7 +86,7 @@ int mlt_producer_init( mlt_producer this, void *child ) // Get the properties of the parent mlt_properties properties = MLT_SERVICE_PROPERTIES( parent ); - + // Set the default properties mlt_properties_set( properties, "mlt_type", "mlt_producer" ); mlt_properties_set_position( properties, "_position", 0.0 ); @@ -106,7 +112,14 @@ int mlt_producer_init( mlt_producer this, void *child ) } /** Listener for property changes. -*/ + * + * If the in, out, or length properties changed, fire a "producer-changed" event. + * + * \private \memberof mlt_producer_s + * \param owner a service (ignored) + * \param this the producer + * \param name the property that changed + */ static void mlt_producer_property_changed( mlt_service owner, mlt_producer this, char *name ) { @@ -115,15 +128,24 @@ static void mlt_producer_property_changed( mlt_service owner, mlt_producer this, } /** Listener for service changes. -*/ + * + * Fires the "producer-changed" event. + * + * \private \memberof mlt_producer_s + * \param owner a service (ignored) + * \param this the producer + */ static void mlt_producer_service_changed( mlt_service owner, mlt_producer this ) { mlt_events_fire( MLT_PRODUCER_PROPERTIES( mlt_producer_cut_parent( this ) ), "producer-changed", NULL ); } -/** Create a new producer. -*/ +/** Create and initialize a new producer. + * + * \public \memberof mlt_producer_s + * \return the new producer + */ mlt_producer mlt_producer_new( ) { @@ -133,7 +155,12 @@ mlt_producer mlt_producer_new( ) } /** Determine if producer is a cut. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return true if \p this is a "cut" producer + * \see mlt_producer_cut + */ int mlt_producer_is_cut( mlt_producer this ) { @@ -141,7 +168,12 @@ int mlt_producer_is_cut( mlt_producer this ) } /** Determine if producer is a mix. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return true if this is a "mix" producer + * \todo Define a mix producer. + */ int mlt_producer_is_mix( mlt_producer this ) { @@ -150,8 +182,14 @@ int mlt_producer_is_mix( mlt_producer this ) return tractor != NULL; } -/** Determine if the producer is a blank [from a playlist]. -*/ +/** Determine if the producer is a blank. + * + * Blank producers should only appear as an item in a playlist. + * \public \memberof mlt_producer_s + * \param this a producer + * \return true if this is a "blank" producer + * \see mlt_playlist_insert_blank + */ int mlt_producer_is_blank( mlt_producer this ) { @@ -159,7 +197,11 @@ int mlt_producer_is_blank( mlt_producer this ) } /** Obtain the parent producer. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return either the parent producer if this is a "cut" producer or \p this otherwise. + */ mlt_producer mlt_producer_cut_parent( mlt_producer this ) { @@ -170,8 +212,17 @@ mlt_producer mlt_producer_cut_parent( mlt_producer this ) return this; } -/** Create a cut of this producer -*/ +/** Create a cut of this producer. + * + * A "cut" is a portion of another (parent) producer. + * + * \public \memberof mlt_producer_s + * \param this a producer + * \param in the beginning + * \param out the end + * \return the new producer + * \todo Expand on the value of a cut. + */ mlt_producer mlt_producer_cut( mlt_producer this, int in, int out ) { @@ -198,7 +249,12 @@ mlt_producer mlt_producer_cut( mlt_producer this, int in, int out ) } /** Get the parent service object. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the service parent class + * \see MLT_PRODUCER_SERVICE + */ mlt_service mlt_producer_service( mlt_producer this ) { @@ -206,7 +262,12 @@ mlt_service mlt_producer_service( mlt_producer this ) } /** Get the producer properties. -*/ + * + * \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 ) { @@ -214,7 +275,13 @@ mlt_properties mlt_producer_properties( mlt_producer this ) } /** Seek to a specified position. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \param position set the "play head" position of the producer + * \return false + * \todo Document how the properties affect behavior. + */ int mlt_producer_seek( mlt_producer this, mlt_position position ) { @@ -253,7 +320,11 @@ int mlt_producer_seek( mlt_producer this, mlt_position position ) } /** Get the current position (relative to in point). -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the position of the "play head" relative to its beginning + */ mlt_position mlt_producer_position( mlt_producer this ) { @@ -261,7 +332,11 @@ mlt_position mlt_producer_position( mlt_producer this ) } /** Get the current position (relative to start of producer). -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the position of the "play head" regardless of the in point + */ mlt_position mlt_producer_frame( mlt_producer this ) { @@ -269,7 +344,12 @@ mlt_position mlt_producer_frame( mlt_producer this ) } /** Set the playing speed. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \param speed the new speed as a relative factor (1.0 = normal) + * \return + */ int mlt_producer_set_speed( mlt_producer this, double speed ) { @@ -277,7 +357,11 @@ int mlt_producer_set_speed( mlt_producer this, double speed ) } /** Get the playing speed. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the speed as a relative factor (1.0 = normal) + */ double mlt_producer_get_speed( mlt_producer this ) { @@ -285,15 +369,34 @@ double mlt_producer_get_speed( mlt_producer this ) } /** Get the frames per second. -*/ + * + * This is determined by the producer's profile. + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the video refresh rate + */ double mlt_producer_get_fps( mlt_producer this ) { - return mlt_profile_fps( NULL ); + mlt_profile profile = mlt_service_profile( MLT_PRODUCER_SERVICE( this ) ); + return mlt_profile_fps( profile ); } /** Set the in and out points. -*/ + * + * The in point is where play out should start relative to the natural start + * of the underlying file. The out point is where play out should end, also + * relative to the start of the underlying file. If the underlying resource is + * a live stream, then the in point is an offset relative to first usable + * sample. + * + * \public \memberof mlt_producer_s + * \param this a producer + * \param in the relative starting time + * \param out the relative ending time + * \return false + */ int mlt_producer_set_in_and_out( mlt_producer this, mlt_position in, mlt_position out ) { @@ -330,8 +433,12 @@ int mlt_producer_set_in_and_out( mlt_producer this, mlt_position in, mlt_positio } /** Physically reduce the producer (typically a cut) to a 0 length. - Essentially, all 0 length cuts should be immediately removed by containers. -*/ + * Essentially, all 0 length cuts should be immediately removed by containers. + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return false + */ int mlt_producer_clear( mlt_producer this ) { @@ -347,7 +454,11 @@ int mlt_producer_clear( mlt_producer this ) } /** Get the in point. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the in point + */ mlt_position mlt_producer_get_in( mlt_producer this ) { @@ -355,7 +466,11 @@ mlt_position mlt_producer_get_in( mlt_producer this ) } /** Get the out point. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the out point + */ mlt_position mlt_producer_get_out( mlt_producer this ) { @@ -363,15 +478,25 @@ mlt_position mlt_producer_get_out( mlt_producer this ) } /** Get the total play time. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the playable (based on in and out points) duration + */ 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. + * + * \public \memberof mlt_producer_s + * \param this a producer + * \return the duration of the producer regardless of in and out points + */ mlt_position mlt_producer_get_length( mlt_producer this ) { @@ -379,7 +504,13 @@ mlt_position mlt_producer_get_length( mlt_producer this ) } /** Prepare for next frame. -*/ + * + * Advance the play out position. If the speed is less than zero, it will + * move the play out position in the reverse direction. + * + * \public \memberof mlt_producer_s + * \param this a producer + */ void mlt_producer_prepare_next( mlt_producer this ) { @@ -388,7 +519,20 @@ void mlt_producer_prepare_next( mlt_producer this ) } /** Get a frame. -*/ + * + * This is the implementation of the \p get_frame virtual function. + * It requests a new frame object from the actual producer for the current + * play out position. The producer and its filters can add information and + * operations to the frame object in their get_frame handlers. + * + * \private \memberof mlt_producer_s + * \param service a service + * \param[out] frame a frame by reference + * \param index as determined by the actual producer + * \return true if there was an error + * \todo Learn more about the details and document how certain properties affect + * its behavior. + */ static int producer_get_frame( mlt_service service, mlt_frame_ptr frame, int index ) { @@ -416,7 +560,7 @@ static int producer_get_frame( mlt_service service, mlt_frame_ptr frame, int ind if ( this->get_frame == NULL || ( !strcmp( eof, "continue" ) && mlt_producer_position( this ) > mlt_producer_get_out( this ) ) ) { // Generate a test frame - *frame = mlt_frame_init( ); + *frame = mlt_frame_init( service ); // Set the position result = mlt_frame_set_position( *frame, mlt_producer_position( this ) ); @@ -467,7 +611,7 @@ static int producer_get_frame( mlt_service service, mlt_frame_ptr frame, int ind char key[ 25 ]; sprintf( key, "_clone.%d", clone_index - 1 ); clone = mlt_properties_get_data( MLT_PRODUCER_PROPERTIES( mlt_producer_cut_parent( this ) ), key, NULL ); - if ( clone == NULL ) fprintf( stderr, "requested clone doesn't exist %d\n", clone_index ); + if ( clone == NULL ) mlt_log( service, MLT_LOG_ERROR, "requested clone doesn't exist %d\n", clone_index ); clone = clone == NULL ? this : clone; } else @@ -496,7 +640,7 @@ static int producer_get_frame( mlt_service service, mlt_frame_ptr frame, int ind } else { - *frame = mlt_frame_init( ); + *frame = mlt_frame_init( service ); result = 0; } @@ -521,7 +665,12 @@ static int producer_get_frame( mlt_service service, mlt_frame_ptr frame, int ind } /** Attach a filter. -*/ + * + * \public \memberof mlt_producer_s + * \param this a producer + * \param filter the filter to attach + * \return true if there was an error + */ int mlt_producer_attach( mlt_producer this, mlt_filter filter ) { @@ -529,7 +678,12 @@ int mlt_producer_attach( mlt_producer this, mlt_filter filter ) } /** Detach a filter. -*/ + * + * \public \memberof mlt_producer_s + * \param this a service + * \param filter the filter to detach + * \return true if there was an error + */ int mlt_producer_detach( mlt_producer this, mlt_filter filter ) { @@ -537,7 +691,12 @@ int mlt_producer_detach( mlt_producer this, mlt_filter filter ) } /** Retrieve a filter. -*/ + * + * \public \memberof mlt_producer_s + * \param this a service + * \param index which filter to retrieve + * \return the filter or null if there was an error + */ mlt_filter mlt_producer_filter( mlt_producer this, int index ) { @@ -545,7 +704,12 @@ mlt_filter mlt_producer_filter( mlt_producer this, int index ) } /** Clone this producer. -*/ + * + * \private \memberof mlt_producer_s + * \param this a producer + * \return a new producer that is a copy of \p this + * \see mlt_producer_set_clones + */ static mlt_producer mlt_producer_clone( mlt_producer this ) { @@ -553,14 +717,15 @@ static mlt_producer mlt_producer_clone( mlt_producer this ) mlt_properties properties = MLT_PRODUCER_PROPERTIES( this ); char *resource = mlt_properties_get( properties, "resource" ); char *service = mlt_properties_get( properties, "mlt_service" ); + mlt_profile profile = mlt_service_profile( MLT_PRODUCER_SERVICE( this ) ); mlt_events_block( mlt_factory_event_object( ), mlt_factory_event_object( ) ); if ( service != NULL ) - clone = mlt_factory_producer( service, resource ); + clone = mlt_factory_producer( profile, service, resource ); if ( clone == NULL && resource != NULL ) - clone = mlt_factory_producer( "fezzik", resource ); + clone = mlt_factory_producer( profile, mlt_environment( "MLT_PRODUCER" ), resource ); if ( clone != NULL ) mlt_properties_inherit( MLT_PRODUCER_PROPERTIES( clone ), properties ); @@ -571,7 +736,12 @@ static mlt_producer mlt_producer_clone( mlt_producer this ) } /** Create clones. -*/ + * + * \private \memberof mlt_producer_s + * \param this a producer + * \param clones the number of copies to make + * \see mlt_producer_optimise + */ static void mlt_producer_set_clones( mlt_producer this, int clones ) { @@ -617,10 +787,9 @@ static void mlt_producer_set_clones( mlt_producer this, int clones ) mlt_properties_set_int( properties, "_clones", clones ); } -/** Optimise for overlapping cuts from the same clip. -*/ +/** \brief private to mlt_producer_s, used by mlt_producer_optimise() */ -typedef struct +typedef struct { int multitrack; int track; @@ -630,6 +799,8 @@ typedef struct } track_info; +/** \brief private to mlt_producer_s, used by mlt_producer_optimise() */ + typedef struct { mlt_producer cut; @@ -737,6 +908,14 @@ static int on_end_multitrack( mlt_parser this, mlt_multitrack object ) return 0; } +/** Optimise for overlapping cuts from the same clip. + * + * \todo learn more about this + * \public \memberof mlt_producer_s + * \param this a producer + * \return true if there was an error + */ + int mlt_producer_optimise( mlt_producer this ) { int error = 1; @@ -808,7 +987,15 @@ int mlt_producer_optimise( mlt_producer this ) } /** Close the producer. -*/ + * + * Destroys the producer and deallocates its resources managed by its + * properties list. This will call the close virtual function. Therefore, a + * subclass that defines its own close function should set its virtual close + * function to NULL prior to calling this to avoid circular calls. + * + * \public \memberof mlt_producer_s + * \param this a producer + */ void mlt_producer_close( mlt_producer this ) { @@ -830,11 +1017,8 @@ void mlt_producer_close( mlt_producer this ) #endif #ifdef _MLT_PRODUCER_CHECKS_ - // Increment destroyed count - producers_destroyed ++; - // Show current stats - these should match when the app is closed - fprintf( stderr, "Producers created %d, destroyed %d\n", producers_created, producers_destroyed ); + mlt_log( MLT_PRODUCER_SERVICE( this ), MLT_LOG_DEBUG, "Producers created %d, destroyed %d\n", producers_created, ++producers_destroyed ); #endif mlt_service_close( &this->parent );