MotionBuilder 2014

Animation and Characters

1. These new classes provide SDK access to the flexible mocap workflow: FBControlSetState, FBEffectorSetState, and FBCharacterMarkerSet.
2. The FBCharacterInputType enum type has a new enumerator (kFBCharacterInputMoCap).
3. New argument (pResetOrientation) in the function FBActor::GetCurrentSkeletonState() – When it is set to true, all rotations in the state is reset to characterization values. For example code, see <yourinstallationfolder>/bin/config/Scripts/Samples/Character/CharacterMarkerSetFromActor.py.
4. The following functions and properties are added to the FBCharacter class.
   • GetGoalModel() – To get the goal model associated with each body part in the character marker set of the character.
   • CreateCharacterMarkerSet() – To create the character marker set.
   • GetCharacterMarkerSet() – To obtain the input character marker set.
   • GetControlSetEvaluationCache() – To return the evaluation cache that is dedicated for control set and evaluation information.
   • GetEffectorEvaluationCache() – To return the evaluation cache that is dedicated for effector set and evaluation information.
   • New read/write properties LockX, LockY, and LockZ lock character skeleton in place on X, Y and Z axis respectively.
5. Following are the changes in the FBCharacterSolver class:
   • New parameter (pEvaluateCandidates) in function FBCharacterSolver::BackgroundEvaluateInfoBegin() to specify whether to resolve candidates.
   • Added new functions: FBCharacterSolver::BackgroundEvaluateInfoRecursiveBegin() and FBCharacterSolver::BackgroundEvaluateInfoNotify(). For example code, see <yourinstallationfolder>/OpenRealitySDK/Samples/constraints/CharacterSolver/IK2014Solver.
   • New virtual FBCharacterSolver::ResetExtraProperties() function provides support for resetting properties that are defined and specific to the custom solver.
   • New function FBCharacterSolver::GetDoubleSolve() to indicate the control rig’s double solve property status.
6. You can now query or set the current character’s floor contact visibility using these new functions: FBGetCharacterFloorContactsVisibility() and FBSetCharacterFloorContactsVisibility(). For finger visibility, you can use FBGetCharacterFingerTipsVisibility() and FBSetCharacterFingerTipsVisibility().
7. The new FBPlotPopup::EnablePlotLockedProperties read/write property specifies whether to enable the Plot Locked Properties option for popup.
8. The new data member FBPlotOptions::mPlotLockedProperties specifies whether to plot locked properties.
9. Previously, to create a take and make it accessible in the Transport control using the SDK, you need to use FBTake* lTake = FBSystem::ThenOne().CurrentTake->CopyTake( "new take" ). Now, you can do this using FBSystem::TheOne()::Scene.Takes.Add( new FBTake( "new take" )).
10. Other improvements in the FBTake class are the following:
    • New argument (pMergeLockedProperties) in the MergeLayers() function to specify whether the properties need to be merged even when they are locked.
    • New argument (pOnLockedProperties) in the ClearAllProperties() function to specify if clear operation will be performed on locked properties.
    • New PlotTakeOnSelected(FBPlotOptions* pPlotOptions) function to plot the animation on selected models.
    • New PlotTakeOnSelectedProperties(FBPlotOptions* pPlotOptions) function to plot the animation on selected properties.
11. Following new enumerators in the FBTangentMode class:
    • kFBTangentModeTimeIndependent – This is calculated based upon the slope between the previous and next key values. In the UI, it is identified as Spline.
    • kFBTangentModeClampProgressive – Flattens the tangent handles when the key value goes over or under the previous and next key values. In the UI, it is identified as Auto.
12. Following changes in the FBFCurve class:
    • New parameters (FBInterpolation pInterpolation=kFBInterpolationCubic and FBTangentMode pTangentMode=kFBTangentModeAuto) in the FBFCurve::KeyAdd() function.
    • The function FBFCurve::Replace() is deprecated for naming consistency. Instead, you can use the FBFCurve::KeyReplaceBy() function.
