应用程序编程接口（API）

插件通过应用程序编程接口（API）实现实现。 每个插件类都有其特定的 API，在 3D 插件教程中，我们已经看到了由标题 “3d_plugin.h” 声明的 3D 插件 API 实现的示例。 插件也可能依赖于 KiCad 源代码树中定义的其他 API; 在 3D 插件的情况下，支持模型可视化的所有插件必须与标题 ‘ifsg_all.h’ 及其包含的标题中声明的 Scene Graph API 交互。

本节描述了插件类实现可能需要的插件类 API 和其他 KiCad API 的详细信息。

插件类 API

目前只有一个为 KiCad 声明的插件类：3D 插件类。 所有 KiCad 插件类都必须实现头文件 ‘kicad_plugin.h’ 中声明的一组基本函数; 这些声明称为 Base Kicad 插件类。 不存在 Base Kicad 插件类的实现; 头文件的存在纯粹是为了确保插件开发人员在每个插件实现中实现这些定义的函数。

在 KiCad 中，插件加载器的每个实例都实现了插件提供的 API，就像插件加载器是提供插件服务的类一样。 这是通过 Plugin 加载器类实现的，该类提供包含与插件实现的类似的函数名的公共接口; 如果例如没有加载插件，则参数列表可以变化以适应向用户通知可能遇到的任何问题的需要。 在内部，插件加载器使用存储的指针指向每个 API 函数，以代表用户调用每个函数。

API：Base Kicad 插件类

Base Kicad 插件类由头文件 ‘kicad_plugin.h’ 定义。 此标头必须包含在所有其他插件类的声明中; 例如，请参阅头文件 ‘3d_plugin.h’ 中的 3D 插件类声明。 这些函数的原型在 《 plugin-classes（插件-类），Plugin Classes（插件类）》 中简要描述。 API 由 “pluginldr.cpp” 中定义的基本插件加载器实现。

为了帮助理解基本 KiCad 插件头所需的功能，我们必须查看基本插件 Loader 类中发生的情况。 Plugin Loader 类声明了一个虚函数 ‘Open()’，它接受要加载的插件的完整路径。 在特定的插件类加载器中实现 ‘Open()’ 函数最初将调用基本插件加载器的受保护的 ‘open()’ 函数; 这个基础 ‘open()’ 函数试图找到每个必需的基本插件函数的地址; 一旦检索到每个函数的地址，就会强制执行一些检查：

1. 调用插件 ‘GetKicadPluginClass()’，并将结果与插件加载器实现提供的插件类字符串进行比较; 如果这些字符串不匹配，则打开的插件不适用于 Plugin Loader 实例。

2. 调用插件 ‘GetClassVersion()’ 来检索插件实现的插件类 API 版本。

3. 插件加载器虚拟 ‘GetLoaderVersion()’ 函数被调用以检索由加载器实现的插件类 API 版本。

4. 插件和加载器报告的插件类 API 版本必须具有相同的主版本号，否则它们被认为是不兼容的。 这是最基本的版本测试，它由基本插件加载器强制执行。

5. 使用插件加载器的插件类 API 版本信息调用插件 ‘CheckClassVersion()’; 如果插件支持给定版本，则返回 “true” 表示成功。 如果成功，加载器根据 ‘GetKicadPluginName()’ 和 ‘GetPluginVersion()’ 的结果创建一个 PluginInfo 字符串，插件加载过程在 Plugin Loader 的 ‘Open()’ 实现中继续。

API：3D 插件类

3D 插件类由头文件 ‘3d_plugin.h’ 声明，它扩展了所需的插件函数，如《class-plugin-3d（类-插件-3d），Plugin Class（插件类）：PLUGIN_3D（插件_3D）》中所述。 相应的插件加载器在 ‘pluginldr3D.cpp’ 中定义，除了所需的 API 函数之外，加载器还实现了以下公共函数：

/* 打开完整路径 "aFullFileName" 指定的插件 */
/* Open the plugin specified by the full path "aFullFileName" */
bool Open( const wxString& aFullFileName );
/* 关闭当前打开的插件 */
/* Close the currently opened plugin */
void Close( void );
/* 检索该插件加载器实现的插件类 API 版本 */
/* Retrieve the Plugin Class API Version implemented by this Plugin Loader */
void GetLoaderVersion( unsigned char* Major, unsigned char* Minor,
    unsigned char* Revision, unsigned char* Patch ) const;

所需的 3D 插件类功能通过以下功能公开：

