FBX SDK对象模型

FBX SDK对象模型

  本节介绍了FBX SDK对象模型。 此处解释了几个关键概念，以使您直观地了解如何有效使用FBX SDK。

内存管理
  FBX SDK中的内存管理由FBX SDK Manager对象（FbxManager）执行。 FbxManager单例负责创建，操作和销毁SDK使用的对象。
对象
  FBX SDK中的大多数类都是从FbxObject派生的。 有关更多信息，请查阅FBX Objects主题和FbxObject类参考页。 从FbxObject派生的类的示例包括场景节点，I / O对象和集合。

一.FBX对象

1.FBX对象创建和销毁

  FBX对象是FbxObject或从FbxObject派生的任何其他类的实例。 对象的实例是通过调用其类的Create（）函数以及对应用程序的FbxManager单例的引用或对FbxScene对象的引用来创建的。
  可以通过调用其Destroy（）成员函数或在用于创建该对象的FbxManager或FbxScene对象上调用Destroy（）来显式销毁该对象。 可以通过调用FbxObject :: GetFbxManager（）来检索用于实例化FbxObject的FbxManager。 请注意，在下面的代码示例中，FbxImporter从FbxIO继承，而FbxIO从FbxObject继承。

// Assume pImporter is an instance of FbxImporter.
FbxManager* lSdkManager = pImporter->GetFbxManager();

2.属性

  FBX SDK使用FbxProperty类来强制属性与FbxObject实例的强类型，静态和/或动态关联。 FBX属性主题中描述了FBX SDK属性主题。

3.集合

  FbxAnimLayer，FbxAnimStack和FbxScene等容器类从FbxCollection类继承。 此类提供了以下接口：
  添加成员-FbxCollection :: AddMember（）
  删除成员-FbxCollection :: RemoveMember（）
  计数成员-FbxCollection :: GetMemberCount（）
  获取成员-FbxCollection :: GetMember（）
  搜索其成员-FbxCollection :: FindMember（）
  FbxCollection :: GetMemberCount（）和FbxCollection :: GetMember（）函数被重载以接受FbxCriteria。

4.复制FBX对象

  可以通过调用FBX对象的Copy（）成员函数来复制FBX对象。 赋值运算符（operator =）不能用于复制FBX对象。 它是一个私有成员函数。 以下代码示例说明了如何复制网格对象。

// Assume that lScene is a pointer to a valid scene object.
FbxMesh* lSourceMesh = FbxMesh::Create (lScene, "");
 
// Define control points, etc. for lSourceMesh.
 
// This mesh will be overwritten
FbxMesh* lTargetMesh = FbxMesh::Create (lScene, "");
 
// Copy the data from lSourceMesh into lTargetMesh. Note that
// the source object and the target object must be instances of
// the same class (FbxMesh in this case).
lTargetMesh->Copy(lSourceMesh);

注意：复制FbxObject还将复制其所有关联的FbxProperty实例及其值。
注意：复制FbxObject不会复制其任何对象间连接（例如，父子关系）。 这些连接必须在副本上明确设置。

二.FBX属性

1.管理属性

  FbxProperty模板类用于确保FbxObject的数据具有强类型。 例如，使用参数为FbxDouble3的FbxTypedProperty描述FbxNode的本地转换向量。
  创建FbxObject时，将自动初始化其静态内置FbxProperty。 若要创建自己的FbxProperty，必须调用FbxProperty :: Create（），然后将引用传递给FbxObject或另一个FbxProperty。
  下面的代码示例摘自Animation示例。 在此的示例FbxProperty :: Create（）的第一个参数是FbxScene对象。 第二个参数是属性的数据类型（可以在fbxdatatypes.h头文件中找到数据类型的完整列表）。 第三个参数是属性的分配名称。

