From e5fd66367b6f976e3bcb0ada98408afcb40cb2ce Mon Sep 17 00:00:00 2001 From: ddennedy Date: Thu, 4 Dec 2008 02:33:22 +0000 Subject: [PATCH] src/framework/*: improve the doxygen documentation (work in progress). This also includes removal of superfluous white space. git-svn-id: https://mlt.svn.sourceforge.net/svnroot/mlt/trunk/mlt@1248 d19143bc-622f-0410-bfdd-b5b2a6649095 --- src/framework/mlt_consumer.c | 21 +- src/framework/mlt_consumer.h | 19 +- src/framework/mlt_deque.c | 184 +++++++--- src/framework/mlt_deque.h | 10 +- src/framework/mlt_events.c | 27 +- src/framework/mlt_events.h | 18 +- src/framework/mlt_field.c | 17 +- src/framework/mlt_field.h | 10 +- src/framework/mlt_filter.h | 6 +- src/framework/mlt_frame.h | 35 +- src/framework/mlt_multitrack.c | 38 +- src/framework/mlt_multitrack.h | 22 +- src/framework/mlt_parser.c | 10 +- src/framework/mlt_parser.h | 15 +- src/framework/mlt_playlist.c | 46 +-- src/framework/mlt_playlist.h | 22 +- src/framework/mlt_pool.c | 17 +- src/framework/mlt_pool.h | 10 +- src/framework/mlt_producer.c | 283 ++++++++++++--- src/framework/mlt_producer.h | 66 +++- src/framework/mlt_profile.c | 14 +- src/framework/mlt_profile.h | 14 +- src/framework/mlt_properties.c | 623 +++++++++++++++++++++++++-------- src/framework/mlt_properties.h | 31 +- src/framework/mlt_property.c | 229 +++++++++--- src/framework/mlt_property.h | 54 +-- src/framework/mlt_repository.c | 41 ++- src/framework/mlt_repository.h | 14 +- src/framework/mlt_service.c | 199 ++++++++--- src/framework/mlt_service.h | 62 ++-- src/framework/mlt_tokeniser.c | 12 +- src/framework/mlt_tokeniser.h | 15 +- src/framework/mlt_tractor.c | 16 +- src/framework/mlt_tractor.h | 16 +- src/framework/mlt_transition.c | 30 +- src/framework/mlt_transition.h | 20 +- src/framework/mlt_types.h | 117 ++++--- 37 files changed, 1706 insertions(+), 677 deletions(-) diff --git a/src/framework/mlt_consumer.c b/src/framework/mlt_consumer.c index de126e08..8ed90c72 100644 --- a/src/framework/mlt_consumer.c +++ b/src/framework/mlt_consumer.c @@ -1,7 +1,9 @@ -/* - * mlt_consumer.c -- abstraction for all consumer services - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_consumer.c + * \brief abstraction for all consumer 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 @@ -36,9 +38,6 @@ 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 ); -/** Public final methods -*/ - int mlt_consumer_init( mlt_consumer this, void *child, mlt_profile profile ) { int error = 0; @@ -49,7 +48,7 @@ int mlt_consumer_init( mlt_consumer this, void *child, mlt_profile profile ) { // Get the properties from the service mlt_properties properties = MLT_SERVICE_PROPERTIES( &this->parent ); - + // Apply profile to properties if ( profile == NULL ) { @@ -328,7 +327,7 @@ int mlt_consumer_start( mlt_consumer this ) int frame_duration = 1000000 / mlt_properties_get_int( properties, "frame_rate_num" ) * mlt_properties_get_int( properties, "frame_rate_den" ); mlt_properties_set_int( properties, "frame_duration", frame_duration ); - + // Check and run an ante command if ( mlt_properties_get( properties, "ante" ) ) system( mlt_properties_get( properties, "ante" ) ); @@ -658,7 +657,7 @@ static void consumer_read_ahead_start( mlt_consumer this ) // Create the condition pthread_cond_init( &this->cond, NULL ); - // Create the read ahead + // Create the read ahead if ( mlt_properties_get( MLT_CONSUMER_PROPERTIES( this ), "priority" ) ) { struct sched_param priority; @@ -749,7 +748,7 @@ mlt_frame mlt_consumer_rt_frame( mlt_consumer this ) if ( buffer > 1 ) size = prefill > 0 && prefill < buffer ? prefill : buffer; } - + // Get frame from queue pthread_mutex_lock( &this->mutex ); while( this->ahead && mlt_deque_count( this->queue ) < size ) diff --git a/src/framework/mlt_consumer.h b/src/framework/mlt_consumer.h index e33eb1ed..22457041 100644 --- a/src/framework/mlt_consumer.h +++ b/src/framework/mlt_consumer.h @@ -1,7 +1,9 @@ -/* - * mlt_consumer.h -- abstraction for all consumer services - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_consumer.h + * \brief abstraction for all consumer 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 @@ -25,8 +27,10 @@ #include "mlt_events.h" #include -/** The interface definition for all consumers. -*/ +/** \brief Consumer abstract service class + * + * \extends mlt_service_s + */ struct mlt_consumer_s { @@ -57,9 +61,6 @@ struct mlt_consumer_s mlt_event event_listener; }; -/** Public final methods -*/ - #define MLT_CONSUMER_SERVICE( consumer ) ( &( consumer )->parent ) #define MLT_CONSUMER_PROPERTIES( consumer ) MLT_SERVICE_PROPERTIES( MLT_CONSUMER_SERVICE( consumer ) ) diff --git a/src/framework/mlt_deque.c b/src/framework/mlt_deque.c index 1be59298..28dfd7f6 100644 --- a/src/framework/mlt_deque.c +++ b/src/framework/mlt_deque.c @@ -1,7 +1,9 @@ -/* - * mlt_deque.c -- double ended queue - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_deque.c + * \brief double ended queue + * + * 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 @@ -25,6 +27,10 @@ #include #include +/** \brief Deque entry class + * + */ + typedef union { void *addr; @@ -33,8 +39,11 @@ typedef union } deque_entry; -/** Private structure. -*/ +/** \brief Double-Ended Queue (deque) class + * + * The double-ended queue is a very versatile data structure. MLT uses it as + * list, stack, and circular queue. + */ struct mlt_deque_s { @@ -44,7 +53,10 @@ struct mlt_deque_s }; /** Create a deque. -*/ + * + * \public \memberof mlt_deque_s + * \return a new deque + */ mlt_deque mlt_deque_init( ) { @@ -59,7 +71,11 @@ mlt_deque mlt_deque_init( ) } /** Return the number of items in the deque. -*/ + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return the number of items + */ int mlt_deque_count( mlt_deque this ) { @@ -67,7 +83,11 @@ int mlt_deque_count( mlt_deque this ) } /** Allocate space on the deque. -*/ + * + * \private \memberof mlt_deque_s + * \param this a deque + * \return true if there was an error + */ static int mlt_deque_allocate( mlt_deque this ) { @@ -80,7 +100,12 @@ static int mlt_deque_allocate( mlt_deque this ) } /** Push an item to the end. -*/ + * + * \public \memberof mlt_deque_s + * \param this a deque + * \param item an opaque pointer + * \return true if there was an error + */ int mlt_deque_push_back( mlt_deque this, void *item ) { @@ -93,7 +118,11 @@ int mlt_deque_push_back( mlt_deque this, void *item ) } /** Pop an item. -*/ + * + * \public \memberof mlt_deque_s + * \param this a pointer + * \return an opaque pointer + */ void *mlt_deque_pop_back( mlt_deque this ) { @@ -101,7 +130,12 @@ void *mlt_deque_pop_back( mlt_deque this ) } /** Queue an item at the start. -*/ + * + * \public \memberof mlt_deque_s + * \param this a deque + * \param item an opaque pointer + * \return true if there was an error + */ int mlt_deque_push_front( mlt_deque this, void *item ) { @@ -117,7 +151,11 @@ int mlt_deque_push_front( mlt_deque this, void *item ) } /** Remove an item from the start. -*/ + * + * \public \memberof mlt_deque_s + * \param this a pointer + * \return an opaque pointer + */ void *mlt_deque_pop_front( mlt_deque this ) { @@ -133,7 +171,11 @@ void *mlt_deque_pop_front( mlt_deque this ) } /** Inquire on item at back of deque but don't remove. -*/ + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return an opaque pointer + */ void *mlt_deque_peek_back( mlt_deque this ) { @@ -141,15 +183,24 @@ void *mlt_deque_peek_back( mlt_deque this ) } /** Inquire on item at front of deque but don't remove. -*/ + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return an opaque pointer + */ void *mlt_deque_peek_front( mlt_deque this ) { return this->count > 0 ? this->list[ 0 ].addr : NULL; } -/** Push an item to the end. -*/ +/** Push an integer to the end. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \param item an integer + * \return true if there was an error + */ int mlt_deque_push_back_int( mlt_deque this, int item ) { @@ -161,16 +212,25 @@ int mlt_deque_push_back_int( mlt_deque this, int item ) return error; } -/** Pop an item. -*/ +/** Pop an integer. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return an integer + */ int mlt_deque_pop_back_int( mlt_deque this ) { return this->count > 0 ? this->list[ -- this->count ].value : 0; } -/** Queue an item at the start. -*/ +/** Queue an integer at the start. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \param item an integer + * \return true if there was an error + */ int mlt_deque_push_front_int( mlt_deque this, int item ) { @@ -185,8 +245,12 @@ int mlt_deque_push_front_int( mlt_deque this, int item ) return error; } -/** Remove an item from the start. -*/ +/** Remove an integer from the start. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return an integer + */ int mlt_deque_pop_front_int( mlt_deque this ) { @@ -201,24 +265,37 @@ int mlt_deque_pop_front_int( mlt_deque this ) return item; } -/** Inquire on item at back of deque but don't remove. -*/ +/** Inquire on an integer at back of deque but don't remove. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return an integer + */ int mlt_deque_peek_back_int( mlt_deque this ) { return this->count > 0 ? this->list[ this->count - 1 ].value : 0; } -/** Inquire on item at front of deque but don't remove. -*/ +/** Inquire on an integer at front of deque but don't remove. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return an integer + */ int mlt_deque_peek_front_int( mlt_deque this ) { return this->count > 0 ? this->list[ 0 ].value : 0; } -/** Push an item to the end. -*/ +/** Push a double float to the end. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \param item a double float + * \return true if there was an error + */ int mlt_deque_push_back_double( mlt_deque this, double item ) { @@ -230,16 +307,25 @@ int mlt_deque_push_back_double( mlt_deque this, double item ) return error; } -/** Pop an item. -*/ +/** Pop a double float. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return a double float + */ double mlt_deque_pop_back_double( mlt_deque this ) { return this->count > 0 ? this->list[ -- this->count ].floating : 0; } -/** Queue an item at the start. -*/ +/** Queue a double float at the start. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \param item a double float + * \return true if there was an error + */ int mlt_deque_push_front_double( mlt_deque this, double item ) { @@ -254,8 +340,12 @@ int mlt_deque_push_front_double( mlt_deque this, double item ) return error; } -/** Remove an item from the start. -*/ +/** Remove a double float from the start. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return a double float + */ double mlt_deque_pop_front_double( mlt_deque this ) { @@ -270,28 +360,38 @@ double mlt_deque_pop_front_double( mlt_deque this ) return item; } -/** Inquire on item at back of deque but don't remove. -*/ +/** Inquire on a double float at back of deque but don't remove. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return a double float + */ double mlt_deque_peek_back_double( mlt_deque this ) { return this->count > 0 ? this->list[ this->count - 1 ].floating : 0; } -/** Inquire on item at front of deque but don't remove. -*/ +/** Inquire on a double float at front of deque but don't remove. + * + * \public \memberof mlt_deque_s + * \param this a deque + * \return a double float + */ double mlt_deque_peek_front_double( mlt_deque this ) { return this->count > 0 ? this->list[ 0 ].floating : 0; } -/** Close the queue. -*/ +/** Destroy the queue. + * + * \public \memberof mlt_deque_s + * \param this a deque + */ void mlt_deque_close( mlt_deque this ) { free( this->list ); free( this ); } - diff --git a/src/framework/mlt_deque.h b/src/framework/mlt_deque.h index 9cd66517..00ed30ee 100644 --- a/src/framework/mlt_deque.h +++ b/src/framework/mlt_deque.h @@ -1,7 +1,9 @@ -/* - * mlt_deque.h -- double ended queue - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_deque.h + * \brief double ended queue + * + * 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 diff --git a/src/framework/mlt_events.c b/src/framework/mlt_events.c index 844721d4..b0efd6b7 100644 --- a/src/framework/mlt_events.c +++ b/src/framework/mlt_events.c @@ -1,7 +1,9 @@ -/* - * mlt_events.h -- event handling - * Copyright (C) 2004-2005 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_events.c + * \brief event handling + * + * Copyright (C) 2004-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 @@ -26,16 +28,19 @@ #include "mlt_properties.h" #include "mlt_events.h" -/** Memory leak checks. -*/ +/** Memory leak checks. */ -//#define _MLT_EVENT_CHECKS_ +#undef _MLT_EVENT_CHECKS_ #ifdef _MLT_EVENT_CHECKS_ static int events_created = 0; static int events_destroyed = 0; #endif +/** \brief Events class + * + */ + struct mlt_events_struct { mlt_properties owner; @@ -44,6 +49,10 @@ struct mlt_events_struct typedef struct mlt_events_struct *mlt_events; +/** \brief Event class + * + */ + struct mlt_event_struct { mlt_events owner; @@ -100,7 +109,7 @@ void mlt_event_close( mlt_event this ) } } -/** Forward declaration to private functions. +/* Forward declaration to private functions. */ static mlt_events mlt_events_fetch( mlt_properties ); @@ -319,6 +328,8 @@ void mlt_events_disconnect( mlt_properties this, void *service ) } } +/** \brief private to mlt_events_struct, used by mlt_events_wait_for() */ + typedef struct { int done; diff --git a/src/framework/mlt_events.h b/src/framework/mlt_events.h index 11b5f11f..43a296d0 100644 --- a/src/framework/mlt_events.h +++ b/src/framework/mlt_events.h @@ -1,7 +1,9 @@ -/* - * mlt_events.h -- event handling - * Copyright (C) 2004-2005 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_events.h + * \brief event handling + * + * Copyright (C) 2004-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 @@ -27,7 +29,15 @@ typedef void ( *mlt_transmitter )( void *, ... ); typedef void ( *mlt_listener )( void *, ... ); #else +/** callback function to send an event message + * + */ typedef void ( *mlt_transmitter )( ); +/** event handler when receiving an event message + * \param the properties object on which the event was registered + * \param an opaque pointer to a service or really an object + * \param variable args supplied by the transmitter + */ typedef void ( *mlt_listener )( ); #endif diff --git a/src/framework/mlt_field.c b/src/framework/mlt_field.c index 924eee94..a86afa92 100644 --- a/src/framework/mlt_field.c +++ b/src/framework/mlt_field.c @@ -1,7 +1,9 @@ -/* - * mlt_field.c -- A field for planting multiple transitions and filters - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_field.c + * \brief a field for planting multiple transitions and filters + * + * 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 @@ -28,8 +30,9 @@ #include #include -/** Private structures. -*/ +/** \brief Field class + * + */ struct mlt_field_s { @@ -44,7 +47,7 @@ struct mlt_field_s }; /** Constructor. - + We construct a multitrack and a tractor here. */ diff --git a/src/framework/mlt_field.h b/src/framework/mlt_field.h index d5b0c205..e32062f1 100644 --- a/src/framework/mlt_field.h +++ b/src/framework/mlt_field.h @@ -1,7 +1,9 @@ -/* - * mlt_field.h -- A field for planting multiple transitions and services - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_field.h + * \brief a field for planting multiple transitions and 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 diff --git a/src/framework/mlt_filter.h b/src/framework/mlt_filter.h index 423dd62b..c67c9abc 100644 --- a/src/framework/mlt_filter.h +++ b/src/framework/mlt_filter.h @@ -23,8 +23,10 @@ #include "mlt_service.h" -/** The interface definition for all filters. -*/ +/** \brief Filter abstract service class + * + * \extends mlt_service_s + */ struct mlt_filter_s { diff --git a/src/framework/mlt_frame.h b/src/framework/mlt_frame.h index 941d8ff4..6850bd96 100644 --- a/src/framework/mlt_frame.h +++ b/src/framework/mlt_frame.h @@ -1,7 +1,9 @@ -/* - * mlt_frame.h -- interface for all frame classes - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_frame.h + * \brief interface for all frame classes + * + * 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 @@ -25,9 +27,27 @@ #include "mlt_deque.h" #include "mlt_service.h" +/** callback function to get video data + * + */ + typedef int ( *mlt_get_image )( mlt_frame self, uint8_t **buffer, mlt_image_format *format, int *width, int *height, int writable ); + +/** callback function to get audio data + * + */ + typedef int ( *mlt_get_audio )( mlt_frame self, int16_t **buffer, mlt_audio_format *format, int *frequency, int *channels, int *samples ); +/** \brief Frame class + * + * \properties \em test_image set if the frame holds a "test card" image + * \properties \em test_audio set if the frame holds "test card" audio + * \properties \em _producer holds a reference to the frame's end producer + * \properties \em _speed + * \properties \em meta.* holds metadata + */ + struct mlt_frame_s { /* We're extending properties here */ @@ -35,7 +55,7 @@ struct mlt_frame_s /* Virtual methods */ uint8_t * ( *get_alpha_mask )( mlt_frame self ); - + /* Private properties */ mlt_deque stack_image; mlt_deque stack_audio; @@ -90,13 +110,13 @@ extern int mlt_frame_combine_audio( mlt_frame self, mlt_frame that, int16_t **bu extern int mlt_sample_calculator( float fps, int frequency, int64_t position ); extern int64_t mlt_sample_calculator_to_now( float fps, int frequency, int64_t position ); -/* this macro scales rgb into the yuv gamut, y is scaled by 219/255 and uv by 224/255 */ +/** This macro scales rgb into the yuv gamut - y is scaled by 219/255 and uv by 224/255. */ #define RGB2YUV(r, g, b, y, u, v)\ y = ((263*r + 516*g + 100*b) >> 10) + 16;\ u = ((-152*r - 298*g + 450*b) >> 10) + 128;\ v = ((450*r - 377*g - 73*b) >> 10) + 128; -/* this macro assumes the user has already scaled their rgb down into the broadcast limits */ +/** This macro assumes the user has already scaled their rgb down into the broadcast limits. **/ #define RGB2YUV_UNSCALED(r, g, b, y, u, v)\ y = (299*r + 587*g + 114*b) >> 10;\ u = ((-169*r - 331*g + 500*b) >> 10) + 128;\ @@ -108,6 +128,7 @@ extern int64_t mlt_sample_calculator_to_now( float fps, int frequency, int64_t p u = u > 240 ? 240 : u;\ v = v > 240 ? 240 : v +/** This macro converts a YUV value to the RGB color space. */ #define YUV2RGB( y, u, v, r, g, b ) \ r = ((1192 * ( y - 16 ) + 1634 * ( v - 128 ) ) >> 10 ); \ g = ((1192 * ( y - 16 ) - 832 * ( v - 128 ) - 400 * ( u - 128 ) ) >> 10 ); \ diff --git a/src/framework/mlt_multitrack.c b/src/framework/mlt_multitrack.c index bf9c0738..432b90c9 100644 --- a/src/framework/mlt_multitrack.c +++ b/src/framework/mlt_multitrack.c @@ -1,7 +1,9 @@ -/* - * mlt_multitrack.c -- multitrack service class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_multitrack.c + * \brief multitrack service class + * + * 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 @@ -59,7 +61,7 @@ mlt_multitrack mlt_multitrack_init( ) this = NULL; } } - + return this; } @@ -113,7 +115,7 @@ void mlt_multitrack_refresh( mlt_multitrack this ) // If we have more than 1 track, we must be in continue mode if ( this->count > 1 ) mlt_properties_set( MLT_PRODUCER_PROPERTIES( producer ), "eof", "continue" ); - + // Determine the longest length //if ( !mlt_properties_get_int( MLT_PRODUCER_PROPERTIES( producer ), "hide" ) ) length = mlt_producer_get_playtime( producer ) > length ? mlt_producer_get_playtime( producer ) : length; @@ -170,15 +172,15 @@ int mlt_multitrack_connect( mlt_multitrack this, mlt_producer producer, int trac // Assign the track in our list here this->list[ track ]->producer = producer; - this->list[ track ]->event = mlt_events_listen( MLT_PRODUCER_PROPERTIES( producer ), this, + this->list[ track ]->event = mlt_events_listen( MLT_PRODUCER_PROPERTIES( producer ), this, "producer-changed", ( mlt_listener )mlt_multitrack_listener ); mlt_properties_inc_ref( MLT_PRODUCER_PROPERTIES( producer ) ); mlt_event_inc_ref( this->list[ track ]->event ); - + // Increment the track count if need be if ( track >= this->count ) this->count = track + 1; - + // Refresh our stats mlt_multitrack_refresh( this ); } @@ -191,7 +193,7 @@ int mlt_multitrack_connect( mlt_multitrack this, mlt_producer producer, int trac int mlt_multitrack_count( mlt_multitrack this ) { - return this->count; + return this->count; } /** Get an individual track as a producer. @@ -200,7 +202,7 @@ int mlt_multitrack_count( mlt_multitrack this ) mlt_producer mlt_multitrack_track( mlt_multitrack this, int track ) { mlt_producer producer = NULL; - + if ( this->list != NULL && track < this->count ) producer = this->list[ track ]->producer; @@ -225,9 +227,9 @@ static int add_unique( mlt_position *array, int size, mlt_position position ) /** Determine the clip point. - Special case here: a 'producer' has no concept of multiple clips - only the - playlist and multitrack producers have clip functionality. Further to that a - multitrack determines clip information from any connected tracks that happen + Special case here: a 'producer' has no concept of multiple clips - only the + playlist and multitrack producers have clip functionality. Further to that a + multitrack determines clip information from any connected tracks that happen to be playlists. Additionally, it must locate clips in the correct order, for example, consider @@ -295,7 +297,7 @@ mlt_position mlt_multitrack_clip( mlt_multitrack this, mlt_whence whence, int in case mlt_whence_relative_current: position = mlt_producer_position( MLT_MULTITRACK_PRODUCER( this ) ); - for ( i = 0; i < count - 2; i ++ ) + for ( i = 0; i < count - 2; i ++ ) if ( position >= map[ i ] && position < map[ i + 1 ] ) break; index += i; @@ -330,10 +332,10 @@ mlt_position mlt_multitrack_clip( mlt_multitrack this, mlt_whence whence, int in Producer2 - multitrack - { filters/transitions } - tractor - consumer Producer3 / - The get_frame of a tractor pulls frames from it's connected service on all tracks and - will terminate as soon as it receives a test card with a last_track property. The + The get_frame of a tractor pulls frames from it's connected service on all tracks and + will terminate as soon as it receives a test card with a last_track property. The important case here is that the mulitrack does not move to the next frame until all - tracks have been pulled. + tracks have been pulled. Reasoning: In order to seek on a network such as above, the multitrack needs to ensure that all producers are positioned on the same frame. It uses the 'last track' logic diff --git a/src/framework/mlt_multitrack.h b/src/framework/mlt_multitrack.h index 6323f56a..5d272b33 100644 --- a/src/framework/mlt_multitrack.h +++ b/src/framework/mlt_multitrack.h @@ -1,7 +1,9 @@ -/* - * mlt_multitrack.h -- multitrack service class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_multitrack.h + * \brief multitrack service class + * + * 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 @@ -23,8 +25,8 @@ #include "mlt_producer.h" -/** Private definition. -*/ +/** \brief Track class + */ struct mlt_track_s { @@ -34,6 +36,11 @@ struct mlt_track_s typedef struct mlt_track_s *mlt_track; +/** \brief Multitrack class + * + * \extends mlt_producer_s + */ + struct mlt_multitrack_s { /* We're extending producer here */ @@ -43,9 +50,6 @@ struct mlt_multitrack_s int count; }; -/** Public final methods -*/ - #define MLT_MULTITRACK_PRODUCER( multitrack ) ( &( multitrack )->parent ) #define MLT_MULTITRACK_SERVICE( multitrack ) MLT_PRODUCER_SERVICE( MLT_MULTITRACK_PRODUCER( multitrack ) ) #define MLT_MULTITRACK_PROPERTIES( multitrack ) MLT_SERVICE_PROPERTIES( MLT_MULTITRACK_SERVICE( multitrack ) ) diff --git a/src/framework/mlt_parser.c b/src/framework/mlt_parser.c index 2f76e373..5473aff1 100644 --- a/src/framework/mlt_parser.c +++ b/src/framework/mlt_parser.c @@ -1,7 +1,9 @@ -/* - * mlt_parser.c -- service parsing functionality - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_parser.c + * \brief service parsing functionality + * + * 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 diff --git a/src/framework/mlt_parser.h b/src/framework/mlt_parser.h index 48df1b8f..08f6ffbf 100644 --- a/src/framework/mlt_parser.h +++ b/src/framework/mlt_parser.h @@ -1,7 +1,9 @@ -/* - * mlt_parser.h -- service parsing functionality - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_parser.h + * \brief service parsing functionality + * + * 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 @@ -23,6 +25,11 @@ #include "mlt_types.h" +/** \brief Parser class + * + * \extends mlt_properties_s + */ + struct mlt_parser_s { struct mlt_properties_s parent; diff --git a/src/framework/mlt_playlist.c b/src/framework/mlt_playlist.c index 27c44435..8cf43389 100644 --- a/src/framework/mlt_playlist.c +++ b/src/framework/mlt_playlist.c @@ -1,7 +1,9 @@ -/* - * mlt_playlist.c -- playlist service class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_playlist.c + * \brief playlist service class + * + * 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 @@ -29,7 +31,7 @@ #include #include -/** Virtual playlist entry. +/** \brief virtual playlist entry */ struct playlist_entry_s @@ -90,7 +92,7 @@ mlt_playlist mlt_playlist_init( ) this->size = 10; this->list = malloc( this->size * sizeof( playlist_entry * ) ); } - + return this; } @@ -135,7 +137,7 @@ static int mlt_playlist_virtual_refresh( mlt_playlist this ) if ( producer ) { int current_length = mlt_producer_get_out( producer ) - mlt_producer_get_in( producer ) + 1; - + // Check if the length of the producer has changed if ( this->list[ i ]->frame_in != mlt_producer_get_in( producer ) || this->list[ i ]->frame_out != mlt_producer_get_out( producer ) ) @@ -147,13 +149,13 @@ static int mlt_playlist_virtual_refresh( mlt_playlist this ) this->list[ i ]->frame_out = -1; this->list[ i ]->frame_count = 0; } - else + else { this->list[ i ]->frame_in = mlt_producer_get_in( producer ); this->list[ i ]->frame_out = mlt_producer_get_out( producer ); this->list[ i ]->frame_count = current_length; } - + // Update the producer_length this->list[ i ]->producer_length = current_length; } @@ -593,9 +595,9 @@ int mlt_playlist_append_io( mlt_playlist this, mlt_producer producer, mlt_positi int mlt_playlist_blank( mlt_playlist this, mlt_position length ) { // Append to the virtual list - if (length >= 0) + if (length >= 0) return mlt_playlist_virtual_append( this, &this->blank, 0, length ); - else + else return 1; } @@ -635,11 +637,11 @@ int mlt_playlist_remove( mlt_playlist this, int where ) // Loop variable int i = 0; - // Get the clip info + // Get the clip info mlt_playlist_get_clip_info( this, &where_info, where ); // Make sure the clip to be removed is valid and correct if necessary - if ( where < 0 ) + if ( where < 0 ) where = 0; if ( where >= this->count ) where = this->count - 1; @@ -662,7 +664,7 @@ int mlt_playlist_remove( mlt_playlist this, int where ) mlt_properties mix = mlt_properties_get_data( properties, "mix_out", NULL ); mlt_properties_set_data( mix, "mix_in", NULL, 0, NULL, NULL ); } - + if ( mlt_properties_ref_count( MLT_PRODUCER_PROPERTIES( entry->producer ) ) == 1 ) mlt_producer_clear( entry->producer ); } @@ -697,16 +699,16 @@ int mlt_playlist_move( mlt_playlist this, int src, int dest ) int i; /* We need to ensure that the requested indexes are valid and correct it as necessary */ - if ( src < 0 ) + if ( src < 0 ) src = 0; if ( src >= this->count ) src = this->count - 1; - if ( dest < 0 ) + if ( dest < 0 ) dest = 0; if ( dest >= this->count ) dest = this->count - 1; - + if ( src != dest && this->count > 1 ) { int current = mlt_playlist_current_clip( this ); @@ -1072,7 +1074,7 @@ int mlt_playlist_clip_is_mix( mlt_playlist this, int clip ) static int mlt_playlist_unmix( mlt_playlist this, int clip ) { - int error = ( clip < 0 || clip >= this->count ); + int error = ( clip < 0 || clip >= this->count ); // Ensure that the clip request is actually a mix if ( error == 0 ) @@ -1124,7 +1126,7 @@ 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 ) { - int error = ( clip < 0 || clip >= this->count ); + int error = ( clip < 0 || clip >= this->count ); // Ensure that the clip request is actually a mix if ( error == 0 ) @@ -1324,10 +1326,10 @@ int mlt_playlist_insert_at( mlt_playlist this, mlt_position position, mlt_produc mlt_playlist_insert( this, producer, clip, -1, -1 ); ret = clip; } - else + else { if ( mode == 1 ) { - if ( position == info.start ) + if ( position == info.start ) mlt_playlist_remove( this, clip ); else mlt_playlist_blank( this, position - mlt_properties_get_int( properties, "length" ) - 1 ); @@ -1411,7 +1413,7 @@ int mlt_playlist_remove_region( mlt_playlist this, mlt_position position, int le length -= mlt_playlist_clip_length( this, index ); mlt_playlist_remove( this, index ); } - + mlt_playlist_consolidate_blanks( this, 0 ); mlt_events_unblock( properties, this ); mlt_playlist_virtual_refresh( this ); diff --git a/src/framework/mlt_playlist.h b/src/framework/mlt_playlist.h index 2fd9673b..115cf1df 100644 --- a/src/framework/mlt_playlist.h +++ b/src/framework/mlt_playlist.h @@ -1,7 +1,9 @@ -/* - * mlt_playlist.h -- playlist service class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_playlist.h + * \brief playlist service class + * + * 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 @@ -23,8 +25,8 @@ #include "mlt_producer.h" -/** Structure for returning clip information. -*/ +/** \brief structure for returning clip information + */ typedef struct { @@ -47,6 +49,11 @@ mlt_playlist_clip_info; typedef struct playlist_entry_s playlist_entry; +/** \brief Playlist class + * + * \extends mlt_producer_s + */ + struct mlt_playlist_s { struct mlt_producer_s parent; @@ -57,9 +64,6 @@ struct mlt_playlist_s playlist_entry **list; }; -/** Public final methods -*/ - #define MLT_PLAYLIST_PRODUCER( playlist ) ( &( playlist )->parent ) #define MLT_PLAYLIST_SERVICE( playlist ) MLT_PRODUCER_SERVICE( MLT_PLAYLIST_PRODUCER( playlist ) ) #define MLT_PLAYLIST_PROPERTIES( playlist ) MLT_SERVICE_PROPERTIES( MLT_PLAYLIST_SERVICE( playlist ) ) diff --git a/src/framework/mlt_pool.c b/src/framework/mlt_pool.c index 7c8657c4..d58d02ca 100644 --- a/src/framework/mlt_pool.c +++ b/src/framework/mlt_pool.c @@ -1,7 +1,9 @@ -/* - * mlt_pool.c -- memory pooling functionality - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_pool.c + * \brief memory pooling functionality + * + * 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 @@ -35,8 +37,8 @@ static mlt_properties pools = NULL; -/** Private pooling structure. -*/ +/** \brief Pool (memory) class + */ typedef struct mlt_pool_s { @@ -47,6 +49,9 @@ typedef struct mlt_pool_s } *mlt_pool; +/** \brief private to mlt_pool_s, for tracking items to release + */ + typedef struct mlt_release_s { mlt_pool pool; diff --git a/src/framework/mlt_pool.h b/src/framework/mlt_pool.h index e8e34ee0..eadfe200 100644 --- a/src/framework/mlt_pool.h +++ b/src/framework/mlt_pool.h @@ -1,7 +1,9 @@ -/* - * mlt_pool.h -- memory pooling functionality - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_pool.h + * \brief memory pooling functionality + * + * 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 diff --git a/src/framework/mlt_producer.c b/src/framework/mlt_producer.c index df0677ce..6f00734f 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 @@ -29,22 +31,27 @@ #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 + * \todo Document the special properties and events. + */ int mlt_producer_init( mlt_producer this, void *child ) { @@ -60,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; @@ -69,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; @@ -79,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 ); @@ -105,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 ) { @@ -114,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( ) { @@ -132,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 ) { @@ -140,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 ) { @@ -149,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 ) { @@ -158,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 ) { @@ -169,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 ) { @@ -197,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 ) { @@ -205,7 +262,11 @@ 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 + */ mlt_properties mlt_producer_properties( mlt_producer this ) { @@ -213,7 +274,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 ) { @@ -252,7 +319,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 ) { @@ -260,7 +331,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 ) { @@ -268,7 +343,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 ) { @@ -276,7 +356,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 ) { @@ -284,7 +368,13 @@ 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 ) { @@ -293,7 +383,19 @@ double mlt_producer_get_fps( mlt_producer this ) } /** 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 +432,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 +453,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 +465,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,7 +477,11 @@ 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 ) { @@ -371,7 +489,13 @@ mlt_position mlt_producer_get_playtime( mlt_producer this ) } /** Get the total 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 +503,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 +518,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 ) { @@ -521,7 +664,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 +677,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 +690,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 +703,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 ) { @@ -572,7 +735,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 ) { @@ -618,10 +786,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; @@ -631,6 +798,8 @@ typedef struct } track_info; +/** \brief private to mlt_producer_s, used by mlt_producer_optimise() */ + typedef struct { mlt_producer cut; @@ -738,6 +907,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; @@ -809,7 +986,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 ) { diff --git a/src/framework/mlt_producer.h b/src/framework/mlt_producer.h index 48479ecb..6f98ad74 100644 --- a/src/framework/mlt_producer.h +++ b/src/framework/mlt_producer.h @@ -1,7 +1,9 @@ -/* - * mlt_producer.h -- abstraction for all producer services - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_producer.h + * \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 @@ -24,26 +26,62 @@ #include "mlt_service.h" #include "mlt_filter.h" -/** The interface definition for all producers. -*/ +/** \brief Producer abstract service class + * + * A producer is a service that generates audio, video, and metadata. + * Some day it may also generate text (subtitles). This is not to say + * a producer "synthesizes," rather that is an origin of data within the + * service network - that could be through synthesis or reading a stream. + * + * \extends mlt_service + * \event \em producer-changed + * \properties \em mlt_type the name of the service subclass, e.g. mlt_producer + * \properties \em mlt_service the name of a producer subclass + * \properties \em _position the current position of the play head, relative to the in point + * \properties \em _frame the current position of the play head, relative to the beginning of the resource + * \properties \em _speed the current speed factor, where 1.0 is normal + * \properties \em aspect_ratio sample aspect ratio + * \properties \em length the duration of the cut in frames + * \properties \em eof the end-of-file behavior, one of: pause, continue, loop + * \properties \em resource the file name, stream address, or the class name in angle brackets + * \properties \em _cut set if this producer is a "cut" producer + * \properties \em mlt_mix stores the data for a "mix" producer + * \properties \em _cut_parent holds a reference to the cut's parent producer + * \properties \em ignore_points Set this to temporarily disable the in and out points. + * \properties \em use_clone holds a reference to a clone's producer, as created by mlt_producer_optimise + * \properties \em _clone is the index of the clone in the list of clones stored on the clone's producer + * \properties \em _clones is the number of clones of the producer, as created by mlt_producer_optimise + * \properties \em _clone.{N} holds a reference to the N'th clone of the producer, as created by mlt_producer_optimise + * \properties \em meta.* holds metadata - there is a loose taxonomy to be defined + * \properties \em set.* holds properties to set on a frame produced + * \todo define the media metadata taxonomy + */ struct mlt_producer_s { - /* We're implementing service here */ + /** A producer is a service. */ struct mlt_service_s parent; - /* Public virtual methods */ + /** Get a frame of data (virtual function). + * + * \param mlt_producer a producer + * \param mlt_frame_ptr a frame pointer by reference + * \param int an index + * \return true if there was an error + */ int ( *get_frame )( mlt_producer, mlt_frame_ptr, int ); + + /** the destructor virtual function */ mlt_destructor close; - void *close_object; + void *close_object; /**< the object supplied to the close virtual function */ - /* Private data */ - void *local; - void *child; + void *local; /**< \private instance object */ + void *child; /**< \private the object of a subclass */ }; -/** Public final methods -*/ +/* + * Public final methods + */ #define MLT_PRODUCER_SERVICE( producer ) ( &( producer )->parent ) #define MLT_PRODUCER_PROPERTIES( producer ) MLT_SERVICE_PROPERTIES( MLT_PRODUCER_SERVICE( producer ) ) diff --git a/src/framework/mlt_profile.c b/src/framework/mlt_profile.c index ea5f098e..f90ca3d6 100644 --- a/src/framework/mlt_profile.c +++ b/src/framework/mlt_profile.c @@ -1,7 +1,9 @@ -/* - * mlt_profile.c -- video output definition - * Copyright (C) 2007 Ushodaya Enterprises Limited - * Author: Dan Dennedy +/** + * \file mlt_profile.c + * \brief video output definition + * + * Copyright (C) 2007-2008 Ushodaya Enterprises Limited + * \author Dan Dennedy * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -37,7 +39,7 @@ static mlt_profile mlt_profile_select( const char *name ) const char *prefix = getenv( "MLT_PROFILES_PATH" ); mlt_properties properties = mlt_properties_load( name ); mlt_profile profile = NULL; - + // Try to load from file specification if ( properties && mlt_properties_get_int( properties, "width" ) ) { @@ -61,7 +63,7 @@ static mlt_profile mlt_profile_select( const char *name ) if ( filename[ strlen( filename ) - 1 ] != '/' ) filename[ strlen( filename ) ] = '/'; } - + // Finish loading strcat( filename, name ); profile = mlt_profile_load_file( filename ); diff --git a/src/framework/mlt_profile.h b/src/framework/mlt_profile.h index 6b0c42d9..18144931 100644 --- a/src/framework/mlt_profile.h +++ b/src/framework/mlt_profile.h @@ -1,7 +1,9 @@ -/* - * mlt_profile.h -- video output definition - * Copyright (C) 2007 Ushodaya Enterprises Limited - * Author: Dan Dennedy +/** + * \file mlt_profile.h + * \brief video output definition + * + * Copyright (C) 2007-2008 Ushodaya Enterprises Limited + * \author Dan Dennedy * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -23,6 +25,10 @@ #include "mlt_types.h" +/** \brief Profile class + * + */ + struct mlt_profile_s { char* description; diff --git a/src/framework/mlt_properties.c b/src/framework/mlt_properties.c index 7e55da91..9714a2fc 100644 --- a/src/framework/mlt_properties.c +++ b/src/framework/mlt_properties.c @@ -1,8 +1,10 @@ -/* - * mlt_properties.c -- base properties class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates - * Contributor: Dan Dennedy +/** + * \file mlt_properties.c + * \brief Properties class definition + * + * Copyright (C) 2003-2008 Ushodaya Enterprises Limited + * \author Charles Yates + * \author Dan Dennedy * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -32,10 +34,8 @@ #include #include -/* ---------------- // Private Implementation // ---------------- */ -/** Private implementation of the property list. -*/ +/** \brief private implementation of the property list */ typedef struct { @@ -50,18 +50,22 @@ typedef struct } property_list; -/** Memory leak checks. -*/ +/* Memory leak checks */ //#define _MLT_PROPERTY_CHECKS_ 2 - #ifdef _MLT_PROPERTY_CHECKS_ static int properties_created = 0; static int properties_destroyed = 0; #endif -/** Basic implementation. -*/ +/** Initialize a properties object that was already allocated. + * + * This does allocate its ::property_list, and it adds a reference count. + * \public \memberof mlt_properties_s + * \param this the properties structure to initialize + * \param child an opaque pointer to a subclass object + * \return true if failed + */ int mlt_properties_init( mlt_properties this, void *child ) { @@ -90,8 +94,13 @@ int mlt_properties_init( mlt_properties this, void *child ) return this != NULL && this->local == NULL; } -/** Constructor for stand alone object. -*/ +/** Create a properties object. + * + * This allocates the properties structure and calls mlt_properties_init() on it. + * Free the properties object with mlt_properties_close(). + * \public \memberof mlt_properties_s + * \return a new properties object + */ mlt_properties mlt_properties_new( ) { @@ -105,8 +114,14 @@ mlt_properties mlt_properties_new( ) return this; } -/** Load properties from a .properties file (DEPRECATED). -*/ +/** Create a properties object by reading a .properties text file. + * + * Free the properties object with mlt_properties_close(). + * \deprecated Please start using mlt_properties_parse_yaml(). + * \public \memberof mlt_properties_s + * \param filename a string contain the absolute file name + * \return a new properties object + */ mlt_properties mlt_properties_load( const char *filename ) { @@ -158,6 +173,13 @@ mlt_properties mlt_properties_load( const char *filename ) return this; } +/** Generate a hash key. + * + * \private \memberof mlt_properties_s + * \param name a string + * \return an integer + */ + static inline int generate_hash( const char *name ) { int hash = 0; @@ -167,15 +189,20 @@ static inline int generate_hash( const char *name ) return hash; } -/** Special case - when a container (such as fezzik) is protecting another - producer, we need to ensure that properties are passed through to the - real producer. -*/ +/** Copy a serializable property to properties list that is mirroring this one. + * + * Special case - when a container (such as fezzik) is protecting another + * producer, we need to ensure that properties are passed through to the + * real producer. + * \private \memberof mlt_properties_s + * \param this a properties list + * \param name the name of the property to copy + */ static inline void mlt_properties_do_mirror( mlt_properties this, const char *name ) { property_list *list = this->local; - if ( list->mirror != NULL ) + if ( list->mirror != NULL ) { char *value = mlt_properties_get( this, name ); if ( value != NULL ) @@ -183,8 +210,12 @@ static inline void mlt_properties_do_mirror( mlt_properties this, const char *na } } -/** Maintain ref count to allow multiple uses of an mlt object. -*/ +/** Increment the reference count. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \return the new reference count + */ int mlt_properties_inc_ref( mlt_properties this ) { @@ -199,8 +230,12 @@ int mlt_properties_inc_ref( mlt_properties this ) return result; } -/** Maintain ref count to allow multiple uses of an mlt object. -*/ +/** Decrement the reference count. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \return the new reference count + */ int mlt_properties_dec_ref( mlt_properties this ) { @@ -215,8 +250,12 @@ int mlt_properties_dec_ref( mlt_properties this ) return result; } -/** Return the ref count of this object. -*/ +/** Get the reference count. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \return the current reference count + */ int mlt_properties_ref_count( mlt_properties this ) { @@ -228,8 +267,14 @@ int mlt_properties_ref_count( mlt_properties this ) return 0; } -/** Mirror properties set on 'this' to 'that'. -*/ +/** Set a properties list to be a mirror copy of another. + * + * Note that this does not copy all existing properties. Rather, you must + * call this before setting the properties that you wish to copy. + * \public \memberof mlt_properties_s + * \param that the properties which will receive copies of the properties as they are set. + * \param this the properties to mirror + */ void mlt_properties_mirror( mlt_properties this, mlt_properties that ) { @@ -237,8 +282,13 @@ void mlt_properties_mirror( mlt_properties this, mlt_properties that ) list->mirror = that; } -/** Inherit all serialisable properties from that into this. -*/ +/** Copy all serializable properties to another properties list. + * + * \public \memberof mlt_properties_s + * \param this The properties to copy from + * \param that The properties to copy to + * \return false + */ int mlt_properties_inherit( mlt_properties this, mlt_properties that ) { @@ -256,8 +306,14 @@ int mlt_properties_inherit( mlt_properties this, mlt_properties that ) return 0; } -/** Pass all properties from 'that' that match the prefix to 'this' (excluding the prefix). -*/ +/** Pass all serializable properties that match a prefix to another properties object + * + * \public \memberof mlt_properties_s + * \param this the properties to copy from + * \param that The properties to copy to + * \param prefix the property names to match (required) + * \return false + */ int mlt_properties_pass( mlt_properties this, mlt_properties that, const char *prefix ) { @@ -277,8 +333,13 @@ int mlt_properties_pass( mlt_properties this, mlt_properties that, const char *p return 0; } -/** Locate a property by name -*/ +/** Locate a property by name. + * + * \private \memberof mlt_properties_s + * \param this a properties list + * \param name the property to lookup by name + * \return the property or NULL for failure + */ static inline mlt_property mlt_properties_find( mlt_properties this, const char *name ) { @@ -291,11 +352,11 @@ static inline mlt_property mlt_properties_find( mlt_properties this, const char { // Check if we're hashed if ( list->count > 0 && - name[ 0 ] == list->name[ i ][ 0 ] && + name[ 0 ] == list->name[ i ][ 0 ] && !strcmp( list->name[ i ], name ) ) value = list->value[ i ]; - // Locate the item + // Locate the item for ( i = list->count - 1; value == NULL && i >= 0; i -- ) if ( name[ 0 ] == list->name[ i ][ 0 ] && !strcmp( list->name[ i ], name ) ) value = list->value[ i ]; @@ -305,7 +366,12 @@ static inline mlt_property mlt_properties_find( mlt_properties this, const char } /** Add a new property. -*/ + * + * \private \memberof mlt_properties_s + * \param this a properties list + * \param name the name of the new property + * \return the new property + */ static mlt_property mlt_properties_add( mlt_properties this, const char *name ) { @@ -332,8 +398,13 @@ static mlt_property mlt_properties_add( mlt_properties this, const char *name ) return list->value[ list->count ++ ]; } -/** Fetch a property by name - this includes add if not found. -*/ +/** Fetch a property by name and add one if not found. + * + * \private \memberof mlt_properties_s + * \param this a properties list + * \param name the property to lookup or add + * \return the property + */ static mlt_property mlt_properties_fetch( mlt_properties this, const char *name ) { @@ -348,9 +419,14 @@ static mlt_property mlt_properties_fetch( mlt_properties this, const char *name return property; } -/** Pass property 'name' from 'that' to 'this' -* Who to blame: Zach -*/ +/** Copy a property to another properties list. + * + * \public \memberof mlt_properties_s + * \author Zach + * \param this the properties to copy from + * \param that the properties to copy to + * \param name the name of the property to copy + */ void mlt_properties_pass_property( mlt_properties this, mlt_properties that, const char *name ) { @@ -362,9 +438,17 @@ void mlt_properties_pass_property( mlt_properties this, mlt_properties that, con mlt_property_pass( mlt_properties_fetch( this, name ), that_prop ); } -/** Pass all properties from 'that' to 'this' as found in comma seperated 'list'. -* Who to blame: Zach -*/ +/** Copy all properties specified in a comma-separated list to another properties list. + * + * White space is also a delimiter. + * \public \memberof mlt_properties_s + * \author Zach + * \param this the properties to copy from + * \param that the properties to copy to + * \param list a delimited list of property names + * \return false + */ + int mlt_properties_pass_list( mlt_properties this, mlt_properties that, const char *list ) { @@ -394,8 +478,15 @@ int mlt_properties_pass_list( mlt_properties this, mlt_properties that, const ch } -/** Set the property. -*/ +/** Set a property to a string. + * + * This makes a copy of the string value you supply. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to set + * \param value the property's new value + * \return true if error + */ int mlt_properties_set( mlt_properties this, const char *name, const char *value ) { @@ -473,8 +564,16 @@ int mlt_properties_set( mlt_properties this, const char *name, const char *value return error; } -/** Set or default the property. -*/ +/** Set or default a property to a string. + * + * This makes a copy of the string value you supply. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to set + * \param value the string value to set or NULL to use the default + * \param def the default string if value is NULL + * \return true if error + */ int mlt_properties_set_or_default( mlt_properties this, const char *name, const char *value, const char *def ) { @@ -482,7 +581,14 @@ int mlt_properties_set_or_default( mlt_properties this, const char *name, const } /** Get a string value by name. -*/ + * + * Do not free the returned string. It's lifetime is controlled by the property + * and this properties object. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to get + * \return the property's string value or NULL if it does not exist + */ char *mlt_properties_get( mlt_properties this, const char *name ) { @@ -490,8 +596,14 @@ char *mlt_properties_get( mlt_properties this, const char *name ) return value == NULL ? NULL : mlt_property_get_string( value ); } -/** Get a name by index. -*/ +/** Get a property name by index. + * + * Do not free the returned string. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param index the numeric index of the property + * \return the name of the property or NULL if index is out of range + */ char *mlt_properties_get_name( mlt_properties this, int index ) { @@ -501,8 +613,14 @@ char *mlt_properties_get_name( mlt_properties this, int index ) return NULL; } -/** Get a string value by index. -*/ +/** Get a property's string value by index. + * + * Do not free the returned string. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param index the numeric index of the property + * \return the property value as a string or NULL if the index is out of range + */ char *mlt_properties_get_value( mlt_properties this, int index ) { @@ -513,7 +631,14 @@ char *mlt_properties_get_value( mlt_properties this, int index ) } /** Get a data value by index. -*/ + * + * Do not free the returned pointer if you supplied a destructor function when you + * set this property. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param index the numeric index of the property + * \param size the size of the binary data in bytes or NULL if the index is out of range + */ void *mlt_properties_get_data_at( mlt_properties this, int index, int *size ) { @@ -524,7 +649,11 @@ void *mlt_properties_get_data_at( mlt_properties this, int index, int *size ) } /** Return the number of items in the list. -*/ + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \return the number of property objects + */ int mlt_properties_count( mlt_properties this ) { @@ -532,8 +661,13 @@ int mlt_properties_count( mlt_properties this ) return list->count; } -/** Set a value by parsing a name=value string -*/ +/** Set a value by parsing a name=value string. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param namevalue a string containing name and value delimited by '=' + * \return true if there was an error + */ int mlt_properties_parse( mlt_properties this, const char *namevalue ) { @@ -571,8 +705,13 @@ int mlt_properties_parse( mlt_properties this, const char *namevalue ) return error; } -/** Get a value associated to the name. -*/ +/** Get an integer associated to the name. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to get + * \return The integer value, 0 if not found (which may also be a legitimate value) + */ int mlt_properties_get_int( mlt_properties this, const char *name ) { @@ -580,8 +719,14 @@ int mlt_properties_get_int( mlt_properties this, const char *name ) return value == NULL ? 0 : mlt_property_get_int( value ); } -/** Set a value associated to the name. -*/ +/** Set a property to an integer value. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to set + * \param value the integer + * \return true if error + */ int mlt_properties_set_int( mlt_properties this, const char *name, int value ) { @@ -602,8 +747,13 @@ int mlt_properties_set_int( mlt_properties this, const char *name, int value ) return error; } -/** Get a value associated to the name. -*/ +/** Get a 64-bit integer associated to the name. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to get + * \return the integer value, 0 if not found (which may also be a legitimate value) + */ int64_t mlt_properties_get_int64( mlt_properties this, const char *name ) { @@ -611,8 +761,14 @@ int64_t mlt_properties_get_int64( mlt_properties this, const char *name ) return value == NULL ? 0 : mlt_property_get_int64( value ); } -/** Set a value associated to the name. -*/ +/** Set a property to a 64-bit integer value. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to set + * \param value the integer + * \return true if error + */ int mlt_properties_set_int64( mlt_properties this, const char *name, int64_t value ) { @@ -633,8 +789,13 @@ int mlt_properties_set_int64( mlt_properties this, const char *name, int64_t val return error; } -/** Get a value associated to the name. -*/ +/** Get a floating point value associated to the name. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to get + * \return the floating point, 0 if not found (which may also be a legitimate value) + */ double mlt_properties_get_double( mlt_properties this, const char *name ) { @@ -642,8 +803,14 @@ double mlt_properties_get_double( mlt_properties this, const char *name ) return value == NULL ? 0 : mlt_property_get_double( value ); } -/** Set a value associated to the name. -*/ +/** Set a property to a floating point value. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to set + * \param value the floating point value + * \return true if error + */ int mlt_properties_set_double( mlt_properties this, const char *name, double value ) { @@ -664,8 +831,13 @@ int mlt_properties_set_double( mlt_properties this, const char *name, double val return error; } -/** Get a value associated to the name. -*/ +/** Get a position value associated to the name. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to get + * \return the position, 0 if not found (which may also be a legitimate value) + */ mlt_position mlt_properties_get_position( mlt_properties this, const char *name ) { @@ -673,8 +845,14 @@ mlt_position mlt_properties_get_position( mlt_properties this, const char *name return value == NULL ? 0 : mlt_property_get_position( value ); } -/** Set a value associated to the name. -*/ +/** Set a property to a position value. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to get + * \param value the position + * \return true if error + */ int mlt_properties_set_position( mlt_properties this, const char *name, mlt_position value ) { @@ -695,8 +873,15 @@ int mlt_properties_set_position( mlt_properties this, const char *name, mlt_posi return error; } -/** Get a value associated to the name. -*/ +/** Get a binary data value associated to the name. + * + * Do not free the returned pointer if you supplied a destructor function + * when you set this property. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to get + * \param length The size of the binary data in bytes, if available (often it is not, you should know) + */ void *mlt_properties_get_data( mlt_properties this, const char *name, int *length ) { @@ -704,8 +889,17 @@ void *mlt_properties_get_data( mlt_properties this, const char *name, int *lengt return value == NULL ? NULL : mlt_property_get_data( value, length ); } -/** Set a value associated to the name. -*/ +/** Store binary data as a property. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param name the property to set + * \param value an opaque pointer to binary data + * \param length the size of the binary data in bytes (optional) + * \param destroy a function to dellacate the binary data when the property is closed (optional) + * \param serialise a function that can serialize the binary data as text (optional) + * \return true if error + */ int mlt_properties_set_data( mlt_properties this, const char *name, void *value, int length, mlt_destructor destroy, mlt_serialiser serialise ) { @@ -724,7 +918,13 @@ int mlt_properties_set_data( mlt_properties this, const char *name, void *value, } /** Rename a property. -*/ + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param source the property to rename + * \param dest the new name + * \return true if the name is already in use + */ int mlt_properties_rename( mlt_properties this, const char *source, const char *dest ) { @@ -735,7 +935,7 @@ int mlt_properties_rename( mlt_properties this, const char *source, const char * property_list *list = this->local; int i = 0; - // Locate the item + // Locate the item for ( i = 0; i < list->count; i ++ ) { if ( !strcmp( list->name[ i ], source ) ) @@ -751,8 +951,12 @@ int mlt_properties_rename( mlt_properties this, const char *source, const char * return value != NULL; } -/** Dump the properties. -*/ +/** Dump the properties to a file handle. + * + * \public \memberof mlt_properties_s + * \param this a properties list + * \param output a file handle + */ void mlt_properties_dump( mlt_properties this, FILE *output ) { @@ -763,6 +967,14 @@ void mlt_properties_dump( mlt_properties this, FILE *output ) fprintf( output, "%s=%s\n", list->name[ i ], mlt_properties_get( this, list->name[ i ] ) ); } +/** Output the properties to a file handle. + * + * This version includes reference counts and does not put each property on a new line. + * \public \memberof mlt_properties_s + * \param this a properties pointer + * \param title a string to preface the output + * \param output a file handle + */ void mlt_properties_debug( mlt_properties this, const char *title, FILE *output ) { if ( output == NULL ) output = stderr; @@ -782,6 +994,15 @@ void mlt_properties_debug( mlt_properties this, const char *title, FILE *output fprintf( output, "\n" ); } +/** Save the properties to a file by name. + * + * This uses the dump format - one line per property. + * \public \memberof mlt_properties_s + * \param this a properties list + * \param filename the name of a file to create or overwrite + * \return true if there was an error + */ + int mlt_properties_save( mlt_properties this, const char *filename ) { int error = 1; @@ -796,8 +1017,16 @@ int mlt_properties_save( mlt_properties this, const char *filename ) } /* This is a very basic cross platform fnmatch replacement - it will fail in -** many cases, but for the basic *.XXX and YYY*.XXX, it will work ok. -*/ + * many cases, but for the basic *.XXX and YYY*.XXX, it will work ok. + */ + +/** Test whether a filename or pathname matches a shell-style pattern. + * + * \private \memberof mlt_properties_s + * \param wild a string containing a wildcard pattern + * \param file the name of a file to test against + * \return true if the file name matches the wildcard pattern + */ static int mlt_fnmatch( const char *wild, const char *file ) { @@ -832,14 +1061,30 @@ static int mlt_fnmatch( const char *wild, const char *file ) return strlen( file ) == f && strlen( wild ) == w; } +/** Compare the string or serialized value of two properties. + * + * \private \memberof mlt_properties_s + * \param this a property + * \param that a property + * \return < 0 if 'this' less than 'that', 0 if equal, or > 0 if 'this' is greater than 'that' + */ + static int mlt_compare( const void *this, const void *that ) { return strcmp( mlt_property_get_string( *( mlt_property * )this ), mlt_property_get_string( *( mlt_property * )that ) ); } -/* Obtains an optionally sorted list of the files found in a directory with a specific wild card. +/** Get the contents of a directory. + * + * Obtains an optionally sorted list of the files found in a directory with a specific wild card. * Entries in the list have a numeric name (running from 0 to count - 1). Only values change * position if sort is enabled. Designed to be posix compatible (linux, os/x, mingw etc). + * \public \memberof mlt_properties_s + * \param this a properties list + * \param dirname the name of the directory + * \param pattern a wildcard pattern to filter the directory listing + * \param sort Do you want to sort the directory listing? + * \return the number of items in the directory listing */ int mlt_properties_dir_list( mlt_properties this, const char *dirname, const char *pattern, int sort ) @@ -874,8 +1119,12 @@ int mlt_properties_dir_list( mlt_properties this, const char *dirname, const cha return mlt_properties_count( this ); } -/** Close the list. -*/ +/** Close a properties object. + * + * Deallocates the properties object and everything it contains. + * \public \memberof mlt_properties_s + * \param this a properties object + */ void mlt_properties_close( mlt_properties this ) { @@ -909,13 +1158,13 @@ void mlt_properties_close( mlt_properties this ) free( list->name[ index ] ); mlt_property_close( list->value[ index ] ); } - + // Clear up the list pthread_mutex_destroy( &list->mutex ); free( list->name ); free( list->value ); free( list ); - + // Free this now if this has no child if ( this->child == NULL ) free( this ); @@ -924,8 +1173,12 @@ void mlt_properties_close( mlt_properties this ) } /** Determine if the properties list is really just a sequence or ordered list. - Returns 0 if false or 1 if true. -*/ + * + * \public \memberof mlt_properties_s + * \param properties a properties list + * \return true if all of the property names are numeric (a sequence) + */ + int mlt_properties_is_sequence( mlt_properties properties ) { int i; @@ -936,7 +1189,8 @@ int mlt_properties_is_sequence( mlt_properties properties ) return 1; } -/** YAML Tiny Parser +/** \brief YAML Tiny Parser context structure + * * YAML is a nifty text format popular in the Ruby world as a cleaner, * less verbose alternative to XML. See this Wikipedia topic for an overview: * http://en.wikipedia.org/wiki/YAML @@ -945,6 +1199,7 @@ int mlt_properties_is_sequence( mlt_properties properties ) * YAML::Tiny is a Perl module that specifies a subset of YAML that we are * using here (for the same reasons): * http://search.cpan.org/~adamk/YAML-Tiny-1.25/lib/YAML/Tiny.pm + * \private */ struct yaml_parser_context @@ -955,10 +1210,16 @@ struct yaml_parser_context char block; char *block_name; unsigned int block_indent; - + }; typedef struct yaml_parser_context *yaml_parser; +/** Remove spaces from the left side of a string. + * + * \param s the string to trim + * \return the number of characters removed + */ + static unsigned int ltrim( char **s ) { unsigned int i = 0; @@ -969,6 +1230,12 @@ static unsigned int ltrim( char **s ) return i; } +/** Remove spaces from the right side of a string. + * + * \param s the string to trim + * \return the number of characters removed + */ + static unsigned int rtrim( char *s ) { int n = strlen( s ); @@ -978,6 +1245,15 @@ static unsigned int rtrim( char *s ) return n - i; } +/** Parse a line of YAML Tiny. + * + * Adds a property if needed. + * \private \memberof yaml_parser_context + * \param context a YAML Tiny Parser context + * \param namevalue a line of YAML Tiny + * \return true if there was an error + */ + static int parse_yaml( yaml_parser context, const char *namevalue ) { char *name_ = strdup( namevalue ); @@ -987,7 +1263,7 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) char *ptr = strchr( name, ':' ); unsigned int indent = ltrim( &name ); mlt_properties properties = mlt_deque_peek_front( context->stack ); - + // Ascending one more levels in the tree if ( indent < context->level ) { @@ -998,13 +1274,13 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) properties = mlt_deque_peek_front( context->stack ); context->level = indent; } - + // Descending a level in the tree else if ( indent > context->level && context->block == 0 ) { context->level = indent; } - + // If there is a colon that is not part of a block if ( ptr && ( indent == context->level ) ) { @@ -1015,41 +1291,41 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) context->block_name = NULL; context->block = 0; } - + // Terminate the name and setup the value pointer *( ptr ++ ) = 0; - + // Trim comment char *comment = strchr( ptr, '#' ); if ( comment ) { *comment = 0; } - - // Trim leading and trailing spaces from bare value + + // Trim leading and trailing spaces from bare value ltrim( &ptr ); rtrim( ptr ); - + // No value means a child if ( strcmp( ptr, "" ) == 0 ) { mlt_properties child = mlt_properties_new(); - mlt_properties_set_data( properties, name, child, 0, + mlt_properties_set_data( properties, name, child, 0, ( mlt_destructor )mlt_properties_close, NULL ); mlt_deque_push_front( context->stack, child ); context->index = 0; free( name_ ); return error; } - + // A dash indicates a sequence item if ( name[0] == '-' ) { mlt_properties child = mlt_properties_new(); char key[20]; - + snprintf( key, sizeof(key), "%d", context->index++ ); - mlt_properties_set_data( properties, key, child, 0, + mlt_properties_set_data( properties, key, child, 0, ( mlt_destructor )mlt_properties_close, NULL ); mlt_deque_push_front( context->stack, child ); @@ -1057,7 +1333,7 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) context->level += ltrim( &name ) + 1; properties = child; } - + // Value is quoted if ( *ptr == '\"' ) { @@ -1066,7 +1342,7 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) if ( value && value[ strlen( value ) - 1 ] == '\"' ) value[ strlen( value ) - 1 ] = 0; } - + // Value is folded or unfolded block else if ( *ptr == '|' || *ptr == '>' ) { @@ -1075,14 +1351,14 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) context->block_indent = 0; value = strdup( "" ); } - + // Bare value else { value = strdup( ptr ); } } - + // A list of scalars else if ( name[0] == '-' ) { @@ -1093,21 +1369,21 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) context->block_name = NULL; context->block = 0; } - + char key[20]; - + snprintf( key, sizeof(key), "%d", context->index++ ); ptr = name + 1; - + // Trim comment char *comment = strchr( ptr, '#' ); if ( comment ) *comment = 0; - - // Trim leading and trailing spaces from bare value + + // Trim leading and trailing spaces from bare value ltrim( &ptr ); rtrim( ptr ); - + // Value is quoted if ( *ptr == '\"' ) { @@ -1116,7 +1392,7 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) if ( value && value[ strlen( value ) - 1 ] == '\"' ) value[ strlen( value ) - 1 ] = 0; } - + // Value is folded or unfolded block else if ( *ptr == '|' || *ptr == '>' ) { @@ -1125,13 +1401,13 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) context->block_indent = 0; value = strdup( "" ); } - + // Bare value else { value = strdup( ptr ); } - + free( name_ ); name = name_ = strdup( key ); } @@ -1152,14 +1428,14 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) strcat( value, name ); name = context->block_name; } - + // Folded block else if ( context->block == '>' ) { ltrim( &name ); rtrim( name ); char *old_value = mlt_properties_get( properties, context->block_name ); - + // Blank line (prepended with spaces) is new line if ( strcmp( name, "" ) == 0 ) { @@ -1178,7 +1454,7 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) } name = context->block_name; } - + else { value = strdup( "" ); @@ -1192,6 +1468,13 @@ static int parse_yaml( yaml_parser context, const char *namevalue ) return error; } +/** Parse a YAML Tiny file by name. + * + * \public \memberof mlt_properties_s + * \param filename the name of a text file containing YAML Tiny + * \return a new properties list + */ + mlt_properties mlt_properties_parse_yaml( const char *filename ) { // Construct a standalone properties object @@ -1208,7 +1491,7 @@ mlt_properties mlt_properties_parse_yaml( const char *filename ) // Temp string char temp[ 1024 ]; char *ptemp = &temp[ 0 ]; - + // Parser context yaml_parser context = calloc( 1, sizeof( struct yaml_parser_context ) ); context->stack = mlt_deque_init(); @@ -1220,12 +1503,12 @@ mlt_properties mlt_properties_parse_yaml( const char *filename ) // Check for end-of-stream if ( strncmp( ptemp, "...", 3 ) == 0 ) break; - + // Chomp the string temp[ strlen( temp ) - 1 ] = '\0'; // Skip blank lines, comment lines, and document separator - if ( strcmp( ptemp, "" ) && ptemp[ 0 ] != '#' && strncmp( ptemp, "---", 3 ) + if ( strcmp( ptemp, "" ) && ptemp[ 0 ] != '#' && strncmp( ptemp, "---", 3 ) && strncmp( ptemp, "%YAML", 5 ) && strncmp( ptemp, "% YAML", 6 ) ) parse_yaml( context, temp ); } @@ -1243,13 +1526,17 @@ mlt_properties mlt_properties_parse_yaml( const char *filename ) return this; } -/** YAML Tiny Serialiser -*/ - -/* strbuf is a self-growing string buffer */ +/* + * YAML Tiny Serializer + */ +/** How many bytes to grow at a time */ #define STRBUF_GROWTH (1024) +/** \brief Self-growing buffer for building strings + * \private + */ + struct strbuf_s { size_t size; @@ -1258,6 +1545,12 @@ struct strbuf_s typedef struct strbuf_s *strbuf; +/** Create a new string buffer + * + * \private \memberof strbuf_s + * \return a new string buffer + */ + static strbuf strbuf_new( ) { strbuf buffer = calloc( 1, sizeof( struct strbuf_s ) ); @@ -1266,6 +1559,12 @@ static strbuf strbuf_new( ) return buffer; } +/** Destroy a string buffer + * + * \private \memberof strbuf_s + * \param buffer the string buffer to close + */ + static void strbuf_close( strbuf buffer ) { // We do not free buffer->string; strbuf user must save that pointer @@ -1274,6 +1573,16 @@ static void strbuf_close( strbuf buffer ) free( buffer ); } +/** Format a string into a string buffer + * + * A variable number of arguments follows the format string - one for each + * format specifier. + * \private \memberof strbuf_s + * \param buffer the string buffer to write into + * \param format a string that contains text and formatting instructions + * \return the formatted string + */ + static char *strbuf_printf( strbuf buffer, const char *format, ... ) { while ( buffer->string ) @@ -1293,6 +1602,13 @@ static char *strbuf_printf( strbuf buffer, const char *format, ... ) return buffer->string; } +/** Indent a line of YAML Tiny. + * + * \private \memberof strbuf_s + * \param output a string buffer + * \param indent the number of spaces to indent + */ + static inline void indent_yaml( strbuf output, int indent ) { int j; @@ -1300,12 +1616,20 @@ static inline void indent_yaml( strbuf output, int indent ) strbuf_printf( output, " " ); } +/** Convert a line string into a YAML block literal. + * + * \private \memberof strbuf_s + * \param output a string buffer + * \param value the string to format as a block literal + * \param indent the number of spaces to indent + */ + static void output_yaml_block_literal( strbuf output, const char *value, int indent ) { char *v = strdup( value ); char *sol = v; char *eol = strchr( sol, '\n' ); - + while ( eol ) { indent_yaml( output, indent ); @@ -1313,22 +1637,31 @@ static void output_yaml_block_literal( strbuf output, const char *value, int ind strbuf_printf( output, "%s\n", sol ); sol = eol + 1; eol = strchr( sol, '\n' ); - } + } indent_yaml( output, indent ); strbuf_printf( output, "%s\n", sol ); } +/** Recursively serialize a properties list into a string buffer as YAML Tiny. + * + * \private \memberof mlt_properties_s + * \param this a properties list + * \param output a string buffer to hold the serialized YAML Tiny + * \param indent the number of spaces to indent (for recursion, initialize to 0) + * \param is_parent_sequence Is 'this' properties list really just a sequence (for recursion, initialize to 0)? + */ + static void serialise_yaml( mlt_properties this, strbuf output, int indent, int is_parent_sequence ) { property_list *list = this->local; int i = 0; - + for ( i = 0; i < list->count; i ++ ) { // This implementation assumes that all data elements are property lists. // Unfortunately, we do not have run time type identification. mlt_properties child = mlt_property_get_data( list->value[ i ], NULL ); - + if ( mlt_properties_is_sequence( this ) ) { // Ignore hidden/non-serialisable items @@ -1337,7 +1670,7 @@ static void serialise_yaml( mlt_properties this, strbuf output, int indent, int // Indicate a sequence item indent_yaml( output, indent ); strbuf_printf( output, "- " ); - + // If the value can be represented as a string const char *value = mlt_properties_get( this, list->name[ i ] ); if ( value && strcmp( value, "" ) ) @@ -1358,11 +1691,11 @@ static void serialise_yaml( mlt_properties this, strbuf output, int indent, int if ( child ) serialise_yaml( child, output, indent + 2, 1 ); } - else + else { // Assume this is a normal map-oriented properties list const char *value = mlt_properties_get( this, list->name[ i ] ); - + // Ignore hidden/non-serialisable items // If the value can be represented as a string if ( list->name[ i ][ 0 ] != '_' && value && strcmp( value, "" ) ) @@ -1371,7 +1704,7 @@ static void serialise_yaml( mlt_properties this, strbuf output, int indent, int indent_yaml( output, indent ); else is_parent_sequence = 0; - + // Determine if this is an unfolded block literal if ( strchr( value, '\n' ) ) { @@ -1383,7 +1716,7 @@ static void serialise_yaml( mlt_properties this, strbuf output, int indent, int strbuf_printf( output, "%s: %s\n", list->name[ i ], value ); } } - + // Output a child as a map item if ( child ) { @@ -1397,9 +1730,15 @@ static void serialise_yaml( mlt_properties this, strbuf output, int indent, int } } -/** Serialise the properties as a string of YAML Tiny. - The caller must free the returned string. -*/ +/** Serialize a properties list as a string of YAML Tiny. + * + * The caller MUST free the returned string! + * This operates on properties containing properties as a hierarchical data + * structure. + * \public \memberof mlt_properties_s + * \param this a properties list + * \return a string containing YAML Tiny that represents the properties list + */ char *mlt_properties_serialise_yaml( mlt_properties this ) { diff --git a/src/framework/mlt_properties.h b/src/framework/mlt_properties.h index 6ecb6d80..6fc81ad7 100644 --- a/src/framework/mlt_properties.h +++ b/src/framework/mlt_properties.h @@ -1,8 +1,10 @@ -/* - * mlt_properties.h -- base properties class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates - * Contributor: Dan Dennedy +/** + * \file mlt_properties.h + * \brief Properties class declaration + * + * Copyright (C) 2003-2008 Ushodaya Enterprises Limited + * \author Charles Yates + * \author Dan Dennedy * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -26,21 +28,22 @@ #include "mlt_events.h" #include -/** The properties base class defines the basic property propagation and - handling. -*/ +/** \brief Properties class + * + * Properties is a combination list/dictionary of name/::mlt_property pairs. + * It is also a base class for many of the other MLT classes. + */ struct mlt_properties_s { - void *child; - void *local; + void *child; /**< \private the object of a subclass */ + void *local; /**< \private instance object */ + + /** the destructor virtual function */ mlt_destructor close; - void *close_object; + void *close_object; /**< the object supplied to the close virtual function */ }; -/** Public interface. -*/ - extern int mlt_properties_init( mlt_properties, void *child ); extern mlt_properties mlt_properties_new( ); extern mlt_properties mlt_properties_load( const char *file ); diff --git a/src/framework/mlt_property.c b/src/framework/mlt_property.c index 83ceb2c5..d64592f2 100644 --- a/src/framework/mlt_property.c +++ b/src/framework/mlt_property.c @@ -1,7 +1,9 @@ -/* - * mlt_property.c -- property class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_property.c + * \brief Property class definition + * + * 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 @@ -24,9 +26,53 @@ #include #include -/** Construct and uninitialised property. + +/** Bit pattern used internally to indicated representations available. */ +typedef enum +{ + mlt_prop_none = 0, //!< not set + mlt_prop_int = 1, //!< set as an integer + mlt_prop_string = 2, //!< set as string or already converted to string + mlt_prop_position = 4,//!< set as a position + mlt_prop_double = 8, //!< set as a floating point + mlt_prop_data = 16, //!< set as opaque binary + mlt_prop_int64 = 32 //!< set as a 64-bit integer +} +mlt_property_type; + +/** \brief Property class + * + * A property is like a variant or dynamic type. They are used for many things + * in MLT, but in particular they are the parameter mechanism for the plugins. + */ + +struct mlt_property_s +{ + /// Stores a bit pattern of types available for this property + mlt_property_type types; + + /// Atomic type handling + int prop_int; + mlt_position prop_position; + double prop_double; + int64_t prop_int64; + + /// String handling + char *prop_string; + + /// Generic type handling + void *data; + int length; + mlt_destructor destructor; + mlt_serialiser serialiser; +}; + +/** Construct a property and initialize it + * \public \memberof mlt_property_s + */ + mlt_property mlt_property_init( ) { mlt_property this = malloc( sizeof( struct mlt_property_s ) ); @@ -46,8 +92,12 @@ mlt_property mlt_property_init( ) return this; } -/** Clear a property. -*/ +/** Clear (0/null) a property. + * + * Frees up any associated resources in the process. + * \private \memberof mlt_property_s + * \param this a property + */ static inline void mlt_property_clear( mlt_property this ) { @@ -72,8 +122,13 @@ static inline void mlt_property_clear( mlt_property this ) this->serialiser = NULL; } -/** Set an int on this property. -*/ +/** Set the property to an integer value. + * + * \public \memberof mlt_property_s + * \param this a property + * \param value an integer + * \return false + */ int mlt_property_set_int( mlt_property this, int value ) { @@ -83,8 +138,13 @@ int mlt_property_set_int( mlt_property this, int value ) return 0; } -/** Set a double on this property. -*/ +/** Set the property to a floating point value. + * + * \public \memberof mlt_property_s + * \param this a property + * \param value a double precision floating point value + * \return false + */ int mlt_property_set_double( mlt_property this, double value ) { @@ -94,8 +154,14 @@ int mlt_property_set_double( mlt_property this, double value ) return 0; } -/** Set a position on this property. -*/ +/** Set the property to a position value. + * + * Position is a relative time value in frame units. + * \public \memberof mlt_property_s + * \param this a property + * \param value a position value + * \return false + */ int mlt_property_set_position( mlt_property this, mlt_position value ) { @@ -105,8 +171,15 @@ int mlt_property_set_position( mlt_property this, mlt_position value ) return 0; } -/** Set a string on this property. -*/ +/** Set the property to a string value. + * + * This makes a copy of the string you supply so you do not need to track + * a new reference to it. + * \public \memberof mlt_property_s + * \param this a property + * \param value the string to copy to the property + * \return true if it failed + */ int mlt_property_set_string( mlt_property this, const char *value ) { @@ -124,8 +197,13 @@ int mlt_property_set_string( mlt_property this, const char *value ) return this->prop_string == NULL; } -/** Set an int64 on this property. -*/ +/** Set the property to a 64-bit integer value. + * + * \public \memberof mlt_property_s + * \param this a property + * \param value a 64-bit integer + * \return false + */ int mlt_property_set_int64( mlt_property this, int64_t value ) { @@ -135,8 +213,20 @@ int mlt_property_set_int64( mlt_property this, int64_t value ) return 0; } -/** Set a data on this property. -*/ +/** Set a property to an opaque binary value. + * + * This does not make a copy of the data. You can use a Properties object + * with its reference tracking and the destructor function to control + * the lifetime of the data. Otherwise, pass NULL for the destructor + * function and control the lifetime yourself. + * \public \memberof mlt_property_s + * \param this a property + * \param value an opaque pointer + * \param length the number of bytes pointed to by value (optional) + * \param destructor a function to use to destroy this binary data (optional, assuming you manage the resource) + * \param serialiser a function to use to convert this binary data to a string (optional) + * \return false + */ int mlt_property_set_data( mlt_property this, void *value, int length, mlt_destructor destructor, mlt_serialiser serialiser ) { @@ -151,18 +241,30 @@ int mlt_property_set_data( mlt_property this, void *value, int length, mlt_destr return 0; } +/** Convert a base 10 or base 16 string to an integer. + * + * The string must begin with '0x' to be interpreted as hexadecimal. + * Otherwise, it is interpreted as base 10. + * \private \memberof mlt_property_s + * \param value a string to convert + * \return the resultant integer + */ static inline int mlt_property_atoi( const char *value ) { if ( value == NULL ) return 0; else if ( value[0] == '0' && value[1] == 'x' ) return strtol( value + 2, NULL, 16 ); - else + else return strtol( value, NULL, 10 ); } -/** Get an int from this property. -*/ +/** Get the property as an integer. + * + * \public \memberof mlt_property_s + * \param this a property + * \return an integer value + */ int mlt_property_get_int( mlt_property this ) { @@ -179,8 +281,12 @@ int mlt_property_get_int( mlt_property this ) return 0; } -/** Get a double from this property. -*/ +/** Get the property as a floating point. + * + * \public \memberof mlt_property_s + * \param this a property + * \return a floating point value + */ double mlt_property_get_double( mlt_property this ) { @@ -197,8 +303,13 @@ double mlt_property_get_double( mlt_property this ) return 0; } -/** Get a position from this property. -*/ +/** Get the property as a position. + * + * A position is an offset time in terms of frame units. + * \public \memberof mlt_property_s + * \param this a property + * \return the position in frames + */ mlt_position mlt_property_get_position( mlt_property this ) { @@ -215,18 +326,30 @@ mlt_position mlt_property_get_position( mlt_property this ) return 0; } +/** Convert a string to a 64-bit integer. + * + * If the string begins with '0x' it is interpreted as a hexadecimal value. + * \private \memberof mlt_property_s + * \param value a string + * \return a 64-bit integer + */ + static inline int64_t mlt_property_atoll( const char *value ) { if ( value == NULL ) return 0; else if ( value[0] == '0' && value[1] == 'x' ) return strtoll( value + 2, NULL, 16 ); - else + else return strtoll( value, NULL, 10 ); } -/** Get an int64 from this property. -*/ +/** Get the property as a signed integer. + * + * \public \memberof mlt_property_s + * \param this a property + * \return a 64-bit integer + */ int64_t mlt_property_get_int64( mlt_property this ) { @@ -243,8 +366,16 @@ int64_t mlt_property_get_int64( mlt_property this ) return 0; } -/** Get a string from this property. -*/ +/** Get the property as a string. + * + * The caller is not responsible for deallocating the returned string! + * The string is deallocated when the Property is closed. + * This tries its hardest to convert the property to string including using + * a serialization function for binary data, if supplied. + * \public \memberof mlt_property_s + * \param this a property + * \return a string representation of the property or NULL if failed + */ char *mlt_property_get_string( mlt_property this ) { @@ -286,8 +417,19 @@ char *mlt_property_get_string( mlt_property this ) return this->prop_string; } -/** Get a data and associated length. -*/ +/** Get the binary data from a property. + * + * This only works if you previously put binary data into the property. + * This does not return a copy of the data; it returns a pointer to it. + * If you supplied a destructor function when setting the binary data, + * the destructor is used when the Property is closed to free the memory. + * Therefore, only free the returned pointer if you did not supply a + * destructor function. + * \public \memberof mlt_property_s + * \param this a property + * \param[out] length the size of the binary object in bytes + * \return an opaque data pointer or NULL if not available + */ void *mlt_property_get_data( mlt_property this, int *length ) { @@ -299,8 +441,11 @@ void *mlt_property_get_data( mlt_property this, int *length ) return this->data; } -/** Close this property. -*/ +/** Destroy a property and free all related resources. + * + * \public \memberof mlt_property_s + * \param this a property + */ void mlt_property_close( mlt_property this ) { @@ -308,9 +453,15 @@ void mlt_property_close( mlt_property this ) free( this ); } -/** Pass the property 'that' to 'this'. -* Who to blame: Zach -*/ +/** Copy a property. + * + * A Property holding binary data only copies the data if a serialiser + * function was supplied when you set the Property. + * \public \memberof mlt_property_s + * \author Zach + * \param this a property + * \param that another property + */ void mlt_property_pass( mlt_property this, mlt_property that ) { mlt_property_clear( this ); @@ -333,6 +484,6 @@ void mlt_property_pass( mlt_property this, mlt_property that ) else if ( this->types & mlt_prop_data && this->serialiser != NULL ) { this->types = mlt_prop_string; - this->prop_string = this->serialiser( this->data, this->length ); + this->prop_string = this->serialiser( this->data, this->length ); } } diff --git a/src/framework/mlt_property.h b/src/framework/mlt_property.h index 01d0729a..fcf15c18 100644 --- a/src/framework/mlt_property.h +++ b/src/framework/mlt_property.h @@ -1,7 +1,9 @@ -/* - * mlt_property.h -- property class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_property.h + * \brief Property class declaration + * + * 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 @@ -23,49 +25,6 @@ #include "mlt_types.h" -/** Bit pattern for properties. -*/ - -typedef enum -{ - mlt_prop_none = 0, - mlt_prop_int = 1, - mlt_prop_string = 2, - mlt_prop_position = 4, - mlt_prop_double = 8, - mlt_prop_data = 16, - mlt_prop_int64 = 32 -} -mlt_property_type; - -/** Property structure. -*/ - -typedef struct mlt_property_s -{ - // Stores a bit pattern of types available for this property - mlt_property_type types; - - // Atomic type handling - int prop_int; - mlt_position prop_position; - double prop_double; - int64_t prop_int64; - - // String handling - char *prop_string; - - // Generic type handling - void *data; - int length; - mlt_destructor destructor; - mlt_serialiser serialiser; -} -*mlt_property; - -/** API -*/ - extern mlt_property mlt_property_init( ); extern int mlt_property_set_int( mlt_property self, int value ); extern int mlt_property_set_double( mlt_property self, double value ); @@ -84,4 +43,3 @@ extern void mlt_property_close( mlt_property self ); extern void mlt_property_pass( mlt_property this, mlt_property that ); #endif - diff --git a/src/framework/mlt_repository.c b/src/framework/mlt_repository.c index 1d93d559..f821abb4 100644 --- a/src/framework/mlt_repository.c +++ b/src/framework/mlt_repository.c @@ -1,8 +1,10 @@ -/* - * repository.c -- provides a map between service and shared objects - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates - * Contributor: Dan Dennedy +/** + * \file mlt_repository.c + * \brief provides a map between service and shared objects + * + * Copyright (C) 2003-2008 Ushodaya Enterprises Limited + * \author Charles Yates + * Dan Dennedy * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -28,6 +30,11 @@ #include #include +/** \brief Repository class + * + * \extends mlt_properties_s + */ + struct mlt_repository_s { struct mlt_properties_s parent; // a list of object files @@ -45,7 +52,7 @@ mlt_repository mlt_repository_init( const char *directory ) // Safety check if ( directory == NULL || strcmp( directory, "" ) == 0 ) return NULL; - + // Construct the repository mlt_repository this = calloc( sizeof( struct mlt_repository_s ), 1 ); mlt_properties_init( &this->parent, this ); @@ -58,7 +65,7 @@ mlt_repository mlt_repository_init( const char *directory ) mlt_properties dir = mlt_properties_new(); int count = mlt_properties_dir_list( dir, directory, NULL, 0 ); int i; - + // Iterate over files for ( i = 0; i < count; i++ ) { @@ -71,17 +78,17 @@ mlt_repository mlt_repository_init( const char *directory ) flags |= RTLD_GLOBAL; // Open the shared object - void *object = dlopen( object_name, flags ); + void *object = dlopen( object_name, flags ); if ( object != NULL ) { // Get the registration function mlt_repository_callback symbol_ptr = dlsym( object, "mlt_register" ); - + // Call the registration function if ( symbol_ptr != NULL ) { symbol_ptr( this ); - + // Register the object file for closure mlt_properties_set_data( &this->parent, object_name, object, 0, ( mlt_destructor )dlclose, NULL ); } @@ -97,7 +104,7 @@ mlt_repository mlt_repository_init( const char *directory ) } mlt_properties_close( dir ); - + return this; } @@ -168,7 +175,7 @@ void *mlt_repository_create( mlt_repository this, mlt_profile profile, mlt_servi if ( properties != NULL ) { mlt_register_callback symbol_ptr = mlt_properties_get_data( properties, "symbol", NULL ); - + // Construct the service return ( symbol_ptr != NULL ) ? symbol_ptr( profile, type, service, input ) : NULL; } @@ -238,7 +245,7 @@ mlt_properties mlt_repository_metadata( mlt_repository self, mlt_service_type ty { mlt_properties metadata = NULL; mlt_properties properties = get_service_properties( self, type, service ); - + // If this is a valid service if ( properties ) { @@ -254,10 +261,10 @@ mlt_properties mlt_repository_metadata( mlt_repository self, mlt_service_type ty { // Fetch the callback data arg void *data = mlt_properties_get_data( properties, "metadata_cb_data", NULL ); - + // Fetch the metadata through the callback metadata = callback( type, service, data ); - + // Cache the metadata if ( metadata ) // Include dellocation and serialisation @@ -286,14 +293,14 @@ static char *getenv_locale() } /** Return a list of user-preferred language codes taken from environment variables. -*/ +*/ mlt_properties mlt_repository_languages( mlt_repository self ) { mlt_properties languages = mlt_properties_get_data( &self->parent, "languages", NULL ); if ( languages ) return languages; - + languages = mlt_properties_new(); char *locale = getenv_locale(); if ( locale ) diff --git a/src/framework/mlt_repository.h b/src/framework/mlt_repository.h index 1487ec95..5873d909 100644 --- a/src/framework/mlt_repository.h +++ b/src/framework/mlt_repository.h @@ -1,8 +1,10 @@ -/* - * repository.h -- provides a map between service and shared objects - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates - * Contributor: Dan Dennedy +/** + * \file mlt_repository.h + * \brief provides a map between service and shared objects + * + * Copyright (C) 2003-2008 Ushodaya Enterprises Limited + * \author Charles Yates + * Dan Dennedy * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -54,7 +56,7 @@ typedef mlt_properties ( *mlt_metadata_callback )( mlt_service_type, const char extern mlt_repository mlt_repository_init( const char *directory ); extern void mlt_repository_register( mlt_repository self, mlt_service_type service_type, const char *service, mlt_register_callback ); -extern void *mlt_repository_create( mlt_repository self, mlt_profile profile, mlt_service_type type, const char *service, void *arg ); +extern void *mlt_repository_create( mlt_repository self, mlt_profile profile, mlt_service_type type, const char *service, void *arg ); extern void mlt_repository_close( mlt_repository self ); extern mlt_properties mlt_repository_consumers( mlt_repository self ); extern mlt_properties mlt_repository_filters( mlt_repository self ); diff --git a/src/framework/mlt_service.c b/src/framework/mlt_service.c index 04d929aa..5491c139 100644 --- a/src/framework/mlt_service.c +++ b/src/framework/mlt_service.c @@ -1,7 +1,9 @@ -/* - * mlt_service.c -- interface for all service classes - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_service.c + * \brief interface definition for all service classes + * + * 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 @@ -26,18 +28,17 @@ #include #include -/** IMPORTANT NOTES +/* IMPORTANT NOTES The base service implements a null frame producing service - as such, - it is functional without extension and will produce test cards frames + it is functional without extension and will produce test cards frames and PAL sized audio frames. - PLEASE DO NOT CHANGE THIS BEHAVIOUR!!! OVERRIDE THE METHODS THAT + PLEASE DO NOT CHANGE THIS BEHAVIOUR!!! OVERRIDE THE METHODS THAT CONTROL THIS IN EXTENDING CLASSES. */ -/** Private service definition. -*/ +/** \brief private service definition */ typedef struct { @@ -52,16 +53,21 @@ typedef struct } mlt_service_base; -/** Private methods -*/ +/* Private methods + */ static void mlt_service_disconnect( mlt_service this ); static void mlt_service_connect( mlt_service this, mlt_service that ); static int service_get_frame( mlt_service this, mlt_frame_ptr frame, int index ); static void mlt_service_property_changed( mlt_listener, mlt_properties owner, mlt_service this, void **args ); -/** Constructor -*/ +/** Initialize a service. + * + * \public \memberof mlt_service_s + * \param this the service structure to initialize + * \param child pointer to the child object for the subclass + * \return true if there was an error + */ int mlt_service_init( mlt_service this, void *child ) { @@ -78,7 +84,7 @@ int mlt_service_init( mlt_service this, void *child ) // Associate the methods this->get_frame = service_get_frame; - + // Initialise the properties error = mlt_properties_init( &this->parent, this ); if ( error == 0 ) @@ -95,24 +101,52 @@ int mlt_service_init( mlt_service this, void *child ) return error; } +/** The listener for property changes. + * + * \private \memberof mlt_service_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_service_property_changed( mlt_listener listener, mlt_properties owner, mlt_service this, void **args ) { if ( listener != NULL ) listener( owner, this, ( char * )args[ 0 ] ); } +/** Acquire a mutual exclusion lock on this service. + * + * \public \memberof mlt_service_s + * \param this the service to lock + */ + void mlt_service_lock( mlt_service this ) { if ( this != NULL ) pthread_mutex_lock( &( ( mlt_service_base * )this->local )->mutex ); } +/** Release a mutual exclusion lock on this service. + * + * \public \memberof mlt_service_s + * \param this the service to unlock + */ + void mlt_service_unlock( mlt_service this ) { if ( this != NULL ) pthread_mutex_unlock( &( ( mlt_service_base * )this->local )->mutex ); } +/** Identify the subclass of the service. + * + * \public \memberof mlt_service_s + * \param this a service + * \return the subclass + */ + mlt_service_type mlt_service_identify( mlt_service this ) { mlt_service_type type = invalid_type; @@ -143,12 +177,17 @@ mlt_service_type mlt_service_identify( mlt_service this ) return type; } -/** Connect a producer service. - Returns: > 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 -*/ +/** Connect a producer to the service. + * + * \public \memberof mlt_service_s + * \param this a service + * \param producer a producer + * \param index which of potentially multiple producers to this service (0 based) + * \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_service_connect_producer( mlt_service this, mlt_service producer, int index ) { @@ -192,10 +231,10 @@ int mlt_service_connect_producer( mlt_service this, mlt_service producer, int in // Now we disconnect the producer service from its consumer mlt_service_disconnect( producer ); - + // Add the service to index specified base->in[ index ] = producer; - + // Determine the number of active tracks if ( index >= base->count ) base->count = index + 1; @@ -216,7 +255,10 @@ int mlt_service_connect_producer( mlt_service this, mlt_service producer, int in } /** Disconnect this service from its consumer. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + */ static void mlt_service_disconnect( mlt_service this ) { @@ -231,7 +273,11 @@ static void mlt_service_disconnect( mlt_service this ) } /** Obtain the consumer this service is connected to. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \return the consumer + */ mlt_service mlt_service_consumer( mlt_service this ) { @@ -243,7 +289,11 @@ mlt_service mlt_service_consumer( mlt_service this ) } /** Obtain the producer this service is connected to. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \return the last-most producer + */ mlt_service mlt_service_producer( mlt_service this ) { @@ -254,8 +304,13 @@ mlt_service mlt_service_producer( mlt_service this ) return base->count > 0 ? base->in[ base->count - 1 ] : NULL; } -/** Associate this service to the consumer. -*/ +/** Associate this service to a consumer. + * + * Overwrites connection to any existing consumer. + * \private \memberof mlt_service_s + * \param this a service + * \param that a consumer + */ static void mlt_service_connect( mlt_service this, mlt_service that ) { @@ -269,8 +324,12 @@ static void mlt_service_connect( mlt_service this, mlt_service that ) } } -/** Get the first connected producer service. -*/ +/** Get the first connected producer. + * + * \public \memberof mlt_service_s + * \param this a service + * \return the first producer + */ mlt_service mlt_service_get_producer( mlt_service this ) { @@ -281,12 +340,18 @@ mlt_service mlt_service_get_producer( mlt_service this ) if ( base->in != NULL ) producer = base->in[ 0 ]; - + return producer; } -/** Default implementation of get_frame. -*/ +/** Default implementation of the get_frame virtual function. + * + * \private \memberof mlt_service_s + * \param this a service + * \param[out] frame a frame by reference + * \param index as determined by the producer + * \return false + */ static int service_get_frame( mlt_service this, mlt_frame_ptr frame, int index ) { @@ -302,15 +367,24 @@ static int service_get_frame( mlt_service this, mlt_frame_ptr frame, int index ) } /** Return the properties object. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \return the properties + */ -mlt_properties mlt_service_properties( mlt_service self ) +mlt_properties mlt_service_properties( mlt_service this ) { - return self != NULL ? &self->parent : NULL; + return this != NULL ? &this->parent : NULL; } -/** Recursively apply attached filters -*/ +/** Recursively apply attached filters. + * + * \public \memberof mlt_service_s + * \param this a service + * \param frame a frame + * \param index used to track depth of recursion, top caller should supply 0 + */ void mlt_service_apply_filters( mlt_service this, mlt_frame frame, int index ) { @@ -320,6 +394,7 @@ 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 ) @@ -345,7 +420,13 @@ void mlt_service_apply_filters( mlt_service this, mlt_frame frame, int index ) } /** Obtain a frame. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \param[out] frame a frame by reference + * \param index as determined by the producer + * \return true if there was an error + */ int mlt_service_get_frame( mlt_service this, mlt_frame_ptr frame, int index ) { @@ -390,13 +471,25 @@ int mlt_service_get_frame( mlt_service this, mlt_frame_ptr frame, int index ) return result; } +/** The service-changed event handler. + * + * \private \memberof mlt_service_s + * \param owner ignored + * \param this the service on which the "service-changed" event is fired + */ + static void mlt_service_filter_changed( mlt_service owner, mlt_service this ) { mlt_events_fire( MLT_SERVICE_PROPERTIES( this ), "service-changed", NULL ); } /** Attach a filter. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \param filter the filter to attach + * \return true if there was an error + */ int mlt_service_attach( mlt_service this, mlt_filter filter ) { @@ -438,7 +531,12 @@ int mlt_service_attach( mlt_service this, mlt_filter filter ) } /** Detach a filter. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \param filter the filter to detach + * \return true if there was an error + */ int mlt_service_detach( mlt_service this, mlt_filter filter ) { @@ -468,7 +566,12 @@ int mlt_service_detach( mlt_service this, mlt_filter filter ) } /** Retrieve a filter. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \param index which one of potentially multiple filters + * \return the filter or null if there was an error + */ mlt_filter mlt_service_filter( mlt_service this, int index ) { @@ -483,15 +586,22 @@ mlt_filter mlt_service_filter( mlt_service this, int index ) } /** Retrieve the profile. -*/ + * + * \public \memberof mlt_service_s + * \param this a service + * \return the profile + */ mlt_profile mlt_service_profile( mlt_service this ) { return mlt_properties_get_data( MLT_SERVICE_PROPERTIES( this ), "_profile", NULL ); } -/** Close the service. -*/ +/** Destroy a service. + * + * \public \memberof mlt_service_s + * \param this the service to destroy + */ void mlt_service_close( mlt_service this ) { @@ -525,4 +635,3 @@ void mlt_service_close( mlt_service this ) mlt_service_unlock( this ); } } - diff --git a/src/framework/mlt_service.h b/src/framework/mlt_service.h index a2d71a5d..96a560a9 100644 --- a/src/framework/mlt_service.h +++ b/src/framework/mlt_service.h @@ -1,7 +1,9 @@ -/* - * mlt_service.h -- interface for all service classes - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_service.h + * \brief interface declaration for all service classes + * + * 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 @@ -24,27 +26,50 @@ #include "mlt_properties.h" #include "mlt_profile.h" -/** The interface definition for all services. -*/ +/** \brief Service abstract base class + * + * \extends mlt_properties + * The service is the base class for all of the interesting classes and + * plugins for MLT. A service can have multiple inputs connections to + * other services called its "producers" but only a single output to another + * service called its "consumer." A service that has both producer and + * consumer connections is called a filter. Any service can have zero or more + * filters "attached" to it. We call any collection of services and their + * connections a "service network," which is similar to what DirectShow calls + * a filter graph or what gstreamer calls an element pipeline. + * + * \event \em service-changed + * \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 _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. + * \properties \em _profile stores the mlt_profile for a service + */ struct mlt_service_s { - /* We're extending properties here */ - struct mlt_properties_s parent; + struct mlt_properties_s parent; /**< \private */ - /* Protected virtual */ + /** Get a frame of data (virtual function). + * + * \param mlt_producer a producer + * \param mlt_frame_ptr a frame pointer by reference + * \param int an index + * \return true if there was an error + */ int ( *get_frame )( mlt_service self, mlt_frame_ptr frame, int index ); + + /** the destructor virtual function */ mlt_destructor close; - void *close_object; + void *close_object; /**< the object supplied to the close virtual function */ - /* Private data */ - void *local; - void *child; + void *local; /**< \private instance object */ + void *child; /**< \private the object of a subclass */ }; -/** The public API. -*/ - #define MLT_SERVICE_PROPERTIES( service ) ( &( service )->parent ) extern int mlt_service_init( mlt_service self, void *child ); @@ -52,6 +77,7 @@ extern void mlt_service_lock( mlt_service self ); extern void mlt_service_unlock( mlt_service self ); extern mlt_service_type mlt_service_identify( mlt_service self ); extern int mlt_service_connect_producer( mlt_service self, mlt_service producer, int index ); +extern mlt_service mlt_service_get_producer( mlt_service self ); extern int mlt_service_get_frame( mlt_service self, mlt_frame_ptr frame, int index ); extern mlt_properties mlt_service_properties( mlt_service self ); extern mlt_service mlt_service_consumer( mlt_service self ); @@ -61,11 +87,7 @@ extern int mlt_service_detach( mlt_service self, mlt_filter filter ); extern void mlt_service_apply_filters( mlt_service self, mlt_frame frame, int index ); extern mlt_filter mlt_service_filter( mlt_service self, int index ); extern mlt_profile mlt_service_profile( mlt_service self ); - extern void mlt_service_close( mlt_service self ); -/* I'm not sure about self one - leaving it out of docs for now (only used in consumer_westley) */ -extern mlt_service mlt_service_get_producer( mlt_service self ); - #endif diff --git a/src/framework/mlt_tokeniser.c b/src/framework/mlt_tokeniser.c index 619a4898..9d3977e7 100644 --- a/src/framework/mlt_tokeniser.c +++ b/src/framework/mlt_tokeniser.c @@ -1,7 +1,9 @@ -/* - * mlt_tokeniser.c -- String tokeniser - * Copyright (C) 2002-2003 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_tokeniser.c + * \brief string tokeniser + * + * Copyright (C) 2002-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 @@ -126,7 +128,7 @@ int mlt_tokeniser_parse_new( mlt_tokeniser tokeniser, char *string, char *delimi count = 0 - ( count - 1 ); mlt_tokeniser_append( tokeniser, token ); } - + free( token ); return count; } diff --git a/src/framework/mlt_tokeniser.h b/src/framework/mlt_tokeniser.h index 1dcf21b8..c0201793 100644 --- a/src/framework/mlt_tokeniser.h +++ b/src/framework/mlt_tokeniser.h @@ -1,7 +1,9 @@ -/* - * mlt_tokeniser.h -- String tokeniser +/** + * \file mlt_tokeniser.h + * \brief string tokeniser + * * Copyright (C) 2002-2003 Ushodaya Enterprises Limited - * Author: Charles Yates + * \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 @@ -21,8 +23,9 @@ #ifndef _MLT_TOKENISER_H_ #define _MLT_TOKENISER_H_ -/** Structure for tokeniser. -*/ +/** \brief Tokeniser class + * + */ typedef struct { @@ -33,7 +36,7 @@ typedef struct } *mlt_tokeniser, mlt_tokeniser_t; -/** Remote parser API. +/* Remote parser API. */ extern mlt_tokeniser mlt_tokeniser_init( ); diff --git a/src/framework/mlt_tractor.c b/src/framework/mlt_tractor.c index 9ab3d8b1..3a3907b3 100644 --- a/src/framework/mlt_tractor.c +++ b/src/framework/mlt_tractor.c @@ -1,7 +1,9 @@ -/* - * mlt_tractor.c -- tractor service class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_tractor.c + * \brief tractor service class + * + * 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 @@ -283,7 +285,7 @@ static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int tra // Determine whether this tractor feeds to the consumer or stops here int global_feed = mlt_properties_get_int( properties, "global_feed" ); - // If we don't have one, we're in trouble... + // If we don't have one, we're in trouble... if ( multitrack != NULL ) { // Used to garbage collect all frames @@ -390,14 +392,14 @@ static int producer_get_frame( mlt_producer parent, mlt_frame_ptr frame, int tra first_video = temp; // Ensure that all frames know the aspect ratio of the background - mlt_properties_set_double( temp_properties, "output_ratio", + mlt_properties_set_double( temp_properties, "output_ratio", mlt_properties_get_double( MLT_FRAME_PROPERTIES( first_video ), "aspect_ratio" ) ); mlt_properties_set_int( MLT_FRAME_PROPERTIES( temp ), "image_count", ++ image_count ); image_count = 1; } } - + // Now stack callbacks if ( audio != NULL ) { diff --git a/src/framework/mlt_tractor.h b/src/framework/mlt_tractor.h index b9f5545d..52496a4a 100644 --- a/src/framework/mlt_tractor.h +++ b/src/framework/mlt_tractor.h @@ -1,7 +1,9 @@ -/* - * mlt_tractor.h -- tractor service class - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_tractor.h + * \brief tractor service class + * + * 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 @@ -23,8 +25,10 @@ #include "mlt_producer.h" -/** Private structure. -*/ +/** \brief Tractor class + * + * \extends mlt_producer_s + */ struct mlt_tractor_s { diff --git a/src/framework/mlt_transition.c b/src/framework/mlt_transition.c index 304e3ea8..7ab5f2fb 100644 --- a/src/framework/mlt_transition.c +++ b/src/framework/mlt_transition.c @@ -1,7 +1,9 @@ -/* - * mlt_transition.c -- abstraction for all transition services - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_transition.c + * \brief abstraction for all transition 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 @@ -156,7 +158,7 @@ mlt_frame mlt_transition_process( mlt_transition this, mlt_frame a_frame, mlt_fr /** Get a frame from this transition. - The logic is complex here. A transition is typically applied to frames on the a and + The logic is complex here. A transition is typically applied to frames on the a and b tracks specified in the connect method above and only if both contain valid info for the transition type (this is either audio or image). @@ -171,15 +173,15 @@ mlt_frame mlt_transition_process( mlt_transition this, mlt_frame a_frame, mlt_fr +----------+-------------+ 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, - it too would be inactive. This isn't an ideal situation - it's better if the B + 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, + it too would be inactive. This isn't an ideal situation - it's better if the B transition simply treats the frames from c3 as though they're the a track. - For this to work, we cache all frames coming from all tracks between the a and b - tracks. Before we process, we determine that the b frame contains someting of the + For this to work, we cache all frames coming from all tracks between the a and b + tracks. Before we process, we determine that the b frame contains someting of the right type and then we determine which frame to use as the a frame (selecting a - matching frame from a_track to b_track - 1). If both frames contain data of the + matching frame from a_track to b_track - 1). If both frames contain data of the correct type, we process the transition. This method is invoked for each track and we return the cached frames as needed. @@ -277,19 +279,19 @@ static int transition_get_frame( mlt_service service, mlt_frame_ptr frame, int i { // Process the transition *frame = mlt_transition_process( this, a_frame_ptr, b_frame_ptr ); - + // We need to ensure that the tractor doesn't consider this frame for output if ( *frame == a_frame_ptr ) b_hide |= type; else a_hide |= type; - + mlt_properties_set_int( MLT_FRAME_PROPERTIES( a_frame_ptr ), "hide", a_hide ); mlt_properties_set_int( MLT_FRAME_PROPERTIES( b_frame_ptr ), "hide", b_hide ); } } } - + // Obtain the frame from the cache or the producer we're attached to if ( index >= a_track && index <= b_track ) *frame = this->frames[ index ]; diff --git a/src/framework/mlt_transition.h b/src/framework/mlt_transition.h index 7b51de86..0a38157b 100644 --- a/src/framework/mlt_transition.h +++ b/src/framework/mlt_transition.h @@ -1,7 +1,9 @@ -/* - * mlt_transition.h -- abstraction for all transition services - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_transition.h + * \brief abstraction for all transition 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 @@ -23,8 +25,10 @@ #include "mlt_service.h" -/** The interface definition for all transitions. -*/ +/** \brief Transition abstract service class + * + * \extends mlt_service_s + */ struct mlt_transition_s { @@ -39,10 +43,10 @@ struct mlt_transition_s /* Protected */ void *child; - + /* track and in/out points */ mlt_service producer; - + /* Private */ mlt_frame *frames; int held; diff --git a/src/framework/mlt_types.h b/src/framework/mlt_types.h index d550c3f9..34c5a213 100644 --- a/src/framework/mlt_types.h +++ b/src/framework/mlt_types.h @@ -1,7 +1,9 @@ -/* - * mlt_types.h -- provides forward definitions of all public types - * Copyright (C) 2003-2004 Ushodaya Enterprises Limited - * Author: Charles Yates +/** + * \file mlt_types.h + * \brief Provides forward definitions of all public types + * + * 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 @@ -29,44 +31,52 @@ #include "mlt_pool.h" +/** The set of supported image formats */ + typedef enum { - mlt_image_none = 0, - mlt_image_rgb24, - mlt_image_rgb24a, - mlt_image_yuv422, - mlt_image_yuv420p, - mlt_image_opengl + mlt_image_none = 0,/**< image not available */ + mlt_image_rgb24, /**< 8-bit RGB */ + mlt_image_rgb24a, /**< 8-bit RGB with alpha channel */ + mlt_image_yuv422, /**< 8-bit YUV 4:2:2 packed */ + mlt_image_yuv420p, /**< 8-bit YUV 4:2:0 planar */ + mlt_image_opengl /**< suitable for OpenGL texture */ } mlt_image_format; +/** The set of supported audio formats */ + typedef enum { - mlt_audio_none = 0, - mlt_audio_pcm + mlt_audio_none = 0,/**< audio not available */ + mlt_audio_pcm /**< signed 16-bit interleaved PCM */ } mlt_audio_format; +/** The relative time qualifiers */ + typedef enum { - mlt_whence_relative_start, - mlt_whence_relative_current, - mlt_whence_relative_end + mlt_whence_relative_start, /**< relative to the beginning */ + mlt_whence_relative_current,/**< relative to the current position */ + mlt_whence_relative_end /**< relative to the end */ } mlt_whence; +/** The recognized subclasses of mlt_service */ + typedef enum { - invalid_type, - unknown_type, - producer_type, - playlist_type, - tractor_type, - multitrack_type, - filter_type, - transition_type, - consumer_type, - field_type + invalid_type, /**< invalid service */ + unknown_type, /**< unknown class */ + producer_type, /**< Producer class */ + tractor_type, /**< Tractor class */ + playlist_type, /**< Playlist class */ + multitrack_type, /**< Multitrack class */ + filter_type, /**< Filter class */ + transition_type, /**< Transition class */ + consumer_type, /**< Consumer class */ + field_type /**< Field class */ } mlt_service_type; @@ -78,33 +88,34 @@ typedef double mlt_position; typedef int32_t mlt_position; #endif -typedef struct mlt_frame_s *mlt_frame, **mlt_frame_ptr; -typedef struct mlt_properties_s *mlt_properties; -typedef struct mlt_event_struct *mlt_event; -typedef struct mlt_service_s *mlt_service; -typedef struct mlt_producer_s *mlt_producer; -typedef struct mlt_playlist_s *mlt_playlist; -typedef struct mlt_multitrack_s *mlt_multitrack; -typedef struct mlt_filter_s *mlt_filter; -typedef struct mlt_transition_s *mlt_transition; -typedef struct mlt_tractor_s *mlt_tractor; -typedef struct mlt_field_s *mlt_field; -typedef struct mlt_consumer_s *mlt_consumer; -typedef struct mlt_parser_s *mlt_parser; -typedef struct mlt_deque_s *mlt_deque; -typedef struct mlt_geometry_s *mlt_geometry; -typedef struct mlt_geometry_item_s *mlt_geometry_item; -typedef struct mlt_profile_s *mlt_profile; - -typedef void ( *mlt_destructor )( void * ); -typedef char *( *mlt_serialiser )( void *, int length ); - -#define MLT_SERVICE(x) ( ( mlt_service )( x ) ) -#define MLT_PRODUCER(x) ( ( mlt_producer )( x ) ) -#define MLT_MULTITRACK(x) ( ( mlt_multitrack )( x ) ) -#define MLT_PLAYLIST(x) ( ( mlt_playlist )( x ) ) -#define MLT_TRACTOR(x) ( ( mlt_tractor )( x ) ) -#define MLT_FILTER(x) ( ( mlt_filter )( x ) ) -#define MLT_TRANSITION(x) ( ( mlt_transition )( x ) ) +typedef struct mlt_frame_s *mlt_frame, **mlt_frame_ptr; /**< pointer to Frame object */ +typedef struct mlt_property_s *mlt_property; /**< pointer to Property object */ +typedef struct mlt_properties_s *mlt_properties; /**< pointer to Properties object */ +typedef struct mlt_event_struct *mlt_event; /**< pointer to Event object */ +typedef struct mlt_service_s *mlt_service; /**< pointer to Service object */ +typedef struct mlt_producer_s *mlt_producer; /**< pointer to Producer object */ +typedef struct mlt_playlist_s *mlt_playlist; /**< pointer to Playlist object */ +typedef struct mlt_multitrack_s *mlt_multitrack; /**< pointer to Multitrack object */ +typedef struct mlt_filter_s *mlt_filter; /**< pointer to Filter object */ +typedef struct mlt_transition_s *mlt_transition; /**< pointer to Transition object */ +typedef struct mlt_tractor_s *mlt_tractor; /**< pointer to Tractor object */ +typedef struct mlt_field_s *mlt_field; /**< pointer to Field object */ +typedef struct mlt_consumer_s *mlt_consumer; /**< pointer to Consumer object */ +typedef struct mlt_parser_s *mlt_parser; /**< pointer to Properties object */ +typedef struct mlt_deque_s *mlt_deque; /**< pointer to Deque object */ +typedef struct mlt_geometry_s *mlt_geometry; /**< pointer to Geometry object */ +typedef struct mlt_geometry_item_s *mlt_geometry_item; /**< pointer to Geometry Item object */ +typedef struct mlt_profile_s *mlt_profile; /**< pointer to Profile object */ + +typedef void ( *mlt_destructor )( void * ); /**< pointer to destructor function */ +typedef char *( *mlt_serialiser )( void *, int length );/**< pointer to serialization function */ + +#define MLT_SERVICE(x) ( ( mlt_service )( x ) ) /**< Cast to a Service pointer */ +#define MLT_PRODUCER(x) ( ( mlt_producer )( x ) ) /**< Cast to a Producer pointer */ +#define MLT_MULTITRACK(x) ( ( mlt_multitrack )( x ) ) /**< Cast to a Multitrack pointer */ +#define MLT_PLAYLIST(x) ( ( mlt_playlist )( x ) ) /**< Cast to a Playlist pointer */ +#define MLT_TRACTOR(x) ( ( mlt_tractor )( x ) ) /**< Cast to a Tractor pointer */ +#define MLT_FILTER(x) ( ( mlt_filter )( x ) ) /**< Cast to a Filter pointer */ +#define MLT_TRANSITION(x) ( ( mlt_transition )( x ) ) /**< Cast to a Transition pointer */ #endif -- 2.39.2