mlt_animation_s Struct Reference

Property Animation class. More...

Public Member Functions
void	mlt_animation_close (mlt_animation self)
	Close the animation and deallocate all of its resources. More...
int	mlt_animation_get_item (mlt_animation self, mlt_animation_item item, int position)
	Load an animation item for an absolute position. More...
int	mlt_animation_get_length (mlt_animation self)
	Get the length of the animation. More...
const char *	mlt_animation_get_string (mlt_animation self)
	Get the cached serialization string. More...
int	mlt_animation_insert (mlt_animation self, mlt_animation_item item)
	Insert an animation item. More...
void	mlt_animation_interpolate (mlt_animation self)
	Re-interpolate non-keyframe nodes after a series of insertions or removals. More...
int	mlt_animation_key_count (mlt_animation self)
	Get the number of keyframes. More...
int	mlt_animation_key_get (mlt_animation self, mlt_animation_item item, int index)
	Get an animation item for the N-th keyframe. More...
int	mlt_animation_key_set_frame (mlt_animation self, int index, int frame)
	Change the frame number for the N-th keyframe. More...
int	mlt_animation_key_set_type (mlt_animation self, int index, mlt_keyframe_type type)
	Change the interpolation for the N-th keyframe. More...
mlt_animation	mlt_animation_new ()
	Create a new animation object. More...
int	mlt_animation_next_key (mlt_animation self, mlt_animation_item item, int position)
	Get the keyfame at the position or the next following. More...
int	mlt_animation_parse (mlt_animation self, const char *data, int length, double fps, mlt_locale_t locale)
	Parse a string representing an animation. More...
int	mlt_animation_parse_item (mlt_animation self, mlt_animation_item item, const char *value)
	Parse a string representing an animation keyframe=value. More...
int	mlt_animation_prev_key (mlt_animation self, mlt_animation_item item, int position)
	Get the keyfame at the position or the next preceding. More...
int	mlt_animation_refresh (mlt_animation self, const char *data, int length)
	Conditionally refresh the animation if it is modified. More...
int	mlt_animation_remove (mlt_animation self, int position)
	Remove the keyframe at the specified position. More...
char *	mlt_animation_serialize (mlt_animation self)
	Serialize the animation. More...
char *	mlt_animation_serialize_cut (mlt_animation self, int in, int out)
	Serialize a cut of the animation. More...
char *	mlt_animation_serialize_cut_tf (mlt_animation self, int in, int out, mlt_time_format time_format)
	Serialize a cut of the animation (with time format). More...
char *	mlt_animation_serialize_tf (mlt_animation self, mlt_time_format time_format)
	Serialize the animation (with time format). More...
void	mlt_animation_set_length (mlt_animation self, int length)
	Set the length of the animation. More...
void	mlt_animation_shift_frames (mlt_animation self, int shift)
	Shift the frame value for all nodes. More...

Data Fields
char *	data
	the string representing the animation More...
double	fps
	framerate to use when converting time clock strings to frame units More...
int	length
	the maximum number of frames to use when interpreting negative keyframe positions More...
mlt_locale_t	locale
	pointer to a locale to use when converting strings to numeric values More...
animation_node	nodes
	a linked list of keyframes (and possibly non-keyframe values) More...

Private Member Functions
static double	catmull_rom_interpolate (double x0, double y0, double x1, double y1, double x2, double y2, double x3, double y3, double t, double alpha, double tension)
	A Catmull–Rom interpolation function. More...
static double	distance (double x0, double y0, double x1, double y1)
	Calculate the distance between two points. More...
static int	interpolate_item (mlt_animation_item item, mlt_animation_item p[], double fps, mlt_locale_t locale)
	Interpolate a new animation item given a set of other items. More...
static double	linear_interpolate (double y1, double y2, double t)
	A linear interpolation function. More...
static void	mlt_animation_clean (mlt_animation self)
	Reset an animation and free all strings and properties. More...
void	mlt_animation_clear_string (mlt_animation self)
	Clear the cached serialization string. More...
static int	mlt_animation_drop (mlt_animation self, animation_node node)
	Remove a node from the linked list. More...

Detailed Description

Property Animation class.

This is the animation engine for a Property object. It is dependent upon the mlt_property API and used by the various mlt_property_anim_* functions.

Member Function Documentation

catmull_rom_interpolate()

static double catmull_rom_interpolate ( double  x0, double  y0, double  x1, double  y1, double  x2, double  y2, double  x3, double  y3, double  t, double  alpha, double  tension  )

inlineprivate

A Catmull–Rom interpolation function.

As described here: https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline And further reduced here with tension added: https://qroph.github.io/2018/07/30/smooth-paths-using-catmull-rom-splines.html

This imlementation supports the alpha value which can be set to 0.5 to result in centripetal Catmull–Rom splines. Centripital Catmull–Rom splines are guaranteed to not have any cusps or loops. These are not desirable because they result in the value reversing direction when interpolation from one point to the next.