13. Added new parameters (FBInterpolation pInterpolation=kFBInterpolationCubic and FBTangentMode pTangentMode=kFBTangentModeAuto) in the FBAnimationNode::KeyAdd() function.
14. New FBEvaluateInfo::GetBufferID() function is useful for the custom constraint plug-in development with multiple threading evaluation support.
15. Following are the changes in the FBProperty class and its descendants:
    • A set of functions related to the property locking feature are added to the FBProperty class:GetSubMemberCount(), AllowsLocking(), HasSomethingLocked(), IsLocked(), IsMemberLocked(), SetLocked(), and SetMemberLocked(). Locking a property or any number of its channels prevents the modification of animation in the property. You cannot add, remove, or edit any key on any layer of a locked property or channel. Also, you cannot change the current value of the property. However, a locked property allows existing animation to flow through. The value of a locked property can change through time as it is being driven by existing animation or constraints.
    • The FBPropertyAnimatable class has two new functions: SetCandidate() and SetGlobalCandidate() that are useful for keying candidate.
    • A set of new functions related to the property mute feature are added to the FBPropertyAnimatable class: AllowsMuting(), HasSomethingMuted(), IsMuted(),IsMemberMuted(), SetMuted(), and SetMemberMuted(). Muting an animatable property or its channels prevents animation from flowing through the property or its channels. The value of a muted property or its channels is the value upon muting, and does not change over time as it is being driven by existing animation or constraints. You can still modify a muted property to add, remove, and edit the existing keys.
16. New FBConstraintManager::TypeCreateConstraint(const char* pName) function allows to create a constraint by name.
17. New argument (FBTimeMode pTimeMode = kFBTimeModeDefault) in the FBPlayerControl::GetTransportFpsValue() function to specify the time mode whose frame rate will be returned.
18. New functions added to the FBTimeCode class: GetRawSecond(),GetRawFrame(), and GetRawRate(). Additionally, the equality comparison operator function overload.

Story

1. New FBStoryFolder::Collapsed read/write property to collapse/expand the story folder.
2. New FBStoryClip::MakeWritable() function to import FCurves from a story clip and make them accessible to the user.
3. New FBStoryClip::GetFbxScene() function to return the pointer inside FBXSDK::FbxScene for read-only animation clip.

File IO and Reference

1. New FBFileReference class provides the basic access to the file reference feature through various SDK functions.
2. New FBComponent::GetOwnerFileReference() function to get the owner file reference object.
3. Changes to the FBScene class including the following:
   • New GetScriptsPaths() function to get the path of all python script objects in a scene.
   • New NamespaceGetOwnerFileReference() function to get the owner file reference object if the namespace originates from file reference.
   • New argument (pAsFileReference) in the NamespaceImport() function to specify whether to import the file as file reference.
   • New argument (pAsFileReference) in the NamespaceImportToMultiple function to specify whether to import the file as file reference.
   • Following new object list properties are added to allow easy access to certain type of scene objects: CharacterMarkerSets, FileReferences, KeyingGroups, ModelSkeletons, and ModelOpticals.
4. New global functions: FBMergeTransactionFileRefEditBegin() and FBMergeTransactionFileRefEditEnd() can be called in pair to improve the performance during multiple file merging process with the file reference editing operation.
5. Following are the changes to the FBFbxOptions class.
   • New kFBOptionsContextSaveSelection enumerator in FBOptionsContext to save selection case.
   • New SaveToString() function to serialize all options to a string.
   • New SetFromString() function to set all options from a string.
   • New UpdateRecentFiles read/write property to specify whether to update the recent file list.
   • New FileReference read/write property to load/save scene as file reference.
   • New FileReferenceEdit read/write property to specify whether to load/save the edits made to referenced objects.
   • New FileReferences read/write property to specify the handling of the file reference elements.
   • The default value of KeepTransformHierarchy property is changed to False to ensure consistent behavior with SaveSelected operation using the File menu.
   • New RemoveEmptyLayer property indicates whether to remove empty animation layers that are in additive mode without child or parent.
   • New ConsiderMuteSolo property considers the mute/solo settings to identify identical layer when merging.