/* 如果没有加载插件，则返回插件类或 NULL */
/* returns the Plugin Class or NULL if no plugin loaded */
char const* GetKicadPluginClass( void );
/* 如果没有加载插件，则返回 FALSE */
/* returns false if no plugin loaded */
bool GetClassVersion( unsigned char* Major, unsigned char* Minor,
    unsigned char* Patch, unsigned char* Revision );
/* 如果类版本检查失败或未加载插件，则返回 FALSE */
/* returns false if the class version check fails or no plugin is loaded */
bool CheckClassVersion( unsigned char Major, unsigned char Minor,
    unsigned char Patch, unsigned char Revision );
/* 返回插件名称，如果没有加载插件，则返回 NULL */
/* returns the Plugin Name or NULL if no plugin loaded */
const char* GetKicadPluginName( void );
/*
   如果未加载任何插件，则返回 False，否则返回参数。
   包含 GetPluginVersion() 的结果。
*/
/*
   returns false if no plugin is loaded, otherwise the arguments
   contain the result of GetPluginVersion()
 */
bool GetVersion( unsigned char* Major, unsigned char* Minor,
    unsigned char* Patch, unsigned char* Revision );
/*
   如果没有加载插件，则将 aPluginInfo 设置为空字符串，
   否则，将 aPluginInfo 设置为以下形式的字符串：
   [名称]：[主要].[次要].[修补程序].[修订版本]其中。
   name = 由 GetKicadPluginClass() 提供的名称。
   主要、次要、修补程序、修订=版本信息来自。
   GetPluginVersion()。
*/
/*
   sets aPluginInfo to an empty string if no plugin is loaded,
   otherwise aPluginInfo is set to a string of the form:
   [NAME]:[MAJOR].[MINOR].[PATCH].[REVISION] where
   NAME = name provided by GetKicadPluginClass()
   MAJOR, MINOR, PATCH, REVISION = version information from
   GetPluginVersion()
 */
void GetPluginInfo( std::string& aPluginInfo );

在典型情况下，用户将执行以下操作：

1. 创建 ‘KICAD_PLUGIN_LDR_3D’ 的实例。

2. 调用 ‘Open(“/path/to/myplugin.so”)’ 来打开一个特定的插件。 必须检查返回值以确保根据需要加载插件。

3. 调用由 ‘KICAD_PLUGIN_LDR_3D’ 公开的任何 3D 插件类调用。

4. 调用 ‘Close()’来关闭（取消链接）插件。

5. 销毁 ‘KICAD_PLUGIN_LDR_3D’ 实例。

场景图类 API

Scenegraph 类 API 由标题 ‘ifsg_all.h’ 及其包含的标题定义。 API 由许多辅助例程组成，命名空间为 ‘S3D’，在 ‘ifsg_api.h’ 中定义，包装类由各种 ‘ifsg_*.h’ 标题定义; 包装器支持底层的场景图类，它们一起形成一个与 VRML2.0 静态场景图兼容的场景图结构。 标题，结构，类及其公共函数如下：

sg_version.h

/*
   定义 SceneGraph 类的版本信息。
   所有使用 Scenegraph 类的插件都应该包含这个头。
   并对照所报告的版本检查版本信息。
   S3D::GetLibVersion() 以确保兼容性。
*/
/*
   Defines version information of the SceneGraph Classes.
   All plugins which use the scenegraph class should include this header
   and check the version information against the version reported by
   S3D::GetLibVersion() to ensure compatibility
 */
#define KICADSG_VERSION_MAJOR         2
#define KICADSG_VERSION_MINOR         0
#define KICADSG_VERSION_PATCH         0
#define KICADSG_VERSION_REVISION      0

sg_types.h

/*
   定义 SceneGraph 类类型；这些类型。
   与 VRML2.0 节点类型密切相关。
*/
/*
   Defines the SceneGraph Class Types; these types
   are closely related to VRML2.0 node types.
 */
namespace S3D
{
    enum SGTYPES
    {
        SGTYPE_TRANSFORM = 0,
        SGTYPE_APPEARANCE,
        SGTYPE_COLORS,
        SGTYPE_COLORINDEX,
        SGTYPE_FACESET,
        SGTYPE_COORDS,
        SGTYPE_COORDINDEX,
        SGTYPE_NORMALS,
        SGTYPE_SHAPE,
        SGTYPE_END
    };
};

‘sg_base.h’ 头包含 scenegraph 类使用的基本数据类型的声明。

sg_base.h

/*
   这是相当于 VRML2.0 的 RGB 颜色模型。
   RGB 模型，其中每种颜色可能在。
   范围 [0..1]。
*/
/*
    This is an RGB color model equivalent to the VRML2.0
    RGB model where each color may have a value within the
    range [0..1].
 */
