Document the property animation, rect, and color additions.

diff --git a/src/framework/mlt_properties.c b/src/framework/mlt_properties.c
index 2f807ee2d9bac02ceed670f7e6d54ba3d6ab349b..7fddb5990edac9d2079f11f9b7a378419d2a41e9 100644 (file)
--- 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 1f847b5af381f0634568d8a969e84b5e1ef5ce01..69161dfd66eb0c21db8b5aeb90e5aa1d48b68120 100644 (file)
--- 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 b25b2b96e43122d40a45d7723d75ff8501d27df5..bb9e2c654d25ff23320f4607729ec1f717ed29ea 100644 (file)
--- 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;