6. New FBFileMonitoringManager::OnFileChangeFileReference event callback property to monitor the change events for the referenced file.
7. New argument (FBDataAsStringFlag pFlag = kFBDataAsStringUI) in the FBProperty::AsString() function to specify whether the returned string is used for UI display or persistent.
8. A set of new object list property types are added that allows easy access to the same type of objects in a scene.
   • FBPropertyListCharacterMarkerSet FBScene::CharacterMarkerSets
   • FBPropertyListKeyingGroup FBScene::KeyingGroups
   • FBPropertyListFileReference FBScene::FileReferences
   • FBPropertyListModelSkeleton FBScene::ModelSkeletons
   • FBPropertyListModelOptical FBScene::ModelOpticals
   • FBPropertyListRendererCallback FBRenderer::RendererCallbacks

Renderer and Viewport

1. New FBRendererCallback class for the custom renderer feature. You can implement your complete custom rendering solution by subclassing this class. For example code, see <yourinstallationdirectory>/OpenRealitySDK/Samples/shaders/CustomRenderer.
2. New FBRendererCallbackLayout class is the base layout class that is inherited by the custom renderer configuration UI.
3. Following functions are added to the FBViewingOptions class:
   • The IsInSelectionBufferPicking() function is the rendering routine during picking status with the GL selection buffer method.
   • The IsInColorBufferPicking() function is the rendering routine during picking status with the GL color buffer method.
   • The RenderCallbackPrefIndex() function gets the current render callback’s preference settings index.
4. Following functions are added to the FBRenderOptions class:
   • The IsIDBufferRendering() function gets the IDBuffer rendering request status (for display or picking).
   • The GetViewerOptions() function gets the current viewer’s option.
5. Following are the changes to the FBRenderer class:
   • The new OGLSetupSceneLights() function is used to setup the scene lights in OpenGL (maximum of eight lights are supported).
   • The new GetLastPickInfoList() function returns the last picking info list in the current view pane.
   • Following new properties are added:
     • SelectionForceSnapPointsDisplay (read/write) – Force to show all feature points (pivots and others) on selected models if true, ignore individual model's settings.
     • RendererCallbacks (read/write) – List of renderer callbacks.
     • RegisteredCallbackCount (read-only) – Registered renderer callbacks count.
     • CurrentPaneCallbackIndex (read/write) – Current pane's renderer callback index.
     • CurrentPaneCallbackPrefIndex (read/write) – Current pane's renderer callback preference index.
     • AdvancedLightingMode (read/write) – Turn on/turn off the advanced lighting setting UI widgets.
6. Changes to support area light type includes the following:
   • New enumerator kFBLightTypeArea in FBLightType. However MotionBuilder does not support this natively in its default viewport. Custom render is required to use this additional pipeline benefit.
   • New enum type FBLight::EAreaLightShapes { eRectangle, eSphere}.
7. Following are the new read/write properties in the FBLight class: AreaLightShape, InnerAngle, OuterAngle, EnableBarnDoor, LeftBarnDoor, RightBarnDoor, TopBarnDoor, and BottomBarnDoor.
8. Following are the viewport picking related enhancements:
   • New mSubItemIndex member variable added for sub item picking in the FBPickInfos class.
   • New FBPickInfos::mNormal member variable allows you to query the normal direction in the world space of the intersection point between the picking ray and model’s surface.
   • New argument (pSubItemIndex) in the FBFindModelByUniqueColorId() function to pass out the sub-item index value. For example code, see <yourinstallationdirectory>/OpenRealitySDK/samples/miscellaneous/model_template.
9. Changes to FBModel class includes the following:
   • New UniqueColorId read-only property to provide the model’s unique color ID for OpenGL color ID buffer based viewer picking.
   • A set of new functions to support multiple sub-items per model/geo selection and picking in OpenGL color buffer mode using the custom rendering routines: SetAdditionalUniqueColorIDCount() to request additional unique color IDs per model, GetAdditionalUniqueColorIDCount() to get additional unique color count, GetAdditionalUniqueColorID() to get additional unique color ID. For example code, see <yourinstallationdirectory>/OpenRealitySDK/Samples/miscellaneous/marker_template.
   • The PushZDepthClipOverride() and PopZDepthClipOverride() functions are added to facilitate the custom render implementation to work with the Z-depth HideFront selection tool.
   • New read-write properties: PrimaryVisibility, CastsShadows, and ReceiveShadows added to control a model’s render state and shadow rendering policy, and to increase rendering interop consistency with other DCC tools.