class SGCOLOR
{
public:
    SGCOLOR();
    SGCOLOR( float aRVal, float aGVal, float aBVal );
    void GetColor( float& aRedVal, float& aGreenVal, float& aBlueVal ) const;
    void GetColor( SGCOLOR& aColor ) const;
    void GetColor( SGCOLOR* aColor ) const;
    bool SetColor( float aRedVal, float aGreenVal, float aBlueVal );
    bool SetColor( const SGCOLOR& aColor );
    bool SetColor( const SGCOLOR* aColor );
};
class SGPOINT
{
public:
    double x;
    double y;
    double z;
public:
    SGPOINT();
    SGPOINT( double aXVal, double aYVal, double aZVal );
    void GetPoint( double& aXVal, double& aYVal, double& aZVal );
    void GetPoint( SGPOINT& aPoint );
    void GetPoint( SGPOINT* aPoint );
    void SetPoint( double aXVal, double aYVal, double aZVal );
    void SetPoint( const SGPOINT& aPoint );
};
/*
   SGVECTOR 有 3 个分量(x，y，z)类似于一个点；但是。
   向量确保存储的值是规范化的，并且。
   防止直接操作组件变量。
*/
/*
    A SGVECTOR has 3 components (x,y,z) similar to a point; however
    a vector ensures that the stored values are normalized and
    prevents direct manipulation of the component variables.
 */
class SGVECTOR
{
public:
    SGVECTOR();
    SGVECTOR( double aXVal, double aYVal, double aZVal );
    void GetVector( double& aXVal, double& aYVal, double& aZVal ) const;
    void SetVector( double aXVal, double aYVal, double aZVal );
    void SetVector( const SGVECTOR& aVector );
    SGVECTOR& operator=( const SGVECTOR& source );
};

‘IFSG_NODE’ 类是所有场景图节点的基类。 所有 scenegraph 对象都实现此类的公共函数，但在某些情况下，特定函数可能对特定类没有意义。

ifsg_node.h

class IFSG_NODE
{
public:
    IFSG_NODE();
    virtual ~IFSG_NODE();
    /**
     * 功能销毁。
     * 删除此包装器持有的 Scenegraph 对象。
     */
    /**
     * Function Destroy
     * deletes the scenegraph object held by this wrapper
     */
    void Destroy( void );
    /**
     * 函数附加。
     * 将给定S GNODE* 与此包装器关联。
     */
    /**
     * Function Attach
     * associates a given SGNODE* with this wrapper
     */
    virtual bool Attach( SGNODE* aNode ) = 0;
    /**
     * 函数 NewNode。
     * 创建与此包装器关联的新节点。
     */
    /**
     * Function NewNode
     * creates a new node to associate with this wrapper
     */
    virtual bool NewNode( SGNODE* aParent ) = 0;
    virtual bool NewNode( IFSG_NODE& aParent ) = 0;
    /**
     * 函数 GetRawPtr()。
     * 返回原始内部SGNODE指针。
     */
    /**
     * Function GetRawPtr()
     * returns the raw internal SGNODE pointer
     */
    SGNODE* GetRawPtr( void );
    /**
     * 函数 GetNodeType。
     * 返回此节点实例的类型。
     */
    /**
     * Function GetNodeType
     * returns the type of this node instance
     */
    S3D::SGTYPES GetNodeType( void ) const;
    /**
     * 函数 GetParent。
     * 返回指向此对象的父 SGNODE 的指针。
     * 如果对象没有父对象，则为 NULL(即 顶级变换)。
     * 或者如果包装器当前未与 SGNODE 关联。
     */
    /**
     * Function GetParent
     * returns a pointer to the parent SGNODE of this object
     * or NULL if the object has no parent (ie. top level transform)
     * or if the wrapper is not currently associated with an SGNODE.
     */
    SGNODE* GetParent( void ) const;
    /**
     * 函数 SetParent。
     * 设置此对象的父 SGNODE。
     *
     * @param aParent [in] 是所需的父节点。
     * @return 如果操作成功，则返回 true；如果操作成功，则返回 false。
     * 给定节点不允许为父节点。
     * 派生对象。
     */
    /**
     * Function SetParent
     * sets the parent SGNODE of this object.
     *
     * @param aParent [in] is the desired parent node
     * @return true if the operation succeeds; false if
     * the given node is not allowed to be a parent to
     * the derived object.
     */
    bool SetParent( SGNODE* aParent );
    /**
     * 函数 GetNodeTypeName。
     * 返回节点类型的文本表示。
     * 如果节点不知何故具有无效类型，则为 NULL。
     */
    /**
     * Function GetNodeTypeName
     * returns the text representation of the node type
     * or NULL if the node somehow has an invalid type
     */
    const char * GetNodeTypeName( S3D::SGTYPES aNodeType ) const;
    /**
     * 函数 AddRefNode。
     * 添加对不属于的现有节点的引用。
     * (不是此节点的子节点)。
     *
     * @return 成功返回 true。
     */
    /**
     * Function AddRefNode
     * adds a reference to an existing node which is not owned by
     * (not a child of) this node.
     *
     * @return true on success
     */
    bool AddRefNode( SGNODE* aNode );
    bool AddRefNode( IFSG_NODE& aNode );
    /**
     * 函数 AddChildNode。
     * 添加一个节点作为此节点拥有的子节点。
     *
     * @return 成功返回 true。
     */
    /**
     * Function AddChildNode
     * adds a node as a child owned by this node.
     *
     * @return true on success
     */
    bool AddChildNode( SGNODE* aNode );
    bool AddChildNode( IFSG_NODE& aNode );
};

