-/*
- * mlt.h -- header file for lazy client and implementation code :-)
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt.h
+ * \brief header file for lazy client and implementation code :-)
+ *
+ * Copyright (C) 2003-2009 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
#ifndef _MLT_H_
#define _MLT_H_
-#define LIBMLT_VERSION_INT ((0<<16)+(2<<8)+5)
-#define LIBMLT_VERSION 0.2.5
+#define LIBMLT_VERSION_INT ((0<<16)+(3<<8)+5)
+#define LIBMLT_VERSION 0.3.5
#ifdef __cplusplus
extern "C"
/**
* \file mlt_consumer.c
* \brief abstraction for all consumer services
+ * \see mlt_consumer_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_consumer.h
* \brief abstraction for all consumer services
+ * \see mlt_consumer_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_deque.c
* \brief double ended queue
+ * \see mlt_deque_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_deque.h
* \brief double ended queue
+ * \see mlt_deque_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_events.c
* \brief event handling
+ * \see mlt_events_struct
*
- * Copyright (C) 2004-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2004-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_events.h
* \brief event handling
+ * \see mlt_events_struct
*
- * Copyright (C) 2004-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2004-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
-/*
- * mlt_factory.c -- the factory method interfaces
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_factory.c
+ * \brief the factory method interfaces
+ *
+ * Copyright (C) 2003-2009 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>
+/** the default subdirectory of the libdir for holding modules (plugins) */
#define PREFIX_LIB LIBDIR "/mlt"
+/** the default subdirectory of the install prefix for holding module (plugin) data */
#define PREFIX_DATA PREFIX "/share/mlt"
-/** Singleton repositories
-*/
+/** holds the full path to the modules directory - initialized and retained for the entire session */
static char *mlt_directory = NULL;
+/** a global properties list for holding environment config data and things needing session-oriented cleanup */
static mlt_properties global_properties = NULL;
+/** the global repository singleton */
static mlt_repository repository = NULL;
+/** the events object for the factory events */
static mlt_properties event_object = NULL;
+/** for tracking the unique_id set on each constructed service */
static int unique_id = 0;
-/** Event transmitters.
-*/
+/* Event transmitters. */
+
+/** the -create-request event transmitter
+ *
+ * \param listener
+ * \param owner
+ * \param this
+ * \param args
+ */
static void mlt_factory_create_request( mlt_listener listener, mlt_properties owner, mlt_service this, void **args )
{
listener( owner, this, ( char * )args[ 0 ], ( char * )args[ 1 ], ( mlt_service * )args[ 2 ] );
}
+/** the -create-done event transmitter
+ *
+ * \param listener
+ * \param owner
+ * \param this
+ * \param args
+ */
+
static void mlt_factory_create_done( mlt_listener listener, mlt_properties owner, mlt_service this, void **args )
{
if ( listener != NULL )
listener( owner, this, ( char * )args[ 0 ], ( char * )args[ 1 ], ( mlt_service )args[ 2 ] );
}
-/** Construct the factories.
-*/
+/** Construct the repository and factories.
+ *
+ * The environment variable MLT_PRODUCER is the name of a default producer often used by other services, defaults to "fezzil".
+ *
+ * The environment variable MLT_CONSUMER is the name of a default consumer, defaults to "sdl".
+ *
+ * The environment variable MLT_TEST_CARD is the name of a producer or file to be played when nothing is available (all tracks blank).
+ *
+ * The environment variable MLT_DATA overrides the default full path to the MLT and module supplemental data files, defaults to \p PREFIX_DATA.
+ *
+ * The environment variable MLT_PROFILE defaults to "dv_pal."
+ *
+ * The environment variable MLT_REPOSITORY overrides the default location of the plugin modules, defaults to \p PREFIX_LIB.
+ *
+ * \param directory an optional full path to a directory containing the modules that overrides the default and
+ * the MLT_REPOSITORY environment variable
+ * \return the repository
+ */
mlt_repository mlt_factory_init( const char *directory )
{
}
/** Fetch the events object.
-*/
+ *
+ * \return the global factory event object
+ */
mlt_properties mlt_factory_event_object( )
{
}
/** Fetch the module directory used in this instance.
-*/
+ *
+ * \return the full path to the module directory that this session is using
+ */
const char *mlt_factory_directory( )
{
}
/** Get a value from the environment.
-*/
+ *
+ * \param name the name of a MLT (runtime configuration) environment variable
+ * \return the value of the variable
+ */
char *mlt_environment( const char *name )
{
}
/** Set a value in the environment.
-*/
+ *
+ * \param name the name of a MLT environment variable
+ * \param value the value of the variable
+ * \return true on error
+ */
int mlt_environment_set( const char *name, const char *value )
{
return -1;
}
+/** Set some properties common to all services.
+ *
+ * This sets _unique_id, \p mlt_type, \p mlt_service (unless _mlt_service_hidden), and _profile.
+ *
+ * \param properties a service's properties list
+ * \param profile the \p mlt_profile supplied to the factory function
+ * \param type the MLT service class
+ * \param service the name of the service
+ */
+
static void set_common_properties( mlt_properties properties, mlt_profile profile, const char *type, const char *service )
{
mlt_properties_set_int( properties, "_unique_id", ++ unique_id );
}
/** Fetch a producer from the repository.
-*/
+ *
+ * \param profile the \p mlt_profile to use
+ * \param service the name of the producer (optional, defaults to MLT_PRODUCER)
+ * \param input an optional argument to the producer constructor, typically a string
+ * \return a new producer
+ */
mlt_producer mlt_factory_producer( mlt_profile profile, const char *service, void *input )
{
}
/** Fetch a filter from the repository.
-*/
+ *
+ * \param profile the \p mlt_profile to use
+ * \param service the name of the filter
+ * \param input an optional argument to the filter constructor, typically a string
+ * \return a new filter
+ */
mlt_filter mlt_factory_filter( mlt_profile profile, const char *service, void *input )
{
}
/** Fetch a transition from the repository.
-*/
+ *
+ * \param profile the \p mlt_profile to use
+ * \param service the name of the transition
+ * \param input an optional argument to the transition constructor, typically a string
+ * \return a new transition
+ */
mlt_transition mlt_factory_transition( mlt_profile profile, const char *service, void *input )
{
return obj;
}
-/** Fetch a consumer from the repository
-*/
+/** Fetch a consumer from the repository.
+ *
+ * \param profile the \p mlt_profile to use
+ * \param service the name of the consumer (optional, defaults to MLT_CONSUMER)
+ * \param input an optional argument to the consumer constructor, typically a string
+ * \return a new consumer
+ */
mlt_consumer mlt_factory_consumer( mlt_profile profile, const char *service, void *input )
{
}
/** Register an object for clean up.
-*/
+ *
+ * \param ptr an opaque pointer to anything allocated on the heap
+ * \param destructor the function pointer of the deallocation subroutine (e.g., free or \p mlt_pool_release)
+ */
void mlt_factory_register_for_clean_up( void *ptr, mlt_destructor destructor )
{
}
/** Close the factory.
-*/
+ *
+ * Cleanup all resources for the session.
+ */
void mlt_factory_close( )
{
-/*
- * mlt_factory.h -- the factory method interfaces
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_factory.h
+ * \brief the factory method interfaces
+ *
+ * Copyright (C) 2003-2009 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_profile.h"
#include "mlt_repository.h"
+/**
+ * \event \em producer-create-request fired when mlt_factory_producer is called
+ * \event \em producer-create-done fired when a producer registers itself
+ * \event \em filter-create-request fired when mlt_factory_filter is called
+ * \event \em filter-create-done fired when a filter registers itself
+ * \event \em transition-create-request fired when mlt_factory_transition is called
+ * \event \em transition-create-done fired when a transition registers itself
+ * \event \em consumer-create-request fired when mlt_factory_consumer is called
+ * \event \em consumer-create-done fired when a consumer registers itself
+ */
+
extern mlt_repository mlt_factory_init( const char *directory );
extern const char *mlt_factory_directory( );
extern char *mlt_environment( const char *name );
/**
* \file mlt_field.c
* \brief a field for planting multiple transitions and filters
+ * \see mlt_field_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/** \brief Field class
*
+ * The field is a convenience class that works with the tractor and multitrack classes to manage track filters and transitions.
*/
struct mlt_field_s
/**
* \file mlt_field.h
* \brief a field for planting multiple transitions and services
+ * \see mlt_field_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
-/*
- * mlt_filter.c -- abstraction for all filter services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_filter.c
+ * \brief abstraction for all filter services
+ * \see mlt_filter_s
+ *
+ * Copyright (C) 2003-2009 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_filter.h -- abstraction for all filter services
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_filter.h
+ * \brief abstraction for all filter services
+ * \see mlt_filter_s
+ *
+ * Copyright (C) 2003-2009 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_frame.c -- interface for all frame classes
- * Copyright (C) 2003-2004 Ushodaya Enterprises Limited
- * Author: Charles Yates <charles.yates@pandora.be>
+/**
+ * \file mlt_frame.c
+ * \brief interface for all frame classes
+ * \see mlt_frame_s
+ *
+ * Copyright (C) 2003-2009 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
of a composite where the b frame completely obscures the a frame).
The image must be writable and the destructor for the image itself must be taken
- care of on another frame and that frame cannot have a replace applied to it...
+ care of on another frame and that frame cannot have a replace applied to it...
Further it assumes that no alpha mask is in use.
- For these reasons, it can only be used in a specific situation - when you have
+ For these reasons, it can only be used in a specific situation - when you have
multiple tracks each with their own transition and these transitions are applied
- in a strictly reversed order (ie: highest numbered [lowest track] is processed
+ in a strictly reversed order (ie: highest numbered [lowest track] is processed
first).
More reliable approach - the cases should be detected during the process phase
// Remove all items from the stack
while( mlt_deque_pop_back( this->stack_image ) ) ;
- // Update the information
+ // Update the information
mlt_properties_set_data( MLT_FRAME_PROPERTIES( this ), "image", image, 0, NULL, NULL );
mlt_properties_set_int( MLT_FRAME_PROPERTIES( this ), "width", width );
mlt_properties_set_int( MLT_FRAME_PROPERTIES( this ), "height", height );
int channels = 2;
double fps = mlt_profile_fps( NULL );
int samples = mlt_sample_calculator( fps, frequency, mlt_frame_get_position( this ) );
-
+
// Get the pcm data
mlt_frame_get_audio( this, &pcm, &format, &frequency, &channels, &samples );
-
+
// Make an 8-bit buffer large enough to hold rendering
int size = w * h;
unsigned char *bitmap = ( unsigned char* )mlt_pool_alloc( size );
if ( bitmap != NULL )
memset( bitmap, 0, size );
mlt_properties_set_data( properties, "waveform", bitmap, size, ( mlt_destructor )mlt_pool_release, NULL );
-
+
// Render vertical lines
int16_t *ubound = pcm + samples * channels;
int skip = samples / w - 1;
int i, j, k;
-
+
// Iterate sample stream and along x coordinate
for ( i = 0; i < w && pcm < ubound; i++ )
{
{
// Determine sample's magnitude from 2s complement;
int pcm_magnitude = *pcm < 0 ? ~(*pcm) + 1 : *pcm;
- // The height of a line is the ratio of the magnitude multiplied by
+ // The height of a line is the ratio of the magnitude multiplied by
// half the vertical resolution
int height = ( int )( ( double )( pcm_magnitude ) / 32768 * h / 2 );
// Determine the starting y coordinate - left channel above center,
int displacement = ( h / 2 ) - ( 1 - j ) * height;
// Position buffer pointer using y coordinate, stride, and x coordinate
unsigned char *p = &bitmap[ i + displacement * w ];
-
+
// Draw vertical line
for ( k = 0; k < height; k++ )
p[ w * k ] = 0xFF;
-
+
pcm++;
}
pcm += skip * channels;
int yy, uu, vv;
int r,g,b;
total /= 2;
- while (total--)
+ while (total--)
{
yy = yuv[0];
uu = yuv[1];
{
// Start at the beginning of the line
out_ptr = out_line;
-
+
// Pointer to the middle of the input line
in_line = in_middle + ( dy >> 16 ) * istride;
double B = exp(-2.0 * M_PI * Fc);
double A = 1.0 - B;
double v;
-
+
for ( i = 0; i < *samples; i++ )
{
for ( j = 0; j < *channels; j++ )
/**
* \file mlt_frame.h
* \brief interface for all frame classes
+ * \see mlt_frame_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_multitrack.c
* \brief multitrack service class
+ * \see mlt_multitrack_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_multitrack.h
* \brief multitrack service class
+ * \see mlt_multitrack_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
#include "mlt_producer.h"
-/** \brief Track class
+/** \brief Track class used by mlt_multitrack_s
*/
struct mlt_track_s
/**
* \file mlt_parser.c
* \brief service parsing functionality
+ * \see mlt_parser_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_parser.h
* \brief service parsing functionality
+ * \see mlt_parser_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_playlist.c
* \brief playlist service class
+ * \see mlt_playlist_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
#include <stdlib.h>
#include <string.h>
-/** \brief virtual playlist entry
+/** \brief Virtual playlist entry used by mlt_playlist_s
*/
struct playlist_entry_s
/**
* \file mlt_playlist.h
* \brief playlist service class
+ * \see mlt_playlist_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
#include "mlt_producer.h"
-/** \brief structure for returning clip information
+/** \brief structure for returning clip information from a playlist entry
*/
typedef struct
/**
* \file mlt_pool.c
* \brief memory pooling functionality
+ * \see mlt_pool_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
#include <malloc.h>
#endif
-/** Singleton repositories
-*/
+/** global singleton for tracking pools */
static mlt_properties pools = NULL;
typedef struct mlt_pool_s
{
- pthread_mutex_t lock;
- mlt_deque stack;
- int size;
- int count;
+ pthread_mutex_t lock; ///< lock to prevent race conditions
+ mlt_deque stack; ///< a stack of addresses to memory blocks
+ int size; ///< the size of the memory block as a power of 2
+ int count; ///< the number of blocks in the pool
}
*mlt_pool;
*mlt_release;
/** Create a pool.
-*/
+ *
+ * \private \memberof mlt_pool_s
+ * \param size the size of the memory blocks to hold as some power of two
+ * \return a new pool object
+ */
static mlt_pool pool_init( int size )
{
}
/** Get an item from the pool.
-*/
+ *
+ * \private \memberof mlt_pool_s
+ * \param this a pool
+ * \return an opaque pointer
+ */
static void *pool_fetch( mlt_pool this )
{
}
/** Return an item to the pool.
-*/
+ *
+ * \private \memberof mlt_pool_s
+ * \param ptr an opaque pointer
+ */
static void pool_return( void *ptr )
{
}
/** Destroy a pool.
-*/
+ *
+ * \private \memberof mlt_pool_s
+ * \param this a pool
+ */
static void pool_close( mlt_pool this )
{
}
}
-/** Initialise the pool.
-*/
+/** Initialise the global pool.
+ *
+ * \public \memberof mlt_pool_s
+ */
void mlt_pool_init( )
{
}
/** Allocate size bytes from the pool.
-*/
+ *
+ * \public \memberof mlt_pool_s
+ * \param size the number of bytes
+ */
void *mlt_pool_alloc( int size )
{
}
/** Allocate size bytes from the pool.
-*/
+ *
+ * \public \memberof mlt_pool_s
+ * \param ptr an opaque pointer - can be in the pool or a new block to allocate
+ * \param size the number of bytes
+ */
void *mlt_pool_realloc( void *ptr, int size )
{
}
/** Purge unused items in the pool.
-*/
+ *
+ * A form of garbage collection.
+ * \public \memberof mlt_pool_s
+ */
void mlt_pool_purge( )
{
}
/** Release the allocated memory.
-*/
+ *
+ * \public \memberof mlt_pool_s
+ * \param release an opaque pointer of a block in the pool
+ */
void mlt_pool_release( void *release )
{
}
/** Close the pool.
-*/
+ *
+ * \public \memberof mlt_pool_s
+ */
void mlt_pool_close( )
{
/**
* \file mlt_pool.h
* \brief memory pooling functionality
+ * \see mlt_pool_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_producer.c
* \brief abstraction for all producer services
+ * \see mlt_producer_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_producer.h
* \brief abstraction for all producer services
+ * \see mlt_producer_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_profile.c
* \brief video output definition
+ * \see mlt_profile_s
*
- * Copyright (C) 2007-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2007-2009 Ushodaya Enterprises Limited
* \author Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
#include <string.h>
#include <libgen.h>
+
+/** the default subdirectory of the prefix for holding profiles */
#define PROFILES_DIR "/share/mlt/profiles/"
-/** Load a profile from the system folder
-*/
+/** Load a profile from the system folder.
+ *
+ * The environment variable MLT_PROFILES_PATH overrides the default \p PROFILES_DIR.
+ *
+ * \private \memberof mlt_profile_s
+ * \param name the name of a profile settings file located in the standard location or
+ * the full path name to a profile settings file
+ * \return a profile or NULL on error
+ */
static mlt_profile mlt_profile_select( const char *name )
{
}
/** Construct a profile.
-*/
+ *
+ * This will never return NULL as it uses the dv_pal settings as hard-coded fallback default.
+ *
+ * \public \memberof mlt_profile_s
+ * @param name the name of a profile settings file located in the standard location or
+ * the full path name to a profile settings file
+ * @return a profile
+ */
mlt_profile mlt_profile_init( const char *name )
{
return profile;
}
-/** Load a profile from specific file
-*/
+/** Load a profile from specific file.
+ *
+ * \public \memberof mlt_profile_s
+ * @param file the full path name to a properties file
+ * @return a profile or NULL on error
+ */
mlt_profile mlt_profile_load_file( const char *file )
{
return profile;
}
-/** Load a profile from a properties object
-*/
+/** Load a profile from a properties object.
+ *
+ * \public \memberof mlt_profile_s
+ * @param properties a properties list
+ * @return a profile or NULL if out of memory
+ */
mlt_profile mlt_profile_load_properties( mlt_properties properties )
{
return profile;
}
-/** Load an anonymous profile from string
-*/
+/** Load an anonymous profile from string.
+ *
+ * \public \memberof mlt_profile_s
+ * @param string a newline-delimited list of properties as name=value pairs
+ * @return a profile or NULL if out of memory
+ */
mlt_profile mlt_profile_load_string( const char *string )
{
return mlt_profile_load_properties( properties );
}
-/** Get the framerate as float
-*/
+/** Get the video frame rate as a floating point value.
+ *
+ * \public \memberof mlt_profile_s
+ * @param aprofile a profile
+ * @return the frame rate
+ */
double mlt_profile_fps( mlt_profile aprofile )
{
return 0;
}
-/** Get the sample aspect ratio as float
-*/
+/** Get the sample aspect ratio as a floating point value.
+ *
+ * \public \memberof mlt_profile_s
+ * @param aprofile a profile
+ * @return the pixel aspect ratio
+ */
double mlt_profile_sar( mlt_profile aprofile )
{
return 0;
}
-/** Get the display aspect ratio as float
-*/
+/** Get the display aspect ratio as floating point value.
+ *
+ * \public \memberof mlt_profile_s
+ * @param aprofile a profile
+ * @return the image aspect ratio
+ */
double mlt_profile_dar( mlt_profile aprofile )
{
return 0;
}
-/** Free up the global profile resources
-*/
+/** Free up the global profile resources.
+ *
+ * \public \memberof mlt_profile_s
+ * @param profile a profile
+ */
void mlt_profile_close( mlt_profile profile )
{
/**
* \file mlt_profile.h
* \brief video output definition
+ * \see mlt_profile_s
*
- * Copyright (C) 2007-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2007-2009 Ushodaya Enterprises Limited
* \author Dan Dennedy <dan@dennedy.org>
*
* This library is free software; you can redistribute it and/or
struct mlt_profile_s
{
- char* description;
- int frame_rate_num;
- int frame_rate_den;
- int width;
- int height;
- int progressive;
- int sample_aspect_num;
- int sample_aspect_den;
- int display_aspect_num;
- int display_aspect_den;
+ char* description; /**< a brief description suitable as a label in UI menu */
+ int frame_rate_num; /**< the numerator of the video frame rate */
+ int frame_rate_den; /**< the denominator of the video frame rate */
+ int width; /**< the horizontal resolution of the video */
+ int height; /**< the vertical resolution of the video */
+ int progressive; /**< a flag to indicate if the video is progressive scan, interlace if not set */
+ int sample_aspect_num; /**< the numerator of the pixel aspect ratio */
+ int sample_aspect_den; /**< the denominator of the pixel aspect ratio */
+ int display_aspect_num; /**< the numerator of the image aspect ratio in case it can not be simply derived (e.g. ITU-R 601) */
+ int display_aspect_den; /**< the denominator of the image aspect ratio in case it can not be simply derived (e.g. ITU-R 601) */
};
extern mlt_profile mlt_profile_init( const char *name );
/**
* \file mlt_properties.c
* \brief Properties class definition
+ * \see mlt_properties_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
* \author Dan Dennedy <dan@dennedy.org>
*
/** How many bytes to grow at a time */
#define STRBUF_GROWTH (1024)
-/** \brief Self-growing buffer for building strings
+/** \brief Private to mlt_properties_s, a self-growing buffer for building strings
* \private
*/
/**
* \file mlt_properties.h
* \brief Properties class declaration
+ * \see mlt_properties_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
* \author Dan Dennedy <dan@dennedy.org>
*
/**
* \file mlt_property.c
* \brief Property class definition
+ * \see mlt_property_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_property.h
* \brief Property class declaration
+ * \see mlt_property_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_repository.c
* \brief provides a map between service and shared objects
+ * \see mlt_repository_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
- * Dan Dennedy <dan@dennedy.org>
+ * \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 <string.h>
/** \brief Repository class
+ *
+ * The Repository is a collection of plugin modules and their services and service metadata.
*
* \extends mlt_properties_s
+ * \properties \p language a cached list of user locales
*/
struct mlt_repository_s
{
- struct mlt_properties_s parent; // a list of object files
- mlt_properties consumers; // lists of entry points
- mlt_properties filters;
- mlt_properties producers;
- mlt_properties transitions;
+ struct mlt_properties_s parent; /// a list of object files
+ mlt_properties consumers; /// a list of entry points for consumers
+ mlt_properties filters; /// a list of entry points for filters
+ mlt_properties producers; /// a list of entry points for producers
+ mlt_properties transitions; /// a list of entry points for transitions
};
-/** Construct a new repository
-*/
+/** Construct a new repository.
+ *
+ * \public \memberof mlt_repository_s
+ * \param directory the full path of a directory from which to read modules
+ * \return a new repository or NULL if failed
+ */
mlt_repository mlt_repository_init( const char *directory )
{
return this;
}
+/** Create a properties list for a service holding a function pointer to its constructor function.
+ *
+ * \private \memberof mlt_repository_s
+ * \param symbol a pointer to a function that can create the service.
+ * \return a properties list
+ */
+
static mlt_properties new_service( void *symbol )
{
mlt_properties properties = mlt_properties_new();
return properties;
}
-/** Register a service with the repository
- Typically, this is invoked by a module within its mlt_register().
-*/
+/** Register a service with the repository.
+ *
+ * Typically, this is invoked by a module within its mlt_register().
+ *
+ * \public \memberof mlt_repository_s
+ * \param this a repository
+ * \param service_type a service class
+ * \param service the name of a service
+ * \param symbol a pointer to a function to create the service
+ */
void mlt_repository_register( mlt_repository this, mlt_service_type service_type, const char *service, mlt_register_callback symbol )
{
}
}
+/** Get the repository properties for particular service class.
+ *
+ * \private \memberof mlt_repository_s
+ * \param this a repository
+ * \param type a service class
+ * \param service the name of a service
+ * \return a properties list or NULL if error
+ */
+
static mlt_properties get_service_properties( mlt_repository this, mlt_service_type type, const char *service )
{
mlt_properties service_properties = NULL;
return service_properties;
}
-/** Construct a new instance of a service
-*/
+/** Construct a new instance of a service.
+ *
+ * \public \memberof mlt_repository_s
+ * \param this a repository
+ * \param profile a \p mlt_profile to give the service
+ * \param type a service class
+ * \param service the name of the service
+ * \param input an optional argument to the service constructor
+ */
void *mlt_repository_create( mlt_repository this, mlt_profile profile, mlt_service_type type, const char *service, void *input )
{
return NULL;
}
-/** Destroy a repository
-*/
+/** Destroy a repository and free its resources.
+ *
+ * \public \memberof mlt_repository_s
+ * \param this a repository
+ */
void mlt_repository_close( mlt_repository this )
{
free( this );
}
-/** Get the list of registered consumers
-*/
+/** Get the list of registered consumers.
+ *
+ * \public \memberof mlt_repository_s
+ * \param self a repository
+ * \return a properties list containing all of the consumers
+ */
mlt_properties mlt_repository_consumers( mlt_repository self )
{
return self->consumers;
}
-/** Get the list of registered filters
-*/
+/** Get the list of registered filters.
+ *
+ * \public \memberof mlt_repository_s
+ * \param self a repository
+ * \return a properties list of all of the filters
+ */
mlt_properties mlt_repository_filters( mlt_repository self )
{
return self->filters;
}
-/** Get the list of registered producers
-*/
+/** Get the list of registered producers.
+ *
+ * \public \memberof mlt_repository_s
+ * \param self a repository
+ * \return a properties list of all of the producers
+ */
mlt_properties mlt_repository_producers( mlt_repository self )
{
return self->producers;
}
-/** Get the list of registered transitions
-*/
+/** Get the list of registered transitions.
+ *
+ * \public \memberof mlt_repository_s
+ * \param self a repository
+ * \return a properties list of all of the transitions
+ */
mlt_properties mlt_repository_transitions( mlt_repository self )
{
return self->transitions;
}
-/** Register the metadata for a service
- IMPORTANT: mlt_repository will take responsibility for deallocating the metadata properties that you supply!
-*/
+/** Register the metadata for a service.
+ *
+ * IMPORTANT: mlt_repository will take responsibility for deallocating the metadata properties
+ * that you supply!
+ *
+ * \public \memberof mlt_repository_s
+ * \param self a repository
+ * \param type a service class
+ * \param service the name of a service
+ * \param callback the pointer to a function that can supply metadata
+ * \param callback_data an opaque user data pointer to be supplied on the callback
+ */
+
void mlt_repository_register_metadata( mlt_repository self, mlt_service_type type, const char *service, mlt_metadata_callback callback, void *callback_data )
{
mlt_properties service_properties = get_service_properties( self, type, service );
mlt_properties_set_data( service_properties, "metadata_cb_data", callback_data, 0, NULL, NULL );
}
-/** Get the metadata about a service
- Returns NULL if service or its metadata are unavailable.
-*/
+/** Get the metadata about a service.
+ *
+ * Returns NULL if service or its metadata are unavailable.
+ *
+ * \public \memberof mlt_repository_s
+ * \param self a repository
+ * \param type a service class
+ * \param service the name of a service
+ * \return the service metadata as a structured properties list
+ */
mlt_properties mlt_repository_metadata( mlt_repository self, mlt_service_type type, const char *service )
{
return metadata;
}
+/** Try to determine the locale from some commonly used environment variables.
+ *
+ * \private \memberof mlt_repository_s
+ * \return a string containing the locale id or NULL if unknown
+ */
+
static char *getenv_locale()
{
char *s = getenv( "LANGUAGE" );
}
/** Return a list of user-preferred language codes taken from environment variables.
-*/
+ *
+ * A module should use this to locate a localized YAML Tiny file from which to build
+ * its metadata strucutured properties.
+ *
+ * \public \memberof mlt_repository_s
+ * \param self a repository
+ * \return a properties list that is a list (not a map) of locales, defaults to "en" if not
+ * overridden by environment variables, in order: LANGUAGE, LC_ALL, LC_MESSAGES, LANG
+ */
mlt_properties mlt_repository_languages( mlt_repository self )
{
/**
* \file mlt_repository.h
* \brief provides a map between service and shared objects
+ * \see mlt_repository_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
- * Dan Dennedy <dan@dennedy.org>
+ * \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"
#include "mlt_profile.h"
-/** Repository structure forward reference.
-*/
-
-typedef struct mlt_repository_s *mlt_repository;
-
/** This callback is the main entry point into a module, which must be exported
- with the symbol "mlt_register".
- Inside the callback, the module registers the additional callbacks below.
-*/
+ * with the symbol "mlt_register".
+ *
+ * Inside the callback, the module registers the additional callbacks below.
+ */
typedef void ( *mlt_repository_callback )( mlt_repository );
-/** These are callback functions that modules implement to construct services
- and metadata.
-*/
+/** The callback function that modules implement to construct a service.
+ */
+
typedef void *( *mlt_register_callback )( mlt_profile, mlt_service_type, const char * /* service name */, void * /* arg */ );
+
+/** The callback function that modules implement to supply metadata as a properties list.
+ */
+
typedef mlt_properties ( *mlt_metadata_callback )( mlt_service_type, const char * /* service name */, void * /* callback_data */ );
-/** These convenience macros can be used to register services in a more declarative manner.
-*/
+/** A convenience macro to create an entry point for service registration. */
#define MLT_REPOSITORY void mlt_register( mlt_repository repository )
+
+/** A convenience macro to a register service in a more declarative manner. */
#define MLT_REGISTER( type, service, symbol ) ( mlt_repository_register( repository, (type), (service), ( mlt_register_callback )(symbol) ) )
-#define MLT_REGISTER_METADATA( type, service, callback, data ) ( mlt_repository_register_metadata( repository, (type), (service), ( mlt_metadata_callback )(callback), (data) ) )
-/** Public functions.
-*/
+/** A convenience macro to a register metadata in a more declarative manner. */
+#define MLT_REGISTER_METADATA( type, service, callback, data ) ( mlt_repository_register_metadata( repository, (type), (service), ( mlt_metadata_callback )(callback), (data) ) )
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 );
/**
* \file mlt_service.c
* \brief interface definition for all service classes
+ * \see mlt_service_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_service.h
* \brief interface declaration for all service classes
+ * \see mlt_service_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_tokeniser.c
* \brief string tokeniser
+ * \see mlt_tokeniser_s
*
- * Copyright (C) 2002-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2002-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_tokeniser.h
* \brief string tokeniser
+ * \see mlt_tokeniser_s
*
- * Copyright (C) 2002-2003 Ushodaya Enterprises Limited
+ * Copyright (C) 2002-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_tractor.c
* \brief tractor service class
+ * \see mlt_tractor_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_tractor.h
* \brief tractor service class
+ * \see mlt_tractor_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_transition.c
* \brief abstraction for all transition services
+ * \see mlt_transition_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
/**
* \file mlt_transition.h
* \brief abstraction for all transition services
+ * \see mlt_transition_s
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
* \file mlt_types.h
* \brief Provides forward definitions of all public types
*
- * Copyright (C) 2003-2008 Ushodaya Enterprises Limited
+ * Copyright (C) 2003-2009 Ushodaya Enterprises Limited
* \author Charles Yates <charles.yates@pandora.be>
*
* This library is free software; you can redistribute it and/or
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 struct mlt_repository_s *mlt_repository; /**< pointer to Repository object */
typedef void ( *mlt_destructor )( void * ); /**< pointer to destructor function */
typedef char *( *mlt_serialiser )( void *, int length );/**< pointer to serialization function */
projects / mlt / commitdiff