10. Following are the changes in the FBCamera class:
    • Two new enumerators are added to FBCameraMatrixType: kFBModelViewProj for a camera’s model-view-projection matrix, and kFBProjInverse for a camera’s projection inverse matrix.
    • Added the WindowWidth, BackGroundTexture,ForeGroundTexture, and ViewShowName properties.
    • Added the GetCameraMatrix() and InverseProjection() functions.

Geometry

1. Following improvements in the FBGeometry class:
   • New IsEditingEnabled() function to determine if geometry editing is enabled.
   • A set of new functions for directly manipulating geometry position, normal, tangent, bi-normal, color, UV, and material arrays: VertexArrayInit(), VertexArrayClear(), GetPositionsArray(), GetTangentsIndexArray(), GetTangentsDirectArray(), GetBinormalsIndexArray(), and GetBinormalsDirectArray(). For example code, see <yourinstallationdirectory>/bin/config/scripts/Samples/Geometry/VertexArrayManipulation.py.
   • New read-only properties for tangent and bi-normal mapping/reference mode: TangentMappingMode, TangentReferenceMode, BinormalMappingMode, and BinormalReferenceMode.
2. Several new functions are added to the FBMesh class for faster mesh creation using the SDK. For example code, see <yourinstallationdirectory>/bin/config/scripts/Samples/Geometry/VertexArrayManipulation.py.
   • TriangleListAdd() for adding triangle list, TriangleStripAdd() for adding triangle strip, and PolygonListAdd() for adding polygon list.
   • PolygonVertexArrayGet() to get the array of polygon vertex (index to control points).
   • IsTriangleMesh() to determine if the mesh is composed entirely of triangles.
   • PolygonMaterialIdGet() to get the material ID for a polygon’s index.

Model and Elements

1. The FBGroup and FBSet classes can hold animatable properties and are now inherited from the FBBox class instead of the FBComponent class to be consistent with the other classes.
2. Several changes to the FBHUDElement class and its subclasses including the following:
   • The FBHUDElement class is now inherited from the FBBox and FBComponent class to support animatable properties.
   • New FBHUDElement::Show read/write property to specify whether the HUD element will be displayed.
   • New virtual functions: GetIntrinsicDimension(), DrawElement(), FbxStore(), and FbxRetrieve() to allow users to implement their own custom FBHUDElement type with persistent capability. For example code, see <yourinstallationdirectory>/OpenRealitySDK/Samples/miscellaneous/hudelement_template.
   • New type of HUD elements: FBHUDBloopSlateElement and FBHUDTimelineElement.
3. Following changes to the FBHUD class:
   • The FBHUD class is now inherited from the FBBox and FBComponent class to support animatable properties.
   • The EStockElement type now has new enumerators: eTextureElement, eBloopSlate, and eTimeline.
4. Following changes to the FBModelPath3D class:
   • Now each control point in the path corresponds to an animatable FBVector4d type property (with naming convention as Point_%d), which allows each control point to have keyframe animation, relation constrain setup, or direct connection with model for attaching behavior.
   • New PathLength read-only property to get the path’s length in centimeter (CM) and PathLengthInString for its string representation in the current choice of unit and precision.
   • New read/write properties: PathLengthUnit, PathLengthShow, TextScale, TextBackground, PathEndCapStyle, and PathEndCapScale to specify the path and length label appearance in the viewport.