‘IFSG_TRANSFORM’ 类似于 VRML2.0 Transform 节点; 它可以包含任意数量的子 IFSG_SHAPE 和 IFSG_TRANSFORM 节点以及任意数量的引用的 IFSG_SHAPE 和 IFSG_TRANSFORM 节点。 有效的场景图必须有一个 “IFSG_TRANSFORM” 对象作为根。

ifsg_transform.h

/**
 * IFSG_Transform 类。
 *是 VRML 兼容转换块类 SCENEGRAPH 的包装。
 */
/**
 * Class IFSG_TRANSFORM
 * is the wrapper for the VRML compatible TRANSFORM block class SCENEGRAPH
 */
class IFSG_TRANSFORM : public IFSG_NODE
{
public:
    IFSG_TRANSFORM( bool create );
    IFSG_TRANSFORM( SGNODE* aParent );
    bool SetScaleOrientation( const SGVECTOR& aScaleAxis, double aAngle );
    bool SetRotation( const SGVECTOR& aRotationAxis, double aAngle );
    bool SetScale( const SGPOINT& aScale );
    bool SetScale( double aScale );
    bool SetCenter( const SGPOINT& aCenter );
    bool SetTranslation( const SGPOINT& aTranslation );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
};

‘IFSG_SHAPE’ 类似于 VRML2.0 Shape 节点; 它必须包含单个子节点或引用 FACESET 节点，并且可以包含单个子节点或引用 APPEARANCE 节点。

ifsg_shape.h

/**
 * IFSG_SHAP E类。
 * 是 SGSHAPE 类的包装。
 */
/**
 * Class IFSG_SHAPE
 * is the wrapper for the SGSHAPE class
 */
class IFSG_SHAPE : public IFSG_NODE
{
public:
    IFSG_SHAPE( bool create );
    IFSG_SHAPE( SGNODE* aParent );
    IFSG_SHAPE( IFSG_NODE& aParent );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
};

‘IFSG_APPEARANCE’ 类似于 VRML2.0 Appearance 节点，但目前它只代表包含 Material 节点的 Appearance 节点的等价物。

ifsg_appearance.h

class IFSG_APPEARANCE : public IFSG_NODE
{
public:
    IFSG_APPEARANCE( bool create );
    IFSG_APPEARANCE( SGNODE* aParent );
    IFSG_APPEARANCE( IFSG_NODE& aParent );
    bool SetEmissive( float aRVal, float aGVal, float aBVal );
    bool SetEmissive( const SGCOLOR* aRGBColor );
    bool SetEmissive( const SGCOLOR& aRGBColor );
    bool SetDiffuse( float aRVal, float aGVal, float aBVal );
    bool SetDiffuse( const SGCOLOR* aRGBColor );
    bool SetDiffuse( const SGCOLOR& aRGBColor );
    bool SetSpecular( float aRVal, float aGVal, float aBVal );
    bool SetSpecular( const SGCOLOR* aRGBColor );
    bool SetSpecular( const SGCOLOR& aRGBColor );
    bool SetAmbient( float aRVal, float aGVal, float aBVal );
    bool SetAmbient( const SGCOLOR* aRGBColor );
    bool SetAmbient( const SGCOLOR& aRGBColor );
    bool SetShininess( float aShininess );
    bool SetTransparency( float aTransparency );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
    /* 以下函数在。
       外观节点，并始终返回失败代码
    /* the following functions make no sense within an
       appearance node and always return a failure code
        bool AddRefNode( SGNODE* aNode );
        bool AddRefNode( IFSG_NODE& aNode );
        bool AddChildNode( SGNODE* aNode );
        bool AddChildNode( IFSG_NODE& aNode );
     */
};