To use this function for animation item interpolation, provide 4 points: two points preceeding t and two points following t. Use the item frame number as the x and the item value as y for each point. t should represent the fractional progress between point 1 and point 2.

If fewer than 2 points are available, then duplicate the first and/or last points as necessary to meet the requirement for 4 points.

Parameters

alpha	0.0 for the uniform spline 0.5 for the centripetal spline (no cusps) 1.0 for the chordal spline.
tension	1.0 results in the most natural slope at x1,y1 and x2,y2 0.0 results in a horizontal tangent at x1,y1 and x2,y2 (slope of 0). -1.0 results in the most natural slope at x1,y1 and x2,y2 unless x1 or x2 represents a peak. In the case of peaks, a horizontal tangent will be used to avoid overshoot.

distance()

static double distance ( double  x0, double  y0, double  x1, double  y1  )

inlineprivate

Calculate the distance between two points.

interpolate_item()

static int interpolate_item ( mlt_animation_item  item, mlt_animation_item  p[], double  fps, mlt_locale_t  locale  )

private

Interpolate a new animation item given a set of other items.

Parameters

item	an unpopulated animation item to be interpolated. The frame and keyframe_type fields must already be set. The value for "frame" is the postion at which the value will be interpolated. The value for "keyframe_type" determines which interpolation will be used.
p	a sequential array of 4 animation items. The frame value for item must lie between the frame values for p[1] and p[2].
fps	the frame rate, which may be needed for converting a time string to frame units
locale	the locale, which may be needed for converting a string to a real number

Returns

true if there was an error

linear_interpolate()

static double linear_interpolate ( double  y1, double  y2, double  t  )

inlineprivate

A linear interpolation function.

mlt_animation_clean()

static void mlt_animation_clean ( mlt_animation  self )

private

Reset an animation and free all strings and properties.

Parameters

self	an animation

mlt_animation_clear_string()

void mlt_animation_clear_string ( mlt_animation  self )

private

Clear the cached serialization string.

Parameters

self	an animation

mlt_animation_close()

void mlt_animation_close

(

mlt_animation

self

)

Close the animation and deallocate all of its resources.

Parameters

self	the animation to destroy

mlt_animation_drop()

static int mlt_animation_drop ( mlt_animation  self, animation_node  node  )

private

Remove a node from the linked list.

Parameters

self	an animation
node	the node to remove

Returns

false

mlt_animation_get_item()

int mlt_animation_get_item	(	mlt_animation	self,
		mlt_animation_item	item,
		int	position
	)

Load an animation item for an absolute position.

This performs interpolation if there is no keyframe at the position.

Parameters

self	an animation
item	an already allocated animation item that will be filled in
position	the frame number for the point in time

Returns

true if there was an error

mlt_animation_get_length()

int mlt_animation_get_length

(

mlt_animation

self

)

Get the length of the animation.

If the animation was initialized with a zero or negative value, then this gets the maximum frame number from animation's list of nodes.

Parameters

self	an animation

Returns

the number of frames

mlt_animation_get_string()

const char * mlt_animation_get_string

(

mlt_animation

self

)

Get the cached serialization string.

This can be used to determine if the animation has been modified because the string is cleared whenever the animation is changed.

Parameters

self	an animation

Returns

the cached serialization string

mlt_animation_insert()

int mlt_animation_insert	(	mlt_animation	self,
		mlt_animation_item	item
	)

Insert an animation item.

Parameters

self	an animation
item	an animation item

Returns

true if there was an error

See also

mlt_animation_parse_item

mlt_animation_interpolate()

void mlt_animation_interpolate

(

mlt_animation

self

)

Re-interpolate non-keyframe nodes after a series of insertions or removals.

Parameters

self	an animation

mlt_animation_key_count()

int mlt_animation_key_count

(

mlt_animation

self

)

Get the number of keyframes.

Parameters

self	an animation

Returns

the number of keyframes or -1 on error

mlt_animation_key_get()

int mlt_animation_key_get	(	mlt_animation	self,
		mlt_animation_item	item,
		int	index
	)

Get an animation item for the N-th keyframe.

Parameters

self	an animation
item	an already allocated animation item that will be filled in
index	the N-th keyframe (0 based) in this animation

Returns

true if there was an error

mlt_animation_key_set_frame()

int mlt_animation_key_set_frame	(	mlt_animation	self,
		int	index,
		int	frame
	)

Change the frame number for the N-th keyframe.

Parameters

self	an animation
index	the N-th keyframe (0 based) in this animation
frame	the position of this keyframe in frame units

Returns

true if there was an error

mlt_animation_key_set_type()

int mlt_animation_key_set_type	(	mlt_animation	self,
		int	index,
		mlt_keyframe_type	type
	)

Change the interpolation for the N-th keyframe.

Parameters

self	an animation
index	the N-th keyframe (0 based) in this animation
type	the method of interpolation for this key frame

Returns

true if there was an error

mlt_animation_new()

mlt_animation mlt_animation_new

(

)

Create a new animation object.

Returns

an animation object