5. Other changes to the FBModel class includes the following:
   • New read/write properties: TranslationActive, TranslationMin, TranslationMax, TranslationMinX, TranslationMinY, TranslationMinZ, TranslationMaxX, TranslationMaxY, and TranslationMaxZ to access the translation limit information.
   • New Transformable read/write property to indicate whether a model can be transformable in the viewer. This has a default value of true.
   • New IsEvaluationReady() function for querying the model's evaluation task status.
   • New MatrixToRotation() and RotationToMatrix() functions allow the conversion between rotation Matrix to Euler Vector based on a model's rotation order.
   • New LRMToDof() and DofToLRM() functions allow the conversion between local rotation matrix to object space ration vector.
   • You can override the new ClosestRayIntersection() virtual function to determine the first intersection point's position and normal between ray and model surface.
6. Following new enumerators are added in the FBMarkerLook class:
   • kFBMarkerLookRigidGoal for rigid goal.
   • kFBMarkerLookRotationGoal for rotation goal.
   • kFBMarkerLookAimRollGoal for aim and roll goal.
7. The new FBModelSkeleton::DrawLink property determines whether to draw a link to the parent node.

Application Framework

1. Following changes to the FBSystem class:
   • New GetCommandLineArgs() function returns portion of the command line arguments within a pair of delimiters (--sdk-begin and --sdk-end).
   • New GetPythonStartupPath() function returns the list of folders where MotionBuilder will search for Python scripts and execute them automatically at startup.

   • New GetPluginPath() function returns the list of folders where MotionBuilder will search for ORSDK plugins and load them automatically at startup.

2. Following changes to the FBApplication class:
   • New FlushEventQueue() function flushes event queue, and processes all pending events for the calling thread until there are no more events to process. Useful for controlling main application loop to perform special tasks. For example code, see <yourinstallationfolder>/bin/config/Scripts/Samples/Profiling/CreateProfilingEventsLog.py.
   • A set of new functions related to the One-Click workflow:
     • The OneClickSendAsNewScene() function to send the current scene as a new scene to the specified application (currently supports Maya and 3ds Max only).
     • The OneClickUpdateCurrentScene() function to send the scene to update the current scene in the specified application.
     • The OneClickAddToCurrentScene() function to Send the scene and add it to the current scene in the specified application.
     • The OneClickSelectPreviouslySentObject() function to select the object that was sent from MotionBuilder.
     • The OneClickIsConnectedTo() function to return the identifier from the other application that is connected to MotionBuilder.
3. Following changes to the FBEvaluateManager class:
   • New IsInteractiveMode() function to check if the application main loop is in interactive or offline rendering mode.
   • Enum FBGlobalEvalCallbackTiming has a new enumerator to allow registering per frame callbacks (global functions) into the rendering pipeline.
     • The kFBGlobalEvalCallbackSyn is invoked when both evaluation and rendering pipelines (or threads) are stopped. Useful in some complicated scene change tasks to avoid race condition.
     • The kFBGlobalEvalCallbackBeforeRender is invoked in rendering pipeline before any rendering tasks start (immediately after clearing GL back buffer).
     • The kFBGlobalEvalCallbackAfterRender is invoked in rendering pipeline after any rendering tasks are finished (just before swapping GL back/front buffer).
   • New event callback properties: OnEvaluationPipelineEvent, OnRenderingPipelineEvent, and OnSynchronizationEvent to allow registration of per frame callbacks function (with ICallback interface) into various critical timing, stages, and pipelines in the application main loop.

UI

1. The new FBWidgetHolder::WidgetCreate() virtual function can be overridden so that you have more flexibility in bridging native QT UI with the MotionBuilder UI framework. You can also do this using Python. For example code, see <yourinstalationdirectory>/bin/config/Scripts/UI/ToolNativeWidgetHolder.py.
2. New FBVisualComponent::GetQWidgetAddress() function returns the memory address of the corresponding internal QWidget object.
3. New FBApplication::UpdateAllWidgets() function to request UI refresh for all widgets.
4. New FBComponent::UseCustomPropertyViewSet() virtual function can be overridden to indicate whether the subclass instance uses the custom property ViewSet. For example code, see the ORSDK sample project in <yourinstallationdirectory>/OpenRealitySDK/Samples/miscellaneous/marker_template.
5. New FBWebView class is a simple UI widget that can load a webpage. For code example, see <yourinstallationdirectory>/bin/config/Scripts/UI/WebView.py.
6. The new FBPropertyViewList, FBPropertyViewDefinition, and FBPropertyViewManager classes provide ways to create new property views. For example code, see <yourinstallationdirectory>/OpenRealitySDK/Samples/constraints/CharacterSolver/HIK2014Solver and <yourinstallationdirectory>/bin/Scripts/Samples/Properties/PropertyViewManager.py.
7. The new FBActionManager class enables you to query and modify the current interaction mode, for example, switch to MotionBuilder, Maya, or 3ds Max keyboard.