‘IFSG_FACESET’ 类似于包含 IndexedFaceSet 节点的 VRML2.0 Geometry 节点。 它必须包含单个子节点或引用 COORDS 节点，单个子 COORDINDEX 节点以及单个子节点或引用 NORMALS 节点; 另外可能有一个子节点或引用 COLORS 节点。 提供简化的法线计算功能以帮助用户将正常值分配给表面。 与 VRML2.0 模拟的偏差如下：

1. 法线始终是每个顶点。

2. 颜色总是每个顶点。

3. 坐标索引集必须仅描述三角形面。

ifsg_faceset.h

/**
 * IFSG_FACESET 类。
 * 是 SGFACESET 类的包装。
 */
/**
 * Class IFSG_FACESET
 * is the wrapper for the SGFACESET class
 */
class IFSG_FACESET : public IFSG_NODE
{
public:
    IFSG_FACESET( bool create );
    IFSG_FACESET( SGNODE* aParent );
    IFSG_FACESET( IFSG_NODE& aParent );
    bool CalcNormals( SGNODE** aPtr );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
};

ifsg_coords.h

/**
 * IFSG_COORDS 类别。
 * 是 SGCOORDS 的包装器。
 */
/**
 * Class IFSG_COORDS
 * is the wrapper for SGCOORDS
 */
class IFSG_COORDS : public IFSG_NODE
{
public:
    IFSG_COORDS( bool create );
    IFSG_COORDS( SGNODE* aParent );
    IFSG_COORDS( IFSG_NODE& aParent );
    bool GetCoordsList( size_t& aListSize, SGPOINT*& aCoordsList );
    bool SetCoordsList( size_t aListSize, const SGPOINT* aCoordsList );
    bool AddCoord( double aXValue, double aYValue, double aZValue );
    bool AddCoord( const SGPOINT& aPoint );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
    /* 以下函数在。
       协调节点并始终返回失败代码
    /* the following functions make no sense within a
       coords node and always return a failure code
        bool AddRefNode( SGNODE* aNode );
        bool AddRefNode( IFSG_NODE& aNode );
        bool AddChildNode( SGNODE* aNode );
        bool AddChildNode( IFSG_NODE& aNode );
     */
};

‘IFSG_COORDINDEX’ 类似于 VRML2.0 coordIdx[] 集，除了它必须专门描述三角形面，这意味着索引的总数可以被 3 整除。

ifsg_coordindex.h

/**
 * IFSG_COORDINDEX 类。
 * 是 SGCOORDINDEX 的包装。
 */
/**
 * Class IFSG_COORDINDEX
 * is the wrapper for SGCOORDINDEX
 */
class IFSG_COORDINDEX : public IFSG_INDEX
{
public:
    IFSG_COORDINDEX( bool create );
    IFSG_COORDINDEX( SGNODE* aParent );
    IFSG_COORDINDEX( IFSG_NODE& aParent );
    bool GetIndices( size_t& nIndices, int*& aIndexList );
    bool SetIndices( size_t nIndices, int* aIndexList );
    bool AddIndex( int aIndex );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
    /* 以下函数在。
       协调节点并始终返回失败代码
    /* the following functions make no sense within a
       coordindex node and always return a failure code
        bool AddRefNode( SGNODE* aNode );
        bool AddRefNode( IFSG_NODE& aNode );
        bool AddChildNode( SGNODE* aNode );
        bool AddChildNode( IFSG_NODE& aNode );
     */
};

‘IFSG_NORMALS’ 相当于 VRML2.0 Normals 节点。

ifsg_normals.h

/**
 * IFSG_Normal 类。
 * 是 SGNORMALS 类的包装。
 */
/**
 * Class IFSG_NORMALS
 * is the wrapper for the SGNORMALS class
 */