mlt_animation_next_key()

int mlt_animation_next_key	(	mlt_animation	self,
		mlt_animation_item	item,
		int	position
	)

Get the keyfame at the position or the next following.

Parameters

self	an animation
item	an already allocated animation item which will be updated
position	the frame number at which to start looking for the next animation node

Returns

true if there was an error

mlt_animation_parse()

int mlt_animation_parse	(	mlt_animation	self,
		const char *	data,
		int	length,
		double	fps,
		mlt_locale_t	locale
	)

Parse a string representing an animation.

A semicolon is the delimiter between keyframe=value items in the string.

Parameters

self	an animation
data	the string representing an animation
length	the maximum number of frames when interpreting negative keyframe times, <=0 if you don't care or need that
fps	the framerate to use when evaluating time strings
locale	the locale to use when converting strings to numbers

Returns

true if there was an error

mlt_animation_parse_item()

int mlt_animation_parse_item	(	mlt_animation	self,
		mlt_animation_item	item,
		const char *	value
	)

Parse a string representing an animation keyframe=value.

This function does not affect the animation itself! But it will use some state of the animation for the parsing (e.g. fps, locale). It parses into a mlt_animation_item that you provide. item->frame should be specified if the string does not have an equal sign and time field. If an exclamation point (!) or vertical bar (|) character precedes the equal sign, then the keyframe interpolation is set to discrete. If a tilde (~) precedes the equal sign, then the keyframe interpolation is set to smooth (spline).

Parameters

self	an animation
item	an already allocated animation item
value	the string representing an animation

Returns

true if there was an error

mlt_animation_prev_key()

int mlt_animation_prev_key	(	mlt_animation	self,
		mlt_animation_item	item,
		int	position
	)

Get the keyfame at the position or the next preceding.

Parameters

self	an animation
item	an already allocated animation item which will be updated
position	the frame number at which to start looking for the previous animation node

Returns

true if there was an error

mlt_animation_refresh()

int mlt_animation_refresh	(	mlt_animation	self,
		const char *	data,
		int	length
	)

Conditionally refresh the animation if it is modified.

Parameters

self	an animation
data	the string representing an animation
length	the maximum number of frames when interpreting negative keyframe times, <=0 if you don't care or need that

Returns

true if there was an error

mlt_animation_remove()

int mlt_animation_remove	(	mlt_animation	self,
		int	position
	)

Remove the keyframe at the specified position.

Parameters

self	an animation
position	the frame number of the animation node to remove

Returns

true if there was an error

mlt_animation_serialize()

char * mlt_animation_serialize

(

mlt_animation

self

)

Serialize the animation.

This version outputs the key frames' position as a frame number. The caller is responsible for free-ing the returned string.

Parameters

self	an animation

Returns

a string representing the animation

mlt_animation_serialize_cut()

char * mlt_animation_serialize_cut	(	mlt_animation	self,
		int	in,
		int	out
	)

Serialize a cut of the animation.

This version outputs the key frames' position as a frame number. The caller is responsible for free-ing the returned string.

Parameters

self	an animation
in	the frame at which to start serializing animation nodes
out	the frame at which to stop serializing nodes

Returns

a string representing the animation

mlt_animation_serialize_cut_tf()

char * mlt_animation_serialize_cut_tf	(	mlt_animation	self,
		int	in,
		int	out,
		mlt_time_format	time_format
	)

Serialize a cut of the animation (with time format).

The caller is responsible for free-ing the returned string.

Parameters

self	an animation
in	the frame at which to start serializing animation nodes
out	the frame at which to stop serializing nodes
time_format	the time format to use for the key frames

Returns

a string representing the animation

mlt_animation_serialize_tf()

char * mlt_animation_serialize_tf	(	mlt_animation	self,
		mlt_time_format	time_format
	)

Serialize the animation (with time format).

The caller is responsible for free-ing the returned string.

Parameters

self	an animation
time_format	the time format to use for the key frames

Returns

a string representing the animation

mlt_animation_set_length()

void mlt_animation_set_length	(	mlt_animation	self,
		int	length
	)

Set the length of the animation.

The length is used for interpreting negative keyframe positions as relative to the length. It is also used when serializing an animation as a string.

Parameters

self	an animation
length	the length of the animation in frame units

mlt_animation_shift_frames()

void mlt_animation_shift_frames	(	mlt_animation	self,
		int	shift
	)

Shift the frame value for all nodes.

Parameters

self	an animation
shift	the value to add to all frame values

Field Documentation

data

char* mlt_animation_s::data

the string representing the animation

fps

double mlt_animation_s::fps

framerate to use when converting time clock strings to frame units

length

int mlt_animation_s::length

the maximum number of frames to use when interpreting negative keyframe positions

locale

mlt_locale_t mlt_animation_s::locale

pointer to a locale to use when converting strings to numeric values

nodes

animation_node mlt_animation_s::nodes

a linked list of keyframes (and possibly non-keyframe values)

---

The documentation for this struct was generated from the following file:

• mlt_animation.c