Video and Image Sequence

1. You can now subclass FBLayeredTexture to support custom blending and composition modes. For example code, see <yourinstallationdirectory>/OpenRealitySDK/Samples/miscellaneous/texture_template.
2. New FBTexture::TextureOGLId property allows you to query its OpenGL texture object ID.
3. New FBSystem::OnVideoFrameRendering event callback property is triggered when the scene is being off-line rendered into video files before and after every frame.
4. Struct FBVideoGrabOptions has new data members: mRendererCallbackIndex and mRendererCallbackPrefIndex to specify renderer callback and preference index.
5. New FBImage::GetBufferAddress() function to access the image data buffer and allow modifications.
6. New FBVideoCodecManager::RegisterExternalVideoFormat() function enables you to register any image/video file suffix which MotionBuilder cannot recognize. However, it is the plug-in developer’s responsibility to load the file into memory.
7. New FBVideoOut::Online read/write property to control the video out and online status of the device.
8. New FBVideoClipImage::ImageSequence read/write property that when set true tries to search for files in a folder to compose an image sequence.
9. Following changes to the FBStoryClip class:
   • NewImageSequence read/write property to indicate whether to use Image sequence.
   • New UseSystemFrameRate read/write property to indicate whether to always use the system frame rate.
   • New FrameRate read/write property for frame rate value that is only effective when UseSystemFrameRate is false.

Miscellaneous

1. New helper classes: HdlFBPlug and HdlFBPlugTemplate to handle dangling pointer issue of FBPlug and its subclasses. For example, see <yourinstallationdirectory>/OpenRealitySDK/Samples/tools/toolqttest.
2. The trace and log mechanism is re-designed and improved. Now, you can set the trace message level, redirect trace output to Python editor console, or even register external trace output target. See the FBTraceSetLevel(), FBTrace(), and FBTraceWithLevel() functions.
3. Improved the FBArrayTemplate class for commonly used date type (bool, int, float, double, and others) in fbsdk library for convenient usage.
4. Added copy constructor to the FBArrayTemplate class to support proper deep copy behavior and avoid potential crash in certain usage scenarios.
5. New argument (pClearFile) in the FBConfigFile::FBConfigFile(const char* pConfigFileName, bool pVirtualMode = false, bool pClearFile = false) constructor function, and new arguments (pVirtualMode and pClearFile) in the FBConfigFile::FBConfigFile (const char* pConfigFileName, const char* pConfigFilePath, bool pVirtualMode = false, bool pClearFile = false) constructor function to remove all existing content from the configuration file upon opening.
6. Added two math utility functions: FBMatrixToQuaternion() for getting a quaternion from a matrix and FBQuaternionToMatrix() for getting a rotation matrix from a quaternion vector.
7. Following changes to the FBStringList class:
   • New arguments (pCaseSensitive and pStartWith) in the Find() function to allow more flexible searching options.
   • New argument (pSeparator) in the AsString() function to change the default string list separator.
   • New argument (pSeparator) in SetString() function to choose a different string list separator.
   • Overloaded assignment operator and copy constructor to support deep copy behavior.
8. Python callbacks registered to FBPropertyEvent are unregistered automatically if they throw exception during runtime.
9. New GetStatStart() and GetStatStop() functions in the FBProfiler class. For example code, see <yourinstallationdirectory>/bin/config/Scripts/Samples/Profiling/CreateProfilingEventsLog.py.

Deprecation

SDK Sample Changes

In MotionBuilder 2014, several ORSDK C++ sample projects and Python sample scripts are updated to fix known bugs. Some SDK samples are newly created to demonstrate the new capabilities.