class IFSG_NORMALS : public IFSG_NODE
{
public:
    IFSG_NORMALS( bool create );
    IFSG_NORMALS( SGNODE* aParent );
    IFSG_NORMALS( IFSG_NODE& aParent );
    bool GetNormalList( size_t& aListSize, SGVECTOR*& aNormalList );
    bool SetNormalList( size_t aListSize, const SGVECTOR* aNormalList );
    bool AddNormal( double aXValue, double aYValue, double aZValue );
    bool AddNormal( const SGVECTOR& aNormal );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
    /* 以下函数在。
       法线节点并始终返回失败代码
    /* the following functions make no sense within a
       normals node and always return a failure code
        bool AddRefNode( SGNODE* aNode );
        bool AddRefNode( IFSG_NODE& aNode );
        bool AddChildNode( SGNODE* aNode );
        bool AddChildNode( IFSG_NODE& aNode );
     */
};

‘IFSG_COLORS’ 类似于 VRML2.0 colors[] 集。

ifsg_colors.h

/**
 * IFSG_COLOR 类。
 * 是 SGCOLORS 的包装器。
 */
/**
 * Class IFSG_COLORS
 * is the wrapper for SGCOLORS
 */
class IFSG_COLORS : public IFSG_NODE
{
public:
    IFSG_COLORS( bool create );
    IFSG_COLORS( SGNODE* aParent );
    IFSG_COLORS( IFSG_NODE& aParent );
    bool GetColorList( size_t& aListSize, SGCOLOR*& aColorList );
    bool SetColorList( size_t aListSize, const SGCOLOR* aColorList );
    bool AddColor( double aRedValue, double aGreenValue, double aBlueValue );
    bool AddColor( const SGCOLOR& aColor );
    /* 此处未显示的各种基类函数 */
    /* various base class functions not shown here */
    /* 以下函数在。
       法线节点并始终返回失败代码
    /* the following functions make no sense within a
       normals node and always return a failure code
        bool AddRefNode( SGNODE* aNode );
        bool AddRefNode( IFSG_NODE& aNode );
        bool AddChildNode( SGNODE* aNode );
        bool AddChildNode( IFSG_NODE& aNode );
     */
};

其余的 API 函数在 ‘ifsg_api.h’ 中定义如下：

ifsg_api.h

