3 * \brief interface definition for all service classes
6 * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
7 * \author Charles Yates <charles.yates@pandora.be>
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library; if not, write to the Free Software
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 #include "mlt_service.h"
25 #include "mlt_filter.h"
26 #include "mlt_frame.h"
27 #include "mlt_cache.h"
28 #include "mlt_factory.h"
30 #include "mlt_producer.h"
40 The base service implements a null frame producing service - as such,
41 it is functional without extension and will produce test cards frames
42 and PAL sized audio frames.
44 PLEASE DO NOT CHANGE THIS BEHAVIOUR!!! OVERRIDE THE METHODS THAT
45 CONTROL THIS IN EXTENDING CLASSES.
48 /** \brief private service definition */
59 pthread_mutex_t mutex;
66 static void mlt_service_disconnect( mlt_service this );
67 static void mlt_service_connect( mlt_service this, mlt_service that );
68 static int service_get_frame( mlt_service this, mlt_frame_ptr frame, int index );
69 static void mlt_service_property_changed( mlt_listener, mlt_properties owner, mlt_service this, void **args );
71 /** Initialize a service.
73 * \public \memberof mlt_service_s
74 * \param this the service structure to initialize
75 * \param child pointer to the child object for the subclass
76 * \return true if there was an error
79 int mlt_service_init( mlt_service this, void *child )
83 // Initialise everything to NULL
84 memset( this, 0, sizeof( struct mlt_service_s ) );
89 // Generate local space
90 this->local = calloc( sizeof( mlt_service_base ), 1 );
92 // Associate the methods
93 this->get_frame = service_get_frame;
95 // Initialise the properties
96 error = mlt_properties_init( &this->parent, this );
99 this->parent.close = ( mlt_destructor )mlt_service_close;
100 this->parent.close_object = this;
102 mlt_events_init( &this->parent );
103 mlt_events_register( &this->parent, "service-changed", NULL );
104 mlt_events_register( &this->parent, "property-changed", ( mlt_transmitter )mlt_service_property_changed );
105 pthread_mutex_init( &( ( mlt_service_base * )this->local )->mutex, NULL );
111 /** The transmitter for property changes.
113 * Invokes the listener.
115 * \private \memberof mlt_service_s
116 * \param listener a function pointer that will be invoked
117 * \param owner a properties list that will be passed to \p listener
118 * \param this a service that will be passed to \p listener
119 * \param args an array of pointers - the first entry is passed as a string to \p listener
122 static void mlt_service_property_changed( mlt_listener listener, mlt_properties owner, mlt_service this, void **args )
124 if ( listener != NULL )
125 listener( owner, this, ( char * )args[ 0 ] );
128 /** Acquire a mutual exclusion lock on this service.
130 * \public \memberof mlt_service_s
131 * \param this the service to lock
134 void mlt_service_lock( mlt_service this )
137 pthread_mutex_lock( &( ( mlt_service_base * )this->local )->mutex );
140 /** Release a mutual exclusion lock on this service.
142 * \public \memberof mlt_service_s
143 * \param this the service to unlock
146 void mlt_service_unlock( mlt_service this )
149 pthread_mutex_unlock( &( ( mlt_service_base * )this->local )->mutex );
152 /** Identify the subclass of the service.
154 * \public \memberof mlt_service_s
155 * \param this a service
156 * \return the subclass
159 mlt_service_type mlt_service_identify( mlt_service this )
161 mlt_service_type type = invalid_type;
164 mlt_properties properties = MLT_SERVICE_PROPERTIES( this );
165 char *mlt_type = mlt_properties_get( properties, "mlt_type" );
166 char *resource = mlt_properties_get( properties, "resource" );
167 if ( mlt_type == NULL )
169 else if (resource != NULL && !strcmp( resource, "<playlist>" ) )
170 type = playlist_type;
171 else if (resource != NULL && !strcmp( resource, "<tractor>" ) )
173 else if (resource != NULL && !strcmp( resource, "<multitrack>" ) )
174 type = multitrack_type;
175 else if ( !strcmp( mlt_type, "producer" ) )
176 type = producer_type;
177 else if ( !strcmp( mlt_type, "filter" ) )
179 else if ( !strcmp( mlt_type, "transition" ) )
180 type = transition_type;
181 else if ( !strcmp( mlt_type, "consumer" ) )
182 type = consumer_type;
189 /** Connect a producer to the service.
191 * \public \memberof mlt_service_s
192 * \param this a service
193 * \param producer a producer
194 * \param index which of potentially multiple producers to this service (0 based)
195 * \return > 0 warning, == 0 success, < 0 serious error,
196 * 1 = this service does not accept input,
197 * 2 = the producer is invalid,
198 * 3 = the producer is already registered with this consumer
201 int mlt_service_connect_producer( mlt_service this, mlt_service producer, int index )
205 // Get the service base
206 mlt_service_base *base = this->local;
208 // Special case 'track' index - only works for last filter(s) in a particular chain
209 // but allows a filter to apply to the output frame regardless of which track it comes from
213 // Check if the producer is already registered with this service
214 for ( i = 0; i < base->count; i ++ )
215 if ( base->in[ i ] == producer )
219 if ( index >= base->size )
221 int new_size = base->size + index + 10;
222 base->in = realloc( base->in, new_size * sizeof( mlt_service ) );
223 if ( base->in != NULL )
225 for ( i = base->size; i < new_size; i ++ )
226 base->in[ i ] = NULL;
227 base->size = new_size;
231 // If we have space, assign the input
232 if ( base->in != NULL && index >= 0 && index < base->size )
234 // Get the current service
235 mlt_service current = base->in[ index ];
237 // Increment the reference count on this producer
238 if ( producer != NULL )
239 mlt_properties_inc_ref( MLT_SERVICE_PROPERTIES( producer ) );
241 // Now we disconnect the producer service from its consumer
242 mlt_service_disconnect( producer );
244 // Add the service to index specified
245 base->in[ index ] = producer;
247 // Determine the number of active tracks
248 if ( index >= base->count )
249 base->count = index + 1;
251 // Now we connect the producer to its connected consumer
252 mlt_service_connect( producer, this );
254 // Close the current service
255 mlt_service_close( current );
257 // Inform caller that all went well
266 /** Disconnect this service from its consumer.
268 * \public \memberof mlt_service_s
269 * \param this a service
272 static void mlt_service_disconnect( mlt_service this )
276 // Get the service base
277 mlt_service_base *base = this->local;
284 /** Obtain the consumer this service is connected to.
286 * \public \memberof mlt_service_s
287 * \param this a service
288 * \return the consumer
291 mlt_service mlt_service_consumer( mlt_service this )
293 // Get the service base
294 mlt_service_base *base = this->local;
296 // Return the connected consumer
300 /** Obtain the producer this service is connected to.
302 * \public \memberof mlt_service_s
303 * \param this a service
304 * \return the last-most producer
307 mlt_service mlt_service_producer( mlt_service this )
309 // Get the service base
310 mlt_service_base *base = this->local;
312 // Return the connected producer
313 return base->count > 0 ? base->in[ base->count - 1 ] : NULL;
316 /** Associate this service to a consumer.
318 * Overwrites connection to any existing consumer.
319 * \private \memberof mlt_service_s
320 * \param this a service
321 * \param that a consumer
324 static void mlt_service_connect( mlt_service this, mlt_service that )
328 // Get the service base
329 mlt_service_base *base = this->local;
331 // There's a bit more required here...
336 /** Get the first connected producer.
338 * \public \memberof mlt_service_s
339 * \param this a service
340 * \return the first producer
343 mlt_service mlt_service_get_producer( mlt_service this )
345 mlt_service producer = NULL;
347 // Get the service base
348 mlt_service_base *base = this->local;
350 if ( base->in != NULL )
351 producer = base->in[ 0 ];
356 /** Default implementation of the get_frame virtual function.
358 * \private \memberof mlt_service_s
359 * \param this a service
360 * \param[out] frame a frame by reference
361 * \param index as determined by the producer
365 static int service_get_frame( mlt_service this, mlt_frame_ptr frame, int index )
367 mlt_service_base *base = this->local;
368 if ( index < base->count )
370 mlt_service producer = base->in[ index ];
371 if ( producer != NULL )
372 return mlt_service_get_frame( producer, frame, index );
374 *frame = mlt_frame_init( this );
378 /** Return the properties object.
380 * \public \memberof mlt_service_s
381 * \param this a service
382 * \return the properties
385 mlt_properties mlt_service_properties( mlt_service this )
387 return this != NULL ? &this->parent : NULL;
390 /** Recursively apply attached filters.
392 * \public \memberof mlt_service_s
393 * \param this a service
394 * \param frame a frame
395 * \param index used to track depth of recursion, top caller should supply 0
398 void mlt_service_apply_filters( mlt_service this, mlt_frame frame, int index )
401 mlt_properties frame_properties = MLT_FRAME_PROPERTIES( frame );
402 mlt_properties service_properties = MLT_SERVICE_PROPERTIES( this );
403 mlt_service_base *base = this->local;
404 mlt_position position = mlt_frame_get_position( frame );
405 mlt_position this_in = mlt_properties_get_position( service_properties, "in" );
406 mlt_position this_out = mlt_properties_get_position( service_properties, "out" );
408 if ( index == 0 || mlt_properties_get_int( service_properties, "_filter_private" ) == 0 )
410 // Process the frame with the attached filters
411 for ( i = 0; i < base->filter_count; i ++ )
413 if ( base->filters[ i ] != NULL )
415 mlt_position in = mlt_filter_get_in( base->filters[ i ] );
416 mlt_position out = mlt_filter_get_out( base->filters[ i ] );
417 int disable = mlt_properties_get_int( MLT_FILTER_PROPERTIES( base->filters[ i ] ), "disable" );
418 if ( !disable && ( ( in == 0 && out == 0 ) || ( position >= in && ( position <= out || out == 0 ) ) ) )
420 mlt_properties_set_position( frame_properties, "in", in == 0 ? this_in : in );
421 mlt_properties_set_position( frame_properties, "out", out == 0 ? this_out : out );
422 mlt_filter_process( base->filters[ i ], frame );
423 mlt_service_apply_filters( MLT_FILTER_SERVICE( base->filters[ i ] ), frame, index + 1 );
432 * \public \memberof mlt_service_s
433 * \param this a service
434 * \param[out] frame a frame by reference
435 * \param index as determined by the producer
436 * \return true if there was an error
439 int mlt_service_get_frame( mlt_service this, mlt_frame_ptr frame, int index )
444 mlt_service_lock( this );
446 // Ensure that the frame is NULL
449 // Only process if we have a valid service
450 if ( this != NULL && this->get_frame != NULL )
452 mlt_properties properties = MLT_SERVICE_PROPERTIES( this );
453 mlt_position in = mlt_properties_get_position( properties, "in" );
454 mlt_position out = mlt_properties_get_position( properties, "out" );
455 mlt_position position = mlt_service_identify( this ) == producer_type ? mlt_producer_position( MLT_PRODUCER( this ) ) : -1;
457 result = this->get_frame( this, frame, index );
461 mlt_properties_inc_ref( properties );
462 properties = MLT_FRAME_PROPERTIES( *frame );
464 if ( in >=0 && out > 0 )
466 mlt_properties_set_position( properties, "in", in );
467 mlt_properties_set_position( properties, "out", out );
469 mlt_service_apply_filters( this, *frame, 1 );
470 mlt_deque_push_back( MLT_FRAME_SERVICE_STACK( *frame ), this );
472 if ( mlt_service_identify( this ) == producer_type &&
473 mlt_properties_get_int( MLT_SERVICE_PROPERTIES( this ), "_need_previous_next" ) )
475 // Save the new position from this->get_frame
476 mlt_position new_position = mlt_producer_position( MLT_PRODUCER( this ) );
478 // Get the preceding frame, unfiltered
479 mlt_frame previous_frame;
480 mlt_producer_seek( MLT_PRODUCER(this), position - 1 );
481 result = this->get_frame( this, &previous_frame, index );
483 mlt_properties_set_data( properties, "previous frame",
484 previous_frame, 0, ( mlt_destructor ) mlt_frame_close, NULL );
486 // Get the following frame, unfiltered
487 mlt_frame next_frame;
488 mlt_producer_seek( MLT_PRODUCER(this), position + 1 );
489 result = this->get_frame( this, &next_frame, index );
492 mlt_properties_set_data( properties, "next frame",
493 next_frame, 0, ( mlt_destructor ) mlt_frame_close, NULL );
496 // Restore the new position
497 mlt_producer_seek( MLT_PRODUCER(this), new_position );
502 // Make sure we return a frame
503 if ( *frame == NULL )
504 *frame = mlt_frame_init( this );
506 // Unlock the service
507 mlt_service_unlock( this );
512 /** The service-changed event handler.
514 * \private \memberof mlt_service_s
515 * \param owner ignored
516 * \param this the service on which the "service-changed" event is fired
519 static void mlt_service_filter_changed( mlt_service owner, mlt_service this )
521 mlt_events_fire( MLT_SERVICE_PROPERTIES( this ), "service-changed", NULL );
526 * \public \memberof mlt_service_s
527 * \param this a service
528 * \param filter the filter to attach
529 * \return true if there was an error
532 int mlt_service_attach( mlt_service this, mlt_filter filter )
534 int error = this == NULL || filter == NULL;
538 mlt_properties properties = MLT_SERVICE_PROPERTIES( this );
539 mlt_service_base *base = this->local;
541 for ( i = 0; error == 0 && i < base->filter_count; i ++ )
542 if ( base->filters[ i ] == filter )
547 if ( base->filter_count == base->filter_size )
549 base->filter_size += 10;
550 base->filters = realloc( base->filters, base->filter_size * sizeof( mlt_filter ) );
553 if ( base->filters != NULL )
555 mlt_properties props = MLT_FILTER_PROPERTIES( filter );
556 mlt_properties_inc_ref( MLT_FILTER_PROPERTIES( filter ) );
557 base->filters[ base->filter_count ++ ] = filter;
558 mlt_properties_set_data( props, "service", this, 0, NULL, NULL );
559 mlt_events_fire( properties, "service-changed", NULL );
560 mlt_events_fire( props, "service-changed", NULL );
561 mlt_events_listen( props, this, "service-changed", ( mlt_listener )mlt_service_filter_changed );
562 mlt_events_listen( props, this, "property-changed", ( mlt_listener )mlt_service_filter_changed );
575 * \public \memberof mlt_service_s
576 * \param this a service
577 * \param filter the filter to detach
578 * \return true if there was an error
581 int mlt_service_detach( mlt_service this, mlt_filter filter )
583 int error = this == NULL || filter == NULL;
587 mlt_service_base *base = this->local;
588 mlt_properties properties = MLT_SERVICE_PROPERTIES( this );
590 for ( i = 0; i < base->filter_count; i ++ )
591 if ( base->filters[ i ] == filter )
594 if ( i < base->filter_count )
596 base->filters[ i ] = NULL;
597 for ( i ++ ; i < base->filter_count; i ++ )
598 base->filters[ i - 1 ] = base->filters[ i ];
599 base->filter_count --;
600 mlt_events_disconnect( MLT_FILTER_PROPERTIES( filter ), this );
601 mlt_filter_close( filter );
602 mlt_events_fire( properties, "service-changed", NULL );
608 /** Retrieve a filter.
610 * \public \memberof mlt_service_s
611 * \param this a service
612 * \param index which one of potentially multiple filters
613 * \return the filter or null if there was an error
616 mlt_filter mlt_service_filter( mlt_service this, int index )
618 mlt_filter filter = NULL;
621 mlt_service_base *base = this->local;
622 if ( index >= 0 && index < base->filter_count )
623 filter = base->filters[ index ];
628 /** Retrieve the profile.
630 * \public \memberof mlt_service_s
631 * \param this a service
632 * \return the profile
635 mlt_profile mlt_service_profile( mlt_service this )
637 return mlt_properties_get_data( MLT_SERVICE_PROPERTIES( this ), "_profile", NULL );
640 /** Destroy a service.
642 * \public \memberof mlt_service_s
643 * \param this the service to destroy
646 void mlt_service_close( mlt_service this )
648 if ( this != NULL && mlt_properties_dec_ref( MLT_SERVICE_PROPERTIES( this ) ) <= 0 )
650 if ( this->close != NULL )
652 this->close( this->close_object );
656 mlt_service_base *base = this->local;
658 int count = base->filter_count;
659 mlt_events_block( MLT_SERVICE_PROPERTIES( this ), this );
661 mlt_service_detach( this, base->filters[ 0 ] );
662 free( base->filters );
663 for ( i = 0; i < base->count; i ++ )
664 if ( base->in[ i ] != NULL )
665 mlt_service_close( base->in[ i ] );
666 this->parent.close = NULL;
668 pthread_mutex_destroy( &base->mutex );
670 mlt_properties_close( &this->parent );
675 mlt_service_unlock( this );
679 /** Release a service's cache items.
681 * \private \memberof mlt_service_s
682 * \param self a service
685 void mlt_service_cache_purge( mlt_service self )
687 mlt_properties caches = mlt_properties_get_data( mlt_global_properties(), "caches", NULL );
691 int i = mlt_properties_count( caches );
694 mlt_cache_purge( mlt_properties_get_data_at( caches, i, NULL ), self );
695 mlt_properties_set_data( mlt_global_properties(), mlt_properties_get_name( caches, i ), NULL, 0, NULL, NULL );
700 /** Lookup the cache object for a service.
702 * \private \memberof mlt_service_s
703 * \param self a service
704 * \param name a name for the object
708 static mlt_cache get_cache( mlt_service self, const char *name )
710 mlt_cache result = NULL;
711 mlt_properties caches = mlt_properties_get_data( mlt_global_properties(), "caches", NULL );
715 caches = mlt_properties_new();
716 mlt_properties_set_data( mlt_global_properties(), "caches", caches, 0, ( mlt_destructor )mlt_properties_close, NULL );
720 result = mlt_properties_get_data( caches, name, NULL );
723 result = mlt_cache_init();
724 mlt_properties_set_data( caches, name, result, 0, ( mlt_destructor )mlt_cache_close, NULL );
731 /** Put an object into a service's cache.
733 * \public \memberof mlt_service_s
734 * \param self a service
735 * \param name a name for the object that is unique to the service class, but not to the instance
736 * \param data an opaque pointer to the object to put into the cache
737 * \param size the number of bytes pointed to by data
738 * \param destructor a function that releases the data
741 void mlt_service_cache_put( mlt_service self, const char *name, void* data, int size, mlt_destructor destructor )
743 mlt_log( self, MLT_LOG_DEBUG, "%s: name %s object %p data %p\n", __FUNCTION__, name, self, data );
744 mlt_cache cache = get_cache( self, name );
747 mlt_cache_put( cache, self, data, size, destructor );
750 /** Get an object from a service's cache.
752 * \public \memberof mlt_service_s
753 * \param self a service
754 * \param name a name for the object that is unique to the service class, but not to the instance
755 * \return a cache item or NULL if an object is not found
756 * \see mlt_cache_item_data
759 mlt_cache_item mlt_service_cache_get( mlt_service self, const char *name )
761 mlt_log( self, MLT_LOG_DEBUG, "%s: name %s object %p\n", __FUNCTION__, name, self );
762 mlt_cache_item result = NULL;
763 mlt_cache cache = get_cache( self, name );
766 result = mlt_cache_get( cache, self );
771 /** Set the number of items to cache for the named cache.
773 * \public \memberof mlt_service_s
774 * \param self a service
775 * \param name a name for the object that is unique to the service class, but not to the instance
776 * \param size the number of items to cache
779 void mlt_service_cache_set_size( mlt_service self, const char *name, int size )
781 mlt_cache cache = get_cache( self, name );
783 mlt_cache_set_size( cache, size );