Object Model: Parameter.AddFCurve

Parameter.AddFCurve

Description

Creates and connects an FCurve to a Parameter object, and optionally adds keys. If no type argument is specified, then the type of fcurve added will be based on the parameter's type (which is configured in the parameter's definition). You can override the default fcurve type associated with a parameter by adding the SPDL attribute 'FCurveType = Standard;' or 'FCurveType = Integer;'.

By default standard fcurves will be created for parameters of type: siDouble, siFloat, siInt4, siInt2, siByte, siUInt4, siUInt2 and siUByte (see siVariantType for further details on types). If the parameter represents a boolean, then a boolean fcurve will be created.

For the JScript-compliant version of this method, see Parameter.AddFCurve2.

C# Syntax

FCurve Parameter.AddFCurve( Object in_Type, Object in_Interpolation, Object in_Extrapolation, Object in_KeyDataArray );

Scripting Syntax

oReturn = Parameter.AddFCurve( [Type], [Interpolation], [Extrapolation], [KeyDataArray] );

Return Value

FCurve

Parameters

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.

Examples

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 );