namespace S3D
{
    /**
     * 函数 GetLibVersion 检索。
     * kicad_3dsg 库。
     */
    /**
     * Function GetLibVersion retrieves version information of the
     * kicad_3dsg library
     */
    SGLIB_API void GetLibVersion( unsigned char* Major, unsigned char* Minor,
                                  unsigned char* Patch, unsigned char* Revision );
    //从 SGNODE 指针提取信息的函数
    // functions to extract information from SGNODE pointers
    SGLIB_API S3D::SGTYPES GetSGNodeType( SGNODE* aNode );
    SGLIB_API SGNODE* GetSGNodeParent( SGNODE* aNode );
    SGLIB_API bool AddSGNodeRef( SGNODE* aParent, SGNODE* aChild );
    SGLIB_API bool AddSGNodeChild( SGNODE* aParent, SGNODE* aChild );
    SGLIB_API void AssociateSGNodeWrapper( SGNODE* aObject, SGNODE** aRefPtr );
    /**
     * 函数 CalcTriNorm
     * 返回顶点 p1，p2，p3 描述的三角形的法向量。
     */
    /**
     * Function CalcTriNorm
     * returns the normal vector of a triangle described by vertices p1, p2, p3
     */
    SGLIB_API SGVECTOR CalcTriNorm( const SGPOINT& p1, const SGPOINT& p2, const SGPOINT& p3 );
    /**
     * 函数 WriteCache
     * 将 SGNODE 树写入二进制缓存文件。
     *
     * @param aFileName 是要写入的文件的名称。
     * @param overwrite 必须设置为 true 才能覆盖现有文件。
     * @param 阳极是要写入的节点树中的任何节点。
     * @return 成功返回 true。
     */
    /**
     * Function WriteCache
     * writes the SGNODE tree to a binary cache file
     *
     * @param aFileName is the name of the file to write
     * @param overwrite must be set to true to overwrite an existing file
     * @param aNode is any node within the node tree which is to be written
     * @return true on success
     */
    SGLIB_API bool WriteCache( const char* aFileName, bool overwrite, SGNODE* aNode,
        const char* aPluginInfo );
    /**
     * 函数 ReadCache
     * 读取二进制缓存文件并创建 SGNODE 树。
     *
     * @param aFileName 是要读取的二进制缓存文件的名称。
     * @return 失败返回 NULL，成功返回顶层 SCENEGRAPH 节点指针；
     * 如果需要，此节点可以通过以下方式与 IFSG_Transform 包装器关联。
     * IFSG_Transform::Attach() 函数。
     */
    /**
     * Function ReadCache
     * reads a binary cache file and creates an SGNODE tree
     *
     * @param aFileName is the name of the binary cache file to be read
     * @return NULL on failure, on success a pointer to the top level SCENEGRAPH node;
     * if desired this node can be associated with an IFSG_TRANSFORM wrapper via
     * the IFSG_TRANSFORM::Attach() function.
     */
    SGLIB_API SGNODE* ReadCache( const char* aFileName, void* aPluginMgr,
        bool (*aTagCheck)( const char*, void* ) );
    /**
     * 函数 WriteVRML
     * 将给定节点及其子节点写出到 VRML2 文件。
     *
     * @param filename 是输出文件的名称。
     * @param overwrite 应设置为 true 以覆盖现有 VRML 文件。
     * @param aTopNode 是指向代表 VRML 场景的 SCENEGRAPH 对象的指针。
     * @param reuse 应设置为 true 以使用 VRML DEF/USE 功能。
     * @return 成功返回 true。
     */
    /**
     * Function WriteVRML
     * writes out the given node and its subnodes to a VRML2 file
     *
     * @param filename is the name of the output file
     * @param overwrite should be set to true to overwrite an existing VRML file
     * @param aTopNode is a pointer to a SCENEGRAPH object representing the VRML scene
     * @param reuse should be set to true to make use of VRML DEF/USE features
     * @return true on success
     */
    SGLIB_API bool WriteVRML( const char* filename, bool overwrite, SGNODE* aTopNode,
                    bool reuse, bool renameNodes );
    // 注意：以下函数组合用于创建 VRML。
    // 组装，可以使用模块的每个 SG* 表示的各种实例。
    // 典型的用例是：
    // 1.调用 ‘ResetNodeIndex()’ 重置全局节点名索引。
    // 2.对于 ‘S3DCACHE->load()’ 提供的每个模型指针，调用一次 ‘RenameNodes()’；
    //    这可确保所有节点都有唯一的名称以呈现给最终输出文件。
    //    内部 RenameNodes() 只重命名给定节点和所有子节点；
    //    仅被引用的节点不会被重命名。使用提供的指针。
    //    通过 ‘S3DCACHE->load()’ 确保除了返回的节点(顶层节点)之外的所有节点都是。
    //    至少一个节点的子节点，因此所有节点都有唯一的名称。
    // 3.如果 SG* 树是独立于 S3DCACHE 创建的 -> load()，则用户必须调用。
    //    RenameNodes() 以确保所有节点都具有唯一的名称。
    // 4.根据需要创建新的 ifsg_transform 节点来创建程序集结构。
    //    对于组件的每个实例；由返回的组件基础模型。
    //    S3DCACHE->load() 可以通过 ‘AddRefNode()’ 添加到这些 IFSG_Transform 节点；
    //    设置 IFSG_Transform 节点的偏移、旋转等，确保正确。
    // 5.确保所有新的 IFSG_Transform 节点都作为子节点放置在。
    //    顶层 IFSG_Transform 节点，为最终节点命名和输出做准备。
    // 6.在顶层组装节点上调用 RenameNodes()。
    // 7.正常调用 WriteVRML()，renameNodes=false，写入整个程序集。
    //    结构转换为单个 VRML 文件。
    // 8.通过删除任何额外的 IFSG_Transform 包装器及其底层 SG* 进行清理。
    //    专门为程序集输出创建的类
    // NOTE: The following functions are used in combination to create a VRML
    // assembly which may use various instances of each SG* representation of a module.
    // A typical use case would be:
    // 1. invoke 'ResetNodeIndex()' to reset the global node name indices
    // 2. for each model pointer provided by 'S3DCACHE->Load()', invoke 'RenameNodes()' once;
    //    this ensures that all nodes have a unique name to present to the final output file.
    //    Internally, RenameNodes() will only rename the given node and all Child subnodes;
    //    nodes which are only referenced will not be renamed. Using the pointer supplied
    //    by 'S3DCACHE->Load()' ensures that all nodes but the returned node (top node) are
    //    children of at least one node, so all nodes are given unique names.
    // 3. if SG* trees are created independently of S3DCACHE->Load() the user must invoke
    //    RenameNodes() as appropriate to ensure that all nodes have a unique name
    // 4. create an assembly structure by creating new IFSG_TRANSFORM nodes as appropriate
    //    for each instance of a component; the component base model as returned by
    //    S3DCACHE->Load() may be added to these IFSG_TRANSFORM nodes via 'AddRefNode()';
    //    set the offset, rotation, etc of the IFSG_TRANSFORM node to ensure correct
    // 5. Ensure that all new IFSG_TRANSFORM nodes are placed as child nodes within a
    //    top level IFSG_TRANSFORM node in preparation for final node naming and output
    // 6. Invoke RenameNodes() on the top level assembly node
    // 7. Invoke WriteVRML() as normal, with renameNodes = false, to write the entire assembly
    //    structure to a single VRML file
    // 8. Clean up by deleting any extra IFSG_TRANSFORM wrappers and their underlying SG*
    //    classes which have been created solely for the assembly output
    /**
     * 函数 ResetNodeIndex
     * 重置全局 SG* 类索引。
     *
     *@param 阳极可以是任何有效的 SGNODE。
     */
    /**
     * Function ResetNodeIndex
     * resets the global SG* class indices
     *
     * @param aNode may be any valid SGNODE
     */
    SGLIB_API void ResetNodeIndex( SGNODE* aNode );
    /**
     * 函数 RenameNodes
     * 根据当前重命名节点和所有子节点。
     * 全局 SG* 的值类别索引。
     *
     * @param 阳极是顶层节点。
     */
    /**
     * Function RenameNodes
     * renames a node and all children nodes based on the current
     * values of the global SG* class indices
     *
     * @param aNode is a top level node
     */
    SGLIB_API void RenameNodes( SGNODE* aNode );
    /**
     * 函数 DestroyNode。
     * 删除给定 SG* 类节点。此功能使其成为可能。
     * 安全删除 SG* 节点而不将节点与关联。
     * 其对应的 IFSG* 包装器。
     */
    /**
     * Function DestroyNode
     * deletes the given SG* class node. This function makes it possible
     * to safely delete an SG* node without associating the node with
     * its corresponding IFSG* wrapper.
     */
    SGLIB_API void DestroyNode( SGNODE* aNode );
    // 注意：以下函数便于创建和销毁。
    // 用于呈现的数据结构
    // NOTE: The following functions facilitate the creation and destruction
    // of data structures for rendering
    /**
     * 函数 GetModel
     * 创建阳极的 S3DMODEL 表示 (原始数据，无转换)。
     *
     * @param 阳极是要转录为 S3DMODEL 表示的节点。
     * @return 成功时返回阳极的 S3DMODEL 表示，否则为 NULL。
     */
    /**
     * Function GetModel
     * creates an S3DMODEL representation of aNode (raw data, no transforms)
     *
     * @param aNode is the node to be transcribed into an S3DMODEL representation
     * @return an S3DMODEL representation of aNode on success, otherwise NULL
     */
    SGLIB_API S3DMODEL* GetModel( SCENEGRAPH* aNode );
    /**
     * 函数 Destroy3DModel
     * 释放 S3DMODEL 结构使用的内存并将指针设置为。
     * 结构为 NULL。
     */
    /**
     * Function Destroy3DModel
     * frees memory used by an S3DMODEL structure and sets the pointer to
     * the structure to NULL
     */
    SGLIB_API void Destroy3DModel( S3DMODEL** aModel );
    /**
     * 函数 Free3DModel
     * 释放由 S3DMODEL 结构内部使用的内存。
     */
    /**
     * Function Free3DModel
     * frees memory used internally by an S3DMODEL structure
     */
    SGLIB_API void Free3DModel( S3DMODEL& aModel );
    /**
     * 函数 Free3DMesh
     * 释放 SMESH 结构内部使用的内存。
     */
    /**
     * Function Free3DMesh
     * frees memory used internally by an SMESH structure
     */
    SGLIB_API void Free3DMesh( SMESH& aMesh );
    /**
     * 函数 New3DModel
     * 创建并初始化 S3DMODEL 结构。
     */
    /**
     * Function New3DModel
     * creates and initializes an S3DMODEL struct
     */
    SGLIB_API S3DMODEL* New3DModel( void );
    /**
     * 函数 Init3DMaterial
     * 初始化 SMATERIAL 结构。
     */
    /**
     * Function Init3DMaterial
     * initializes an SMATERIAL struct
     */
    SGLIB_API void Init3DMaterial( SMATERIAL& aMat );
     /**
     * 函数 Init3DMesh
     * 创建并初始化 SMESH 结构。
     */
    /**
     * Function Init3DMesh
     * creates and initializes an SMESH struct
     */
    SGLIB_API void Init3DMesh( SMESH& aMesh );
};

有关 Scenegraph API 的实际使用示例，请参阅上面的《advanced-3d-plugin（高级-3d-插件）,Advanced 3D Plugin tutorial（高级 3D 插件教程）》，以及 KiCad VRML1，VRML2 和 X3D 解析器。