Parameter.AddFCurve

Parameter Type Description

Type siFCurveType The type of the FCurve.
Default Value: defined by parameter type

Interpolation siFCurveInterpolation The interpolation of the FCurve
Default Value: defined by parameter type

Extrapolation siFCurveExtrapolation The extrapolation of the FCurve
Default Value: defined by parameter type

KeyDataArray Variant The structure of the array is defined by the previous parameters and the number keys. The array must be either 1-dimensional or 2-dimensional. For 2-dimensional arrays, the first dimension defines the values for each key; the second defines the number of keys.

It is necessary to explicitly define the tangency for standard fcurves that use the default key interpolation or specify cubic interpolation. For standard fcurves using constant and linear key interpolation, 2 values are defined for each key: the key time in frames, and the key value at that frame.

To specify the tangency there must be 6 values defined for each key in the following order: the key time in frames, the key value at that frame, the left tangent time in frames relative to the key time (must be a negative value), the left tangent value relative to key value, the right tangent time in frames relative to key time (must be a positive value), and the right tangent value relative to key value.

In order to allow tangents to be set exactly as specified the auto tangent constraint is turned off. This may lead to an invalid curve depending on the tangent values but allows the tangents to be set as specified. If empty values are specified for tangency values the default tangents are calculated.

You can specify tangents for fcurves using constant or linear key interpolation although this is optional and is only used if the key interpolation is changed to cubic.

The curve handles must never extend past the value of the neighboring key frames. When the tangency is explicitly defined, the tangent values must reflect this fact. Passing "Empty" for the tangents in the case of the cubic fcurves, and not having to specify them in the case of linear and constant fcurves, ensures that the tangents for the correct handles are automatically calculated. The left and right tangents of a fcurve can be set to any real value; however, in order to preserve the functional characteristic of the curve, these tangents are subject to change. The values are automatically changed and a different fcurve is drawn if the original chosen values do not generate a curve that is also a valid function on the x and y axes. By definition an fcurve is a function, and therefore must have the property that for every value of x there exists a unique y value. Visually, this means that any vertical line drawn along the domain of x can only pass through the curve once. A minimal rule to guarantee that this functional property holds for a curve is to ensure that the right tangent of a given key is less than or equal to the left tangent of the successive key. It is possible that the right tangent can be moved past this point and the fcurve is still valid, but anything past this point and the tangent values are subject to change. Furthermore, to ensure the functionality of an fcurve, the right tangent of a given key must always be greater than or equal to the value of the key itself and the left tangent must be less than or equal to the key. There are no constraints on the y axis.

For boolean fcurves you don't need to specify the tangency; the only values you need to define are the key time, which can have any real value, and the key value, which can have value "1" or "0". Note that "True" and "False" are not valid parameters and "1" and "0" must respectively be used as representative values.

Parameter	Type	Description
Type	siFCurveType	The type of the FCurve. Default Value: defined by parameter type
Interpolation	siFCurveInterpolation	The interpolation of the FCurve Default Value: defined by parameter type
Extrapolation	siFCurveExtrapolation	The extrapolation of the FCurve Default Value: defined by parameter type
KeyDataArray	Variant	The structure of the array is defined by the previous parameters and the number keys. The array must be either 1-dimensional or 2-dimensional. For 2-dimensional arrays, the first dimension defines the values for each key; the second defines the number of keys. It is necessary to explicitly define the tangency for standard fcurves that use the default key interpolation or specify cubic interpolation. For standard fcurves using constant and linear key interpolation, 2 values are defined for each key: the key time in frames, and the key value at that frame. To specify the tangency there must be 6 values defined for each key in the following order: the key time in frames, the key value at that frame, the left tangent time in frames relative to the key time (must be a negative value), the left tangent value relative to key value, the right tangent time in frames relative to key time (must be a positive value), and the right tangent value relative to key value. In order to allow tangents to be set exactly as specified the auto tangent constraint is turned off. This may lead to an invalid curve depending on the tangent values but allows the tangents to be set as specified. If empty values are specified for tangency values the default tangents are calculated. You can specify tangents for fcurves using constant or linear key interpolation although this is optional and is only used if the key interpolation is changed to cubic. The curve handles must never extend past the value of the neighboring key frames. When the tangency is explicitly defined, the tangent values must reflect this fact. Passing "Empty" for the tangents in the case of the cubic fcurves, and not having to specify them in the case of linear and constant fcurves, ensures that the tangents for the correct handles are automatically calculated. The left and right tangents of a fcurve can be set to any real value; however, in order to preserve the functional characteristic of the curve, these tangents are subject to change. The values are automatically changed and a different fcurve is drawn if the original chosen values do not generate a curve that is also a valid function on the x and y axes. By definition an fcurve is a function, and therefore must have the property that for every value of x there exists a unique y value. Visually, this means that any vertical line drawn along the domain of x can only pass through the curve once. A minimal rule to guarantee that this functional property holds for a curve is to ensure that the right tangent of a given key is less than or equal to the left tangent of the successive key. It is possible that the right tangent can be moved past this point and the fcurve is still valid, but anything past this point and the tangent values are subject to change. Furthermore, to ensure the functionality of an fcurve, the right tangent of a given key must always be greater than or equal to the value of the key itself and the left tangent must be less than or equal to the key. There are no constraints on the y axis. For boolean fcurves you don't need to specify the tangency; the only values you need to define are the key time, which can have any real value, and the key value, which can have value "1" or "0". Note that "True" and "False" are not valid parameters and "1" and "0" must respectively be used as representative values.

1. VBScript Example

'
'	This example demonstrates how to create a standard fcurve with tangents automationally
'	calculated.
'
NewScene , False
set oCube = Application.ActiveSceneRoot.AddGeometry( "Cube","MeshSurface" )
dim aKeyData : aKeyData = array( 1.00, 5.00, Empty, Empty, Empty, Empty, 100.00, 6.00, Empty, Empty, Empty, Empty )
set f = oCube.posx.AddFCurve( , , , aKeyData )
' Write the fcurve keys (assuming standard fcurve)
for each k in f.Keys
	Application.LogMessage k.Name &" Value: " & k.Value
	Application.LogMessage k.Name &" Locked: " & k.Locked
	Application.LogMessage k.Name &" Left: " & k.Left
	Application.LogMessage k.Name &" Right: " & k.Right
	Application.LogMessage k.Name &" LeftTanX: " & k.LeftTanX
	Application.LogMessage k.Name &" LeftTanY: " & k.LeftTanY
	Application.LogMessage k.Name &" RightTanX: " & k.RightTanX
	Application.LogMessage k.Name &" RightTanY: " & k.RightTanY
	Application.LogMessage k.Name &" Interpolation: " & k.Interpolation
	Application.LogMessage k.Name &" Flags: " & k.Flags
next

2. JScript Example

/*
	This example demonstrates how to create a standard fcurve with linear interpolation
*/
NewScene( null, false );
var cube = Application.ActiveSceneRoot.AddGeometry( "Cube", "MeshSurface" );
var aKeyData = Array
(
	1.00, 5.00, 
	100.00, 6.00
)
// Create a standard fcurve with linear interpolation. Notice that you
// only specify time/value pairs for the keydata.
var fc = cube.posx.AddFCurve( null, siLinearInterpolation, null, aKeyData );