-/*
- * mlt_consumer.c -- abstraction for all consumer services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_consumer.c
+ * \brief abstraction for all consumer services
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
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;
{
// Get the properties from the service
mlt_properties properties = MLT_SERVICE_PROPERTIES( &this->parent );
-
+
// Apply profile to properties
if ( profile == NULL )
{
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" ) );
// 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;
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 )
-/*
- * mlt_consumer.h -- abstraction for all consumer services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_consumer.h
+ * \brief abstraction for all consumer services
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_events.h"
#include <pthread.h>
-/** The interface definition for all consumers.
-*/
+/** \brief Consumer abstract service class
+ *
+ * \extends mlt_service_s
+ */
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 ) )
-/*
- * mlt_deque.c -- double ended queue
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_deque.c
+ * \brief double ended queue
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <stdlib.h>
#include <string.h>
+/** \brief Deque entry class
+ *
+ */
+
typedef union
{
void *addr;
}
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
{
};
/** Create a deque.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \return a new deque
+ */
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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** Pop an item.
-*/
+ *
+ * \public \memberof mlt_deque_s
+ * \param this a pointer
+ * \return an opaque pointer
+ */
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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 );
}
-
-/*
- * mlt_deque.h -- double ended queue
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_deque.h
+ * \brief double ended queue
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
-/*
- * mlt_events.h -- event handling
- * Copyright (C) 2004-2005 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_events.c
+ * \brief event handling
+ *
+ * Copyright (C) 2004-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#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;
typedef struct mlt_events_struct *mlt_events;
+/** \brief Event class
+ *
+ */
+
struct mlt_event_struct
{
mlt_events owner;
}
}
-/** Forward declaration to private functions.
+/* Forward declaration to private functions.
*/
static mlt_events mlt_events_fetch( mlt_properties );
}
}
+/** \brief private to mlt_events_struct, used by mlt_events_wait_for() */
+
typedef struct
{
int done;
-/*
- * mlt_events.h -- event handling
- * Copyright (C) 2004-2005 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_events.h
+ * \brief event handling
+ *
+ * Copyright (C) 2004-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
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
-/*
- * mlt_field.c -- A field for planting multiple transitions and filters
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_field.c
+ * \brief a field for planting multiple transitions and filters
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <stdlib.h>
#include <string.h>
-/** Private structures.
-*/
+/** \brief Field class
+ *
+ */
struct mlt_field_s
{
};
/** Constructor.
-
+
We construct a multitrack and a tractor here.
*/
-/*
- * mlt_field.h -- A field for planting multiple transitions and services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_field.h
+ * \brief a field for planting multiple transitions and services
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_service.h"
-/** The interface definition for all filters.
-*/
+/** \brief Filter abstract service class
+ *
+ * \extends mlt_service_s
+ */
struct mlt_filter_s
{
-/*
- * mlt_frame.h -- interface for all frame classes
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_frame.h
+ * \brief interface for all frame classes
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#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 */
/* Virtual methods */
uint8_t * ( *get_alpha_mask )( mlt_frame self );
-
+
/* Private properties */
mlt_deque stack_image;
mlt_deque stack_audio;
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;\
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 ); \
-/*
- * mlt_multitrack.c -- multitrack service class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_multitrack.c
+ * \brief multitrack service class
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
this = NULL;
}
}
-
+
return 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;
// 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 );
}
int mlt_multitrack_count( mlt_multitrack this )
{
- return this->count;
+ return this->count;
}
/** Get an individual track as a producer.
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;
/** 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
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;
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
-/*
- * mlt_multitrack.h -- multitrack service class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_multitrack.h
+ * \brief multitrack service class
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_producer.h"
-/** Private definition.
-*/
+/** \brief Track class
+ */
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 */
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 ) )
-/*
- * mlt_parser.c -- service parsing functionality
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_parser.c
+ * \brief service parsing functionality
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
-/*
- * mlt_parser.h -- service parsing functionality
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_parser.h
+ * \brief service parsing functionality
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_types.h"
+/** \brief Parser class
+ *
+ * \extends mlt_properties_s
+ */
+
struct mlt_parser_s
{
struct mlt_properties_s parent;
-/*
- * mlt_playlist.c -- playlist service class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_playlist.c
+ * \brief playlist service class
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <stdlib.h>
#include <string.h>
-/** Virtual playlist entry.
+/** \brief virtual playlist entry
*/
struct playlist_entry_s
this->size = 10;
this->list = malloc( this->size * sizeof( playlist_entry * ) );
}
-
+
return 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 ) )
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;
}
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;
}
// 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;
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 );
}
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 );
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 )
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 )
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 );
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 );
-/*
- * mlt_playlist.h -- playlist service class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_playlist.h
+ * \brief playlist service class
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_producer.h"
-/** Structure for returning clip information.
-*/
+/** \brief structure for returning clip information
+ */
typedef struct
{
typedef struct playlist_entry_s playlist_entry;
+/** \brief Playlist class
+ *
+ * \extends mlt_producer_s
+ */
+
struct mlt_playlist_s
{
struct mlt_producer_s parent;
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 ) )
-/*
- * mlt_pool.c -- memory pooling functionality
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_pool.c
+ * \brief memory pooling functionality
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
static mlt_properties pools = NULL;
-/** Private pooling structure.
-*/
+/** \brief Pool (memory) class
+ */
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;
-/*
- * mlt_pool.h -- memory pooling functionality
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_pool.h
+ * \brief memory pooling functionality
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
-/*
- * mlt_producer.c -- abstraction for all producer services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_producer.c
+ * \brief abstraction for all producer services
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <stdlib.h>
#include <math.h>
-/** 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 )
{
// Initialise the producer
memset( this, 0, sizeof( struct mlt_producer_s ) );
-
+
// Associate with the child
this->child = 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;
// 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 );
}
/** 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 )
{
}
/** 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( )
{
}
/** 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 )
{
}
/** 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 )
{
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 )
{
}
/** 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 )
{
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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
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;
}
track_info;
+/** \brief private to mlt_producer_s, used by mlt_producer_optimise() */
+
typedef struct
{
mlt_producer cut;
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;
}
/** 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 )
{
-/*
- * mlt_producer.h -- abstraction for all producer services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_producer.h
+ * \brief abstraction for all producer services
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#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 ) )
-/*
- * mlt_profile.c -- video output definition
- * Copyright (C) 2007 Ushodaya Enterprises Limited
- * Author: Dan Dennedy <dan@dennedy.org>
+/**
+ * \file mlt_profile.c
+ * \brief video output definition
+ *
+ * Copyright (C) 2007-2008 Ushodaya Enterprises Limited
+ * \author Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
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" ) )
{
if ( filename[ strlen( filename ) - 1 ] != '/' )
filename[ strlen( filename ) ] = '/';
}
-
+
// Finish loading
strcat( filename, name );
profile = mlt_profile_load_file( filename );
-/*
- * mlt_profile.h -- video output definition
- * Copyright (C) 2007 Ushodaya Enterprises Limited
- * Author: Dan Dennedy <dan@dennedy.org>
+/**
+ * \file mlt_profile.h
+ * \brief video output definition
+ *
+ * Copyright (C) 2007-2008 Ushodaya Enterprises Limited
+ * \author Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_types.h"
+/** \brief Profile class
+ *
+ */
+
struct mlt_profile_s
{
char* description;
-/*
- * mlt_properties.c -- base properties class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
- * Contributor: Dan Dennedy <dan@dennedy.org>
+/**
+ * \file mlt_properties.c
+ * \brief Properties class definition
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
+ * \author Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <sys/types.h>
#include <dirent.h>
-/* ---------------- // Private Implementation // ---------------- */
-/** Private implementation of the property list.
-*/
+/** \brief private implementation of the property list */
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 )
{
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( )
{
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 )
{
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;
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 )
}
}
-/** 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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
{
// 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 ];
}
/** 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 )
{
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 )
{
return property;
}
-/** Pass property 'name' from 'that' to 'this'
-* Who to blame: Zach <zachary.drew@gmail.com>
-*/
+/** Copy a property to another properties list.
+ *
+ * \public \memberof mlt_properties_s
+ * \author Zach <zachary.drew@gmail.com>
+ * \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 )
{
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 <zachary.drew@gmail.com>
-*/
+/** 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 <zachary.drew@gmail.com>
+ * \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 )
{
}
-/** 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 )
{
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 )
{
}
/** 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 )
{
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 )
{
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 )
{
}
/** 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 )
{
}
/** 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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
}
/** 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 )
{
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 ) )
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 )
{
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;
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;
}
/* 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 )
{
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 )
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 )
{
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 );
}
/** 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;
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
* 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
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;
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 );
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 );
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 )
{
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 ) )
{
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 );
context->level += ltrim( &name ) + 1;
properties = child;
}
-
+
// Value is quoted
if ( *ptr == '\"' )
{
if ( value && value[ strlen( value ) - 1 ] == '\"' )
value[ strlen( value ) - 1 ] = 0;
}
-
+
// Value is folded or unfolded block
else if ( *ptr == '|' || *ptr == '>' )
{
context->block_indent = 0;
value = strdup( "" );
}
-
+
// Bare value
else
{
value = strdup( ptr );
}
}
-
+
// A list of scalars
else if ( name[0] == '-' )
{
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 == '\"' )
{
if ( value && value[ strlen( value ) - 1 ] == '\"' )
value[ strlen( value ) - 1 ] = 0;
}
-
+
// Value is folded or unfolded block
else if ( *ptr == '|' || *ptr == '>' )
{
context->block_indent = 0;
value = strdup( "" );
}
-
+
// Bare value
else
{
value = strdup( ptr );
}
-
+
free( name_ );
name = name_ = strdup( key );
}
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 )
{
}
name = context->block_name;
}
-
+
else
{
value = strdup( "" );
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
// 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();
// 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 );
}
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;
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 ) );
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
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 )
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;
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 );
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
// 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, "" ) )
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, "" ) )
indent_yaml( output, indent );
else
is_parent_sequence = 0;
-
+
// Determine if this is an unfolded block literal
if ( strchr( value, '\n' ) )
{
strbuf_printf( output, "%s: %s\n", list->name[ i ], value );
}
}
-
+
// Output a child as a map item
if ( child )
{
}
}
-/** 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 )
{
-/*
- * mlt_properties.h -- base properties class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
- * Contributor: Dan Dennedy <dan@dennedy.org>
+/**
+ * \file mlt_properties.h
+ * \brief Properties class declaration
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
+ * \author Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_events.h"
#include <stdio.h>
-/** 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 );
-/*
- * mlt_property.c -- property class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_property.c
+ * \brief Property class definition
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <stdlib.h>
#include <string.h>
-/** 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 ) );
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
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 )
{
free( this );
}
-/** Pass the property 'that' to 'this'.
-* Who to blame: Zach <zachary.drew@gmail.com>
-*/
+/** 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 <zachary.drew@gmail.com>
+ * \param this a property
+ * \param that another property
+ */
void mlt_property_pass( mlt_property this, mlt_property that )
{
mlt_property_clear( this );
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 );
}
}
-/*
- * mlt_property.h -- property class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_property.h
+ * \brief Property class declaration
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#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 );
extern void mlt_property_pass( mlt_property this, mlt_property that );
#endif
-
-/*
- * repository.c -- provides a map between service and shared objects
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
- * Contributor: Dan Dennedy <dan@dennedy.org>
+/**
+ * \file mlt_repository.c
+ * \brief provides a map between service and shared objects
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
+ * Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <dlfcn.h>
#include <string.h>
+/** \brief Repository class
+ *
+ * \extends mlt_properties_s
+ */
+
struct mlt_repository_s
{
struct mlt_properties_s parent; // a list of object files
// 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 );
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++ )
{
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 );
}
}
mlt_properties_close( dir );
-
+
return this;
}
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;
}
{
mlt_properties metadata = NULL;
mlt_properties properties = get_service_properties( self, type, service );
-
+
// If this is a valid service
if ( properties )
{
{
// 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
}
/** 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 )
-/*
- * repository.h -- provides a map between service and shared objects
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
- * Contributor: Dan Dennedy <dan@dennedy.org>
+/**
+ * \file mlt_repository.h
+ * \brief provides a map between service and shared objects
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
+ * Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
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 );
-/*
- * mlt_service.c -- interface for all service classes
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_service.c
+ * \brief interface definition for all service classes
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include <string.h>
#include <pthread.h>
-/** 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
{
}
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 )
{
// Associate the methods
this->get_frame = service_get_frame;
-
+
// Initialise the properties
error = mlt_properties_init( &this->parent, this );
if ( error == 0 )
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;
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 )
{
// 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;
}
/** Disconnect this service from its consumer.
-*/
+ *
+ * \public \memberof mlt_service_s
+ * \param this a service
+ */
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 )
{
}
/** 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 )
{
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 )
{
}
}
-/** 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 )
{
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 )
{
}
/** 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 )
{
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 )
}
/** 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 )
{
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 )
{
}
/** 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 )
{
}
/** 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 )
{
}
/** 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 )
{
mlt_service_unlock( this );
}
}
-
-/*
- * mlt_service.h -- interface for all service classes
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_service.h
+ * \brief interface declaration for all service classes
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#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 );
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 );
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
-/*
- * mlt_tokeniser.c -- String tokeniser
- * Copyright (C) 2002-2003 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_tokeniser.c
+ * \brief string tokeniser
+ *
+ * Copyright (C) 2002-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
count = 0 - ( count - 1 );
mlt_tokeniser_append( tokeniser, token );
}
-
+
free( token );
return count;
}
-/*
- * mlt_tokeniser.h -- String tokeniser
+/**
+ * \file mlt_tokeniser.h
+ * \brief string tokeniser
+ *
* Copyright (C) 2002-2003 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#ifndef _MLT_TOKENISER_H_
#define _MLT_TOKENISER_H_
-/** Structure for tokeniser.
-*/
+/** \brief Tokeniser class
+ *
+ */
typedef struct
{
}
*mlt_tokeniser, mlt_tokeniser_t;
-/** Remote parser API.
+/* Remote parser API.
*/
extern mlt_tokeniser mlt_tokeniser_init( );
-/*
- * mlt_tractor.c -- tractor service class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_tractor.c
+ * \brief tractor service class
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
// 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
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 )
{
-/*
- * mlt_tractor.h -- tractor service class
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_tractor.h
+ * \brief tractor service class
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_producer.h"
-/** Private structure.
-*/
+/** \brief Tractor class
+ *
+ * \extends mlt_producer_s
+ */
struct mlt_tractor_s
{
-/*
- * mlt_transition.c -- abstraction for all transition services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_transition.c
+ * \brief abstraction for all transition services
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
/** 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).
+----------+-------------+
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.
{
// 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 ];
-/*
- * mlt_transition.h -- abstraction for all transition services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_transition.h
+ * \brief abstraction for all transition services
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#include "mlt_service.h"
-/** The interface definition for all transitions.
-*/
+/** \brief Transition abstract service class
+ *
+ * \extends mlt_service_s
+ */
struct mlt_transition_s
{
/* Protected */
void *child;
-
+
/* track and in/out points */
mlt_service producer;
-
+
/* Private */
mlt_frame *frames;
int held;
-/*
- * mlt_types.h -- provides forward definitions of all public types
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_types.h
+ * \brief Provides forward definitions of all public types
+ *
+ * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
#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;
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
projects / mlt / commitdiff