From b7262377211f41d46ae40326a5203794c6cd826e Mon Sep 17 00:00:00 2001 From: Dan Dennedy Date: Thu, 30 May 2013 20:53:17 -0700 Subject: [PATCH] Document the property animation, rect, and color additions. --- src/framework/mlt_properties.c | 52 +++++++++-- src/framework/mlt_property.c | 162 +++++++++++++++++++++++++++++++-- src/framework/mlt_types.h | 8 +- 3 files changed, 203 insertions(+), 19 deletions(-) diff --git a/src/framework/mlt_properties.c b/src/framework/mlt_properties.c index 2f807ee2..7fddb599 100644 --- a/src/framework/mlt_properties.c +++ b/src/framework/mlt_properties.c @@ -2067,6 +2067,17 @@ char *mlt_properties_get_time( mlt_properties self, const char* name, mlt_time_f return NULL; } +/** Convert a numeric property to a tuple of color components. + * + * If the property's string is red, green, blue, white, or black, then it + * is converted to the corresponding opaque color tuple. Otherwise, the property + * is fetched as an integer and then converted. + * \public \memberof mlt_properties_s + * \param self a properties list + * \param name the property to get + * \return a color structure + */ + mlt_color mlt_properties_get_color( mlt_properties self, const char* name ) { mlt_profile profile = mlt_properties_get_data( self, "_profile", NULL ); @@ -2145,13 +2156,16 @@ int mlt_properties_set_color( mlt_properties self, const char *name, mlt_color c return error; } -/** Get a string value by name. +/** Get a string value by name at a frame position. * * Do not free the returned string. It's lifetime is controlled by the property * and this properties object. * \public \memberof mlt_properties_s * \param self a properties list * \param name the property to get + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that * \return the property's string value or NULL if it does not exist */ @@ -2164,7 +2178,7 @@ char* mlt_properties_anim_get( mlt_properties self, const char *name, int positi return value == NULL ? NULL : mlt_property_anim_get_string( value, fps, list->locale, position, length ); } -/** Set a property to a string. +/** Set a property to a string at a frame position. * * The event "property-changed" is fired after the property has been set. * @@ -2173,6 +2187,9 @@ char* mlt_properties_anim_get( mlt_properties self, const char *name, int positi * \param self a properties list * \param name the property to set * \param value the property's new value + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that * \return true if error */ @@ -2206,7 +2223,10 @@ int mlt_properties_anim_set( mlt_properties self, const char *name, const char * * \public \memberof mlt_properties_s * \param self a properties list * \param name the property to get - * \return The integer value, 0 if not found (which may also be a legitimate value) + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return the integer value, 0 if not found (which may also be a legitimate value) */ int mlt_properties_anim_get_int( mlt_properties self, const char *name, int position, int length ) @@ -2224,6 +2244,10 @@ int mlt_properties_anim_get_int( mlt_properties self, const char *name, int posi * \param self a properties list * \param name the property to set * \param value the integer + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \param keyframe_type the interpolation method for this keyframe * \return true if error */ @@ -2257,7 +2281,10 @@ int mlt_properties_anim_set_int( mlt_properties self, const char *name, int valu * \public \memberof mlt_properties_s * \param self a properties list * \param name the property to get - * \return The real number, 0 if not found (which may also be a legitimate value) + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return the real number, 0 if not found (which may also be a legitimate value) */ double mlt_properties_anim_get_double( mlt_properties self, const char *name, int position, int length ) @@ -2275,6 +2302,10 @@ double mlt_properties_anim_get_double( mlt_properties self, const char *name, in * \param self a properties list * \param name the property to set * \param value the real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \param keyframe_type the interpolation method for this keyframe * \return true if error */ @@ -2352,7 +2383,7 @@ extern int mlt_properties_set_rect( mlt_properties self, const char *name, mlt_r * \public \memberof mlt_properties_s * \param self a properties list * \param name the property to get - * \return The rectangle value, the rectangle fields will be DBL_MIN if not found + * \return the rectangle value, the rectangle fields will be DBL_MIN if not found */ extern mlt_rect mlt_properties_get_rect( mlt_properties self, const char* name ) @@ -2369,6 +2400,10 @@ extern mlt_rect mlt_properties_get_rect( mlt_properties self, const char* name ) * \param self a properties list * \param name the property to set * \param value the rectangle + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \param keyframe_type the interpolation method for this keyframe * \return true if error */ @@ -2397,12 +2432,15 @@ extern int mlt_properties_anim_set_rect( mlt_properties self, const char *name, return error; } -/** Get a rectangle associated to the name. +/** Get a rectangle associated to the name at a frame position. * * \public \memberof mlt_properties_s * \param self a properties list * \param name the property to get - * \return The rectangle value, the rectangle fields will be DBL_MIN if not found + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return the rectangle value, the rectangle fields will be DBL_MIN if not found */ extern mlt_rect mlt_properties_anim_get_rect( mlt_properties self, const char *name, int position, int length ) diff --git a/src/framework/mlt_property.c b/src/framework/mlt_property.c index 1f847b5a..69161dfd 100644 --- a/src/framework/mlt_property.c +++ b/src/framework/mlt_property.c @@ -948,6 +948,14 @@ char *mlt_property_get_time( mlt_property self, mlt_time_format format, double f return self->prop_string; } +/** Determine if the property holds a numeric or numeric string value. + * + * \private \memberof mlt_property_s + * \param self a property + * \param locale the locale to use for string evaluation + * \return true if it is numeric + */ + static int is_property_numeric( mlt_property self, locale_t locale ) { int result = ( self->types & mlt_prop_int ) || @@ -972,13 +980,23 @@ static int is_property_numeric( mlt_property self, locale_t locale ) return result; } +/** A linear interpolation function for animation. + * + * \private \memberof mlt_property_s + */ + static inline double linear_interpolate( double y1, double y2, double t ) { return y1 + ( y2 - y1 ) * t; } -// For non-closed curves, you need to also supply the tangent vector at the first and last control point. -// This is commonly done: T(P[0]) = P[1] - P[0] and T(P[n]) = P[n] - P[n-1]. +/** A smooth spline interpolation for animation. + * + * For non-closed curves, you need to also supply the tangent vector at the first and last control point. + * This is commonly done: T(P[0]) = P[1] - P[0] and T(P[n]) = P[n] - P[n-1]. + * \private \memberof mlt_property_s + */ + static inline double catmull_rom_interpolate( double y0, double y1, double y2, double y3, double t ) { double t2 = t * t; @@ -989,6 +1007,20 @@ static inline double catmull_rom_interpolate( double y0, double y1, double y2, d return a0 * t * t2 + a1 * t2 + a2 * t + a3; } +/** Interpolate a new property value given a set of other properties. + * + * \public \memberof mlt_property_s + * \param self the property onto which to set the computed value + * \param p an array of at least 1 value in p[1] if \p interp is discrete, + * 2 values in p[1] and p[2] if \p interp is linear, or + * 4 values in p[0] - p[3] if \p interp is smooth + * \param progress a ratio in the range [0, 1] to indicate how far between p[1] and p[2] + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param interp the interpolation method to use + * \return true if there was an error + */ + int mlt_property_interpolate( mlt_property self, mlt_property p[], double progress, double fps, locale_t locale, mlt_keyframe_type interp ) { @@ -1070,6 +1102,16 @@ int mlt_property_interpolate( mlt_property self, mlt_property p[], return error; } +/** Create a new animation or refresh an existing one. + * + * \private \memberof mlt_property_s + * \param self a property + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + */ + static void refresh_animation( mlt_property self, double fps, locale_t locale, int length ) { if ( !self->animation ) @@ -1093,6 +1135,18 @@ static void refresh_animation( mlt_property self, double fps, locale_t locale, i } } +/** Get the real number at a frame position. + * + * \public \memberof mlt_property_s + * \param self a property + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return the real number + */ + double mlt_property_anim_get_double( mlt_property self, double fps, locale_t locale, int position, int length ) { double result; @@ -1114,6 +1168,18 @@ double mlt_property_anim_get_double( mlt_property self, double fps, locale_t loc return result; } +/** Get the property as an integer number at a frame position. + * + * \public \memberof mlt_property_s + * \param self a property + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return an integer value + */ + int mlt_property_anim_get_int( mlt_property self, double fps, locale_t locale, int position, int length ) { int result; @@ -1135,6 +1201,18 @@ int mlt_property_anim_get_int( mlt_property self, double fps, locale_t locale, i return result; } +/** Get the string at certain a frame position. + * + * \public \memberof mlt_property_s + * \param self a property + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return the string representation of the property or NULL if failed + */ + char* mlt_property_anim_get_string( mlt_property self, double fps, locale_t locale, int position, int length ) { char *result; @@ -1171,6 +1249,12 @@ char* mlt_property_anim_get_string( mlt_property self, double fps, locale_t loca * \public \memberof mlt_property_s * \param self a property * \param value a double precision floating point value + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \param keyframe_type the interpolation method for this keyframe * \return false if successful, true to indicate error */ @@ -1197,7 +1281,13 @@ int mlt_property_anim_set_double( mlt_property self, double value, double fps, l * * \public \memberof mlt_property_s * \param self a property - * \param value a double precision floating point value + * \param value an integer + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \param keyframe_type the interpolation method for this keyframe * \return false if successful, true to indicate error */ @@ -1220,6 +1310,22 @@ int mlt_property_anim_set_int( mlt_property self, int value, double fps, locale_ return result; } +/** Set a property animation keyframe to a string. + * + * Strings only support discrete animation. Do not use this to set a property's + * animation string that contains a semicolon-delimited set of values; use + * mlt_property_set() for that. + * \public \memberof mlt_property_s + * \param self a property + * \param value a string + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return false if successful, true to indicate error + */ + int mlt_property_anim_set_string( mlt_property self, const char *value, double fps, locale_t locale, int position, int length ) { int result; @@ -1238,11 +1344,31 @@ int mlt_property_anim_set_string( mlt_property self, const char *value, double f return result; } +/** Get an object's animation object. + * + * You might need to call another mlt_property_anim_ function to actually construct + * the animation, as this is a simple accessor function. + * \public \memberof mlt_property_s + * \param self a property + * \return the animation object or NULL if there is no animation + */ + mlt_animation mlt_property_get_animation( mlt_property self ) { - return self->animation; + return self->animation; } +/** Convert a rectangle value into a string. + * + * Unlike the deprecated mlt_geometry API, the canonical form of a mlt_rect + * is a space delimited "x y w h o" even though many kinds of field delimiters + * may be used to convert a string to a rectangle. + * \private \memberof mlt_property_s + * \param rect the rectangle to convert + * \param length not used + * \return the string representation of a rectangle + */ + static char* serialise_mlt_rect( mlt_rect *rect, int length ) { char* result = calloc( 1, 100 ); @@ -1263,7 +1389,7 @@ static char* serialise_mlt_rect( mlt_rect *rect, int length ) * * \public \memberof mlt_property_s * \param self a property - * \param value a mlt_rect + * \param value a rectangle * \return false */ @@ -1281,12 +1407,14 @@ int mlt_property_set_rect( mlt_property self, mlt_rect value ) return 0; } -/** Get the property as a floating point. +/** Get the property as a rectangle. * + * You can use any non-numeric character(s) as a field delimiter. + * If the number has a '%' immediately following it, the number is divided by + * 100 to convert it into a real number. * \public \memberof mlt_property_s * \param self a property - * \param fps frames per second, used when converting from time value - * \param locale the locale to use for this conversion + * \param locale the locale to use for when converting from a string * \return a rectangle value */ @@ -1348,6 +1476,12 @@ mlt_rect mlt_property_get_rect( mlt_property self, locale_t locale ) * \public \memberof mlt_property_s * \param self a property * \param value a rectangle + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \param keyframe_type the interpolation method for this keyframe * \return false if successful, true to indicate error */ @@ -1370,6 +1504,18 @@ int mlt_property_anim_set_rect( mlt_property self, mlt_rect value, double fps, l return result; } +/** Get a rectangle at a frame position. + * + * \public \memberof mlt_property_s + * \param self a property + * \param fps the frame rate, which may be needed for converting a time string to frame units + * \param locale the locale, which may be needed for converting a string to a real number + * \param position the frame number + * \param length the maximum number of frames when interpreting negative keyframe times, + * <=0 if you don't care or need that + * \return the rectangle + */ + mlt_rect mlt_property_anim_get_rect( mlt_property self, double fps, locale_t locale, int position, int length ) { mlt_rect result; diff --git a/src/framework/mlt_types.h b/src/framework/mlt_types.h index b25b2b96..bb9e2c65 100644 --- a/src/framework/mlt_types.h +++ b/src/framework/mlt_types.h @@ -133,10 +133,10 @@ typedef struct { mlt_rect; typedef struct { - uint8_t r; - uint8_t g; - uint8_t b; - uint8_t a; + uint8_t r; /**< red */ + uint8_t g; /**< green */ + uint8_t b; /**< blue */ + uint8_t a; /**< alpha */ } mlt_color; -- 2.39.2