FbxProperty p = FbxProperty::Create(pScene, DTDouble3, "Vector3Property");
FbxSet<FbxDouble3>(p, FbxDouble3(1.1, 2.2, 3.3);

  可以通过调用FbxProperty :: GetName（）来访问创建FbxProperty的名称。 此名称可用于在层次结构中搜索属性。
  FbxProperty的实例可以通过调用FbxProperty :: Destroy（）销毁。 可以通过在根属性上调用FbxProperty :: DestroyRecursively（）来破坏FbxProperty的层次结构。

2.属性数据

  FbxProperty的实例中，可以分别调用FbxProperty :: Set（）和FbxProperty :: Get（）进行设置和访问属性数据。 例如，可以通过以下方式访问以FbxDouble3的向量表示的FbxNode几何变换数据：

// ... initialize FbxNode* lNode ...
FbxDouble3 translation = lNode->LclTranslation.Get();
FbxDouble3 rotation = lNode->LclRotation.Get();
FbxDouble3 scaling = lNode->LclScaling.Get();

  FbxTypedProperty中包含的数据只能设置为对该属性的数据类型有效的值。 支持某些隐式转换。 例如，您可以在需要double时提供int值。

标志
  属性还包含一组FbxPropertyFlags :: eFbxPropertyFlags，可以使用FbxProperty :: GetFlag（）和FbxProperty :: ModifyFlag（）进行操作。

运算符
  标准比较和赋值运算符可用于比较属性并将属性彼此赋值（FbxProperty :: operator ==（），FbxProperty :: operator！=（），FbxProperty :: operator =（））。

用户定义数据
  FbxProperty类可以包含用户定义的数据，这些数据可以在运行时动态关联到FbxObject。

3.属性层次

  可以按层次结构组织属性。 FbxProperty可以连接到FbxObject或另一个FbxProperty。可以通过调用FbxProperty :: GetFbxObject（）来访问属性的绑定FbxObject。 ExportScene05示例说明了属性层次结构的构造。

访问FBX对象的属性
  FBX对象可以具有许多属性，可以使用FbxObject :: FindProperty（）搜索这些属性。也可以通过调用诸如FbxObject :: GetFirstProperty（）和FbxObject :: GetNextProperty（）之类的方法来迭代对象的属性。

导航属性层次结构
  可以通过FBX属性导航功能遍历FBX属性的层次结构：FbxProperty :: GetParent（），FbxProperty :: GetChild（），FbxProperty :: GetSibling（），FbxProperty :: Find（）仅举几例。

4.示例代码

  以下示例代码摘自ExportScene05示例。 它说明了如何创建自己的FbxProperty值，并将其绑定到FbxObjectMetaData实例（该实例继承自FbxObject）。

// ... initialize pScene as a FbxScene* ...

// Create a FbxObjectMetaData* object in pScene.
FbxObjectMetaData* lFamilyMetaData = FbxObjectMetaData::Create(pScene, "Family");

// Create and assign data to several instances of FbxProperty, based on their parametrized
// datatypes (DTString, DTFloat, DTDouble). 
//
// The fourth parameter is an optional label string, which can be obtained and modified
// using FbxProperty::GetLabel() and FbxProperty::SetLabel(). This label only exists
// in the program's main memory, and will not be exported to a file if/when the property
// is exported.
// 
// These properties will be contained within the pFamilyMetaData object.
//
FbxProperty::Create(lFamilyMetaData, DTString, "Level", "Level").Set(FbxString("Family")); // String
FbxProperty::Create(lFamilyMetaData, DTString, "Type", "Type").Set(FbxString("Wall"));     // String
FbxProperty::Create(lFamilyMetaData, DTFloat, "Width", "Width").Set(10.0f);              // float
FbxProperty::Create(lFamilyMetaData, DTDouble, "Weight", "Weight").Set(25.0);            // double
FbxProperty::Create(lFamilyMetaData, DTDouble, "Cost", "Cost").Set(1.25);                // double

三.连接

1.可视化连接

  连接是FBX SDK数据结构，用于管理FBX对象和/或FBX属性之间的双向关系。为了保证FBX SDK中连接的一致性，实际的数据结构未公开。而是可以使用FbxObject和FbxProperty连接管理方法来操纵连接，例如：FbxObject :: ConnectSrcObject（），FbxObject :: ConnectDstObject（），FbxProperty :: ConnectDstObject（），FbxProperty :: ConnectSrcProperty（）等）。
  可以将连接可视化为FBX对象和属性的目标和源层次结构。
对象-属性连接：
  属性包含在对象中作为源。调用FbxObject :: GetSrcProperty（）将在给定索引处返回对象的source属性。对称地，调用FbxProperty :: GetDstObject（）将返回属性的目标对象。
对象-对象连接：
  对象之间的父子关系使用连接（例如：场景的节点层次结构）。通常，对象的子对象是源，可以使用FbxObject :: GetSrcObject（）访问。对象的父对象是目的地，可以使用FbxObject :: GetDstObject（）访问。
属性-属性连接：
  属性之间的父子关系也使用连接（例如：FbxIOSettings的属性层次结构）。通常，属性的子级是源，可以使用FbxProperty :: GetSrcProperty（）访问。属性的父对象称为目标，可以使用FbxProperty :: GetDstProperty（）进行访问。

下面的代码示例中说明了上图中的目标和源连接。
访问obj0的源对象：

// ... Assume obj0 has been initialized to reflect the diagram above...
// For illustrative purposes, count the number of source objects connected to obj0.
int numSrcObjects = obj0->GetSrcObjectCount(); // numSrcObjects = 2

// Access the two source objects connected to obj0
// Note that obj0->GetSrcObject(0) is equivalent to calling obj0->GetSrcObject()
FbxObject* obj1 = obj0->GetSrcObject(0);
FbxObject* obj2 = obj0->GetSrcObject(1);

访问obj0的source属性：

// ... Assume obj0 has been initialized to reflect the diagram above...
FbxProperty* prop0 = obj0->GetSrcProperty();

访问obj1的目标对象：

// ... assume obj1 has been initialized to reflect the diagram above...
FbxObject* obj0 = obj1->GetDstObject();

从obj2开始遍历层次结构：

// ... Assume obj2 has been initialized to reflect the diagram above...
// Access prop2 using obj2.
FbxProperty* prop2 = obj2->GetSrcProperty();

// For illustrative purposes, count the number of source properties of prop2.
int numSrcProperties = prop2->GetSrcPropertyCount(); // numSrcProperties = 2

// Access prop3 and prop4, which are sources with respect to prop2, 
// respectively indexed at 0 and 1.
FbxProperty* prop3 = prop2->GetSrcProperty(0);
FbxProperty* prop4 = prop2->GetSrcProperty(1);

// Access obj0 using obj2.
FbxObject* obj0 = obj2->GetDstObject();

// Access prop0 using obj0.
FbxProperty* prop0 = obj0->GetSrcProperty();

// Access obj1 using obj0. 
// Here, we assume obj1 is indexed at 0, whereas obj2 is indexed at 1.
FbxObject* obj1 = obj0->GetSrcObject(0);

// Access prop1 using obj1.
FbxProperty* prop1 = obj1->GetSrcProperty();

2.连接对象和属性

  FBX SDK中的连接概念允许将FbxProperty实例动态添加到FbxObject。这使您可以灵活地定义自己的数据类型，通过FbxProperty :: SetUserDataPtr（）成员函数将其包装到FBX属性中，并通过FbxObject :: ConnectSrcProperty（）成员属性将该属性绑定到FBX对象。
  FbxCollection类还依靠连接将对象组组织到一个层次结构中。例如，FbxScene类包含FbxNode对象的层次结构，可通过FbxScene :: GetRootNode（）进行访问。
  在深入研究与节点（FbxNode）和节点属性（FbxNodeAttribute）相关的连接之前，建议您熟悉FBX SDK的场景图组织。有关更多信息，请查阅“节点和场景图”部分。但是，如果您喜欢冒险，下面列出的概念将使您直观地了解如何使用节点及其属性来构造场景图。
  作为简要介绍，FbxScene中的FbxNodes层次结构用于指定几何变换堆栈。从FbxNodeAttribute继承的类，例如FbxMesh，FbxCamera和FbxLight，描述了场景中的所有元素。 FbxNodeAttribute连接到FbxNode，以指定3D空间中网格，相机或灯光的位置。

3.“对象-对象”连接示例：场景中节点之间的父子关系

  场景中节点之间的父子关系利用对象连接。 考虑FbxNode :: AddChild（）方法，该方法将一个子节点添加到在其上调用该方法的父节点：

// ... Assume lScene has been initialized as a FbxScene*,

// Obtain the root node of a scene.
FbxNode* lParentNode = lScene->GetRootNode();

// Create a child node.
FbxNode* lChildNode = FbxNode::Create(lScene, "child");

// Add the child node to the root node.
lParentNode->AddChild(lChildNode);

将建立以下连接：
  子节点将成为父节点的源对象。
  父节点将是子节点的目标对象。
注意：lParentNode是lScene的源对象。 因此，lScene是lParentNode的目标对象。
注意：“合并两个场景”主题显式地操作节点之间的连接以合并两个场景的内容。

4.“对象-对象”连接示例：节点和节点属性

  FbxNode与FbxNodeAttribute的关系通常是通过调用FbxNode :: SetNodeAttribute（）创建的。 这样，可以将FbxMesh实例（继承自FbxNodeAttribute）绑定到场景中的节点。 在这种情况下：
  FbxNodeAttribute是FbxNode的源对象。
  FbxNode是FbxNodeAttribute的目标对象。
注意：材质（FbxSurfaceMaterial）也作为源对象连接到FbxNodes。 一个节点可以连接到许多材质，一种材质可以连接到许多节点（以减少内存使用）。 但是，请注意，FbxSurfaceMaterial不是FbxNodeAttribute的子类。

5.“对象-属性”连接示例：节点和转换

  如“属性数据”小节所述，将FbxNode的本地转换数据定义为FbxTypedProperty，并使用FbxDouble3数据类型进行参数化。 在这种情况下：
  FbxNode :: LclTranslation返回的FbxTypedProperty是该FbxNode的源属性。
  FbxNode是该FbxTypedProperty的目标对象。

四.错误处理

1.错误

  FBX类的许多成员函数可能会触发错误。 在这种情况下：
该函数返回false。
  objectname-> GetStatus（）。GetErrorString（）返回带有错误消息的字符串。
  objectname-> GetStatus（）。GetCode（）检索枚举中指定的发生的错误类型。

2.错误处理示例

  以下代码出现在Common / Common.cxx中。 它说明了文件导入操作的错误处理过程，包括密码保护。 某些代码已替换为“ // …”以强调错误处理功能。

bool LoadScene(FbxManager* pManager, FbxDocument* pScene, const char* pFilename)
{
  //…

  bool lStatus;
  char lPassword[1024];

  //…
  
  // Create an importer.
  FbxImporter* lImporter = FbxImporter::Create(pManager,"");
    
  // Initialize the importer by providing a filename.
  const bool lImportStatus = lImporter->Initialize(pFilename, -1, pManager->GetIOSettings());
  
  // …

  if(!lImportStatus)
    {
        FbxString error = lImporter->GetStatus().GetErrorString();
        FBXSDK_printf("Call to FbxImporter::Initialize() failed.\n");
        FBXSDK_printf("Error returned: %s\n\n", error.Buffer());

        if (lImporter->GetStatus().GetCode() == FbxStatus::eInvalidFileVersion)
        {
          FBXSDK_printf("FBX file format version for this FBX SDK is %d.%d.%d\n", lSDKMajor, lSDKMinor, lSDKRevision);
          FBXSDK_printf("FBX file format version for file '%s' is %d.%d.%d\n\n", pFilename, lFileMajor, lFileMinor, lFileRevision);
        }
        
        return false;
    }
    // …
    // Import the scene.
    
    lStatus = lImporter->Import(pScene);
    
    if(lStatus == false && lImporter->GetStatus().GetCode() == FbxStatus::ePasswordError)
    {
        FBXSDK_printf("Please enter password: ");
        lPassword[0] = '\0';
        
        FBXSDK_CRT_SECURE_NO_WARNING_BEGIN
        scanf("%s", lPassword);
        FBXSDK_CRT_SECURE_NO_WARNING_END
        
        FbxString lString(lPassword);
        
        IOS_REF.SetStringProp(IMP_FBX_PASSWORD, lString);
        IOS_REF.SetBoolProp(IMP_FBX_PASSWORD_ENABLE, true);
        
        lStatus = lImporter->Import(pScene);
        
        if(lStatus == false && lImporter->GetStatus().GetCode() == FbxStatus::ePasswordError)
        {
          FBXSDK_printf("\nPassword is wrong, import aborted.\n");
        }
    }
    
    // Destroy the importer.
    lImporter->Destroy();
    
    return lStatus;
}

五.支持的字符串格式

  FBX SDK在内部使用UTF-8字符串。 UTF-8（8位UCS / Unicode转换格式）是Unicode的变长字符编码。 它可以表示Unicode标准中的任何字符，但与ASCII向后兼容。 有关UTF-8的良好介绍，请参见Wikipedia（wikipedia.com）。
  在操作系统的API中调用函数时，FBX会将其UTF-8字符串转换为所需的字符串格式。 如果您的应用程序使用非ASCII字符，则必须先将字符串转换为UTF-8字符* C字符串，然后再将其传递给FBX。 fbxstring.h为Windows环境定义了以下转换函数：

FBXSDK_DLL void FbxWCToAnsi(const wchar_t* pInWideChar, char*& pOutANSI);
FBXSDK_DLL void FbxAnsiToWC(const char* pInANSI, wchar_t*& pOutWideChar);
FBXSDK_DLL void FbxAnsiToUTF8(const char* pInANSI, char*& pOutUTF8);
FBXSDK_DLL void FbxUTF8ToAnsi(const char* pInUTF8, char*& pOutANSI);

六.自定义FBX SDK

  本主题介绍如何自定义或扩展FBX SDK的功能。

1.自定义用户数据

  FbxObject和FbxProperty的实例提供一个（void *）指针，因此您可以将任何自定义数据关联到该实例：
  FbxObject用户数据：FbxObject :: SetUserDataPtr（），FbxObject :: GetUserDataPtr（）。
  FbxProperty用户数据：FbxProperty :: SetUserDataPtr（），FbxProperty :: GetUserDataPtr（）。
注意：您负责创建，销毁和管理自定义数据。

2.自定义属性

  FbxProperty的自定义实例可以动态添加到FbxObject。 FBX属性中提供的示例代码说明了如何创建和添加此类自定义属性。
  ExportScene05，UserProperties和Tutorial：ImportExport示例程序还提供了有关如何获取和设置自定义属性的数据的见解。

3.自定义类

  必须通过调用FbxManager :: RegisterFbxClass（）在FbxManager中注册自定义类。
  在以下从ExportScene03 / main.cxx中获取的示例中，自定义类MyFbxMesh和MyFbxObject在ExportScene03 / MyFbxMesh.h中进行了定义。这些类分别继承自FbxMesh和FbxObject。

#include <fbxsdk.h>
#include "../Common/Common.h"
#include "MyFbxMesh.h"

// ...

int main(int argc, char** argv)
{
    FbxManager* lSdkManager = NULL;
    FbxScene* lScene = NULL;
    // ...

    // Prepare the FBX SDK.
    InitializeSdkObjects(lSdkManager, lScene);

    //Add the new class we have created to the Sdk Manager
    //Our class MyFbxMesh is derived from FbxMesh
    lSdkManager->RegisterFbxClass("MyFbxMesh", FBX_TYPE(MyFbxMesh), FBX_TYPE(FbxMesh));
    //Now, our class MyFbxMesh is ready to be used

    lSdkManager->RegisterFbxClass("MyFbxObject", FBX_TYPE(MyFbxObject), FBX_TYPE(FbxObject), "MyFbxObjectType", "MyFbxObjectSubType");
    // ...

}

4.图层元素的自定义用户数据

  要创建具有自定义类型的图层元素，请使用FbxLayerElementUserData类。像任何其他图层元素一样，它可以按多边形顶点，按顶点，按多边形等进行映射。
  请参考ExportScene03中的CreateCubeWithMaterialAndMyFbxMesh（）函数。此函数基于浮点和布尔数据类型创建自定义化合物，并为每个顶点添加数据。

5.自定义文件格式

  FBX SDK使用多种文件格式导入和导出场景数据。这些文件格式中的每一种都有其自己的writer类（源自FbxWriter）和reader类（源自FbxReader）。要使用自定义的FbxWriter和FbxReader，必须通过FBX SDK I / O插件加载它们。有关更多信息，请参见使用FBX SDK I / O插件自定义文件格式。

6.FBX扩展SDK

  FBX Extensions SDK是一组回调函数，可以在.dll文件中实现。这些功能可自定义3ds Max，Maya和MotionBuilder的导入和导出功能。有关更多信息，请参见FBX Extensions SDK。