Cocos 中的自动绑定

分类：Cocos2d-x作者：编程之家用户

Cocos 中的自动绑定

Cocos 中的自动绑定依赖于 Bindings Generator 工具，这个 python 工具通过配置文件来解析需要绑定的类的头文件，并且按照一定规则生成类的 API 的绑定代码。


Bindings Generator

Bindings Generator 工具是自动绑定的核心工具，它可以将 C++ 类的公共方法和公共属性绑定到脚本层。自动绑定工具非常强大，不过它还是有以下几个限制：

1. 只能够针对类生成绑定，不可以绑定结构体，独立函数等。

2. 不能够生成 Delegate 类型的 API，因为脚本中的对象是无法继承 C++ 中的 Delegate 类并重写其中的 Delegate 函数的。

3. 子类中重写了父类的 API 的同时，又重载了这个 API。

4. 部分 API 实现内容并没有完全体现在其 API 定义中。

5. 在运行时由 C++ 主动调用的 API。

也就是说，除了这几种情况以外，都可以通过自动绑定工具将 C++ 类绑定到脚本层。


配置环境

# Mac OS X 环境配置

  • Mac OS X 中默认包含 Python 2.7，如果你的机器上不包含 Python，可以通过其他方式:
  • 通过 pip 安装其他 Python 依赖库
    sudo easy_install pip
    sudo pip install PyYAML
    sudo pip install Cheetah
  • 从 Google 下载NDKr9d+
  • 在 `~/.bash_profile` 中设置 `PYTHON_ROOT` 和 `NDK_ROOT` 环境变量

# Windows环境配置

  • 下载并安装Python 2.7
  • 添加 Python 的安装路径（e.g. C:\Python27）到 windows 的 `PATH` 环境变量中
  • 下载并安装pyyaml
  • 下载pyCheetah并解压到 Python 路径下的 `Lib\site-packages`
  • 从 Google 下载 64bitNDKr9d+
  • 设置 `PYTHON_ROOT` 和 `NDK_ROOT` 环境变量

至此绑定工具的基本环境已经配置成功。


基本原理

自动绑定工具最核心的工作原理是通过 libclang 分析 C++ 头文件，以一定的绑定规则和绑定代码模版，针对 C++ 类的公共方法和属性一一对应生成每个方法的绑定代码和每个属性的 Getter/Setter 方法。下面让我们用倒推法来分析这个过程：

# 绑定结果

最终，自动绑定的结果是一个 C++ 文件和一个头文件，其中包含：

  1. 所有 API 的绑定函数，用于桥接脚本环境中的 API 和 C++ API，在脚本层调用相应 API 的时候，实际调用的是绑定函数，并由绑定函数转发调用 C++ API。
  2. C++ 类的绑定函数，用于在脚本环境中创建对应的类，它会将所有 API 的绑定函数注册到脚本类中，这样脚本中调用这些 API 就会调用到绑定函数。
  3. 用来注册所有绑定的函数，这个函数中会调用 C++ 类的绑定函数，调用这个注册函数会让这些 C++ 类被实际注册到脚本环境中。

# 注册和调用过程

以 `Node::setOpacity` 为例，可以在 `cocos2d-x/cocos/scripting/js-bindings/auto/jsb_cocos2dx_auto.cpp` 中找到它的 JavaScript 绑定代码。

上面所描述的注册过程如下：


再来看 `js_cocos2dx_Node_setOpacity` 的实现：

bool js_cocos2dx_Node_setOpacity(JSContext *cx, uint32_t argc, jsval *vp)
{
    // 1. 通过SpiderMonkey API获取脚本层传入的所有参数
    JS::CallArgs args = JS::CallArgsFromVp(argc, vp);
    bool ok = true;
    // 2. 通过SpiderMonkey API获取本次调用的脚本层调用者对象
    JS::RootedObject obj(cx, args.thisv().toObjectOrNull());
    js_proxy_t *proxy = jsb_get_js_proxy(obj);
    // 3. 转换脚本层调用对象为其对应的C++对象
    cocos2d::Node* cobj = (cocos2d::Node *)(proxy ? proxy->ptr : NULL);
    JSB_PRECONDITION2( cobj, cx, false, "js_cocos2dx_Node_setOpacity : Invalid Native Object");
    if (argc == 1) {
        uint16_t arg0;
        // 4. 转换脚本层传入的参数对象为C++值或对象
        ok &= jsval_to_uint16(cx, args.get(0), &arg0);
        JSB_PRECONDITION2(ok,34)">"js_cocos2dx_Node_setOpacity : Error processing arguments");
        // 5. 最终使用转换过的参数调用实际的C++ API
        cobj->setOpacity(arg0);
        // 6. 设置脚本层函数调用的返回值
        args.rval().setUndefined();
        return true;
    }


    JS_ReportError(cx,34)">"js_cocos2dx_Node_setOpacity : wrong number of arguments: %d,was expecting %d", argc, 1);
    return false;
}

代码中通过注释标注了一个绑定函数调用时的完整步骤：


可以看出，整个过程实际上就是在 C++ 和脚本层之间进行对象的转换，并转发脚本层函数调用到 C++ 层的过程。所有 API 的绑定，不论其实现多复杂，都是这样的一个过程。


# 分析 C++ 头文件

为了绑定出这样的结果，必须要对 C++ 头文件进行分析，然后对 C++ 类的 API 一一生成绑定代码。自动绑定工具使用 libclang 的 python API 对 C++ 头文件进行语法分析。绑定的过程大致如下：

  1. 创建绑定代码输出文件。
  2. 递归扫描需要绑定的头文件。
  3. 通过 libclang 的 clang.cindex python 模块找到所有需要绑定的类，公共 API 等。
  4. 按照模版生成类绑定函数，API 绑定函数，绑定注册函数并输出到文件中。

# 绑定规则和绑定模版

当然，绑定过程并不是不可控的，其实有很多可定制的规则是通过自动绑定的配置文件来配置的。有了这些配置，开发者就可以选择绑定的具体内容和方式。其中可定制的重要属性如下：

  1. target_namespace：脚本中的目标命名空间，比如 cc,spine 等。
  2. clang_flags：clang 标签，其中可以添加预编译宏。
  3. macro_judgement：将绑定出的绑定代码包裹在一个条件编译块中，避免由预编译宏控制的 API 被绑定导致的编译问题。
  4. headers：需要被绑定的头文件列表，以空格分隔，头文件将被递归扫描。
  5. cpp_headers：绑定代码需要包含但是不需要被绑定工具扫描的头文件列表。
  6. classes：需要被绑定的类名列表，以空格分隔。
  7. classes_need_extend：需要在脚本层被继承的类列表，以空格分隔。
  8. skip：需要忽略的 API 列表，格式为 `ClassName::[api1 api2]`，不同的类以逗号分隔。
  9. rename_functions：需要被重命名的函数，会将 C++ 中的函数绑定为指定名字的脚本函数，格式为 `ClassName::[cppFunctionName=scriptFunctionName ...]`，不同的类以逗号分隔。
  10. rename_classes：需要被重命名的类，会将 C++ 中的类名绑定为指定的脚本类名，格式为 `CppClassName::ScriptClassName`，以逗号分割。
  11. classes_have_no_parents：没有父类的类列表，以空格分隔。
  12. abstract_classes：没有构造函数的类列表，以空格分隔。

有了这些配置之后，自动绑定工具就知道哪些 API 要被绑定和以什么样的方式绑定。不过，还需要配合各种 API 的绑定代码模版才可以真正生成各种 API 的绑定函数。对于每一个特定的模版，它会读取 clang.cindex 解析出的类或 API 定义信息以及绑定配置信息，生成特定 API 的绑定代码。下面是目前自动绑定工具中的模版：

  1. 头文件和 cpp 文件的头部代码模版
  2. 头文件和 cpp 文件的尾部代码模版
  3. 头文件内容模版，包含脚本层类对象声明，原型对象声明和 API 绑定函数声明
  4. 类绑定函数模版
  5. 构造函数的绑定函数模版
  6. 静态函数的绑定函数模版
  7. 重载的静态函数的绑定函数模版
  8. 公共属性的绑定函数模版
  9. 公共方法的绑定函数模版
  10. 重载的公共方法的绑定函数模版
  11. lambda 函数的绑定函数模版

# 转换函数

从上文的调用过程中可以看出，脚本层和 C++ 层的对象转换非常重要，而这个转换并不是自动的，自动绑定工具无法知道如何在各种 C++ 类型和脚本类型之间进行转换。这里没有任何捷径和魔法，所有类型的转换都必须使用脚本引擎的 C++ API 来完成转换。

这里就要提到转换函数了，对于核心引擎模块中的类型，C++ 和 JS 对象的互相转换函数在引擎目录下 `cocos/scripting/js-bindings/manual/js_manual_conversions.h` 中可以找到，C++ 和 Lua 对象的互相转换函数在引擎目录下 `cocos/scripting/lua-bindings/manual/LuaBasicConversions.h` 中。

以 JS 为例，转换函数中包含

  1. 基础数据类型，如 int，long，boolean，char 等。
  2. 结构体，如 Color4B，Vec2，BlendFunc 等。
  3. 容器类型，如 Dictionary，ValueVector，ValueMap 等。

这里没有提到类实例对象的转换，是因为类对象的转换是自动完成的。所以，当开发者自己的 API 中包含自己定义的结构体或者特殊容器类型作为参数或返回值的时候，就需要编写自己的转换函数，转换函数的编写方法可以参考引擎内部的这些范例。

仅仅有转换函数还不够，还需要告诉自动绑定工具该对何种类型具体使用哪个转换函数，这就是 yaml 转换模版的工作了，JS 的转换模版可以在 `tools/bindings-generator/targets/spidermonkey/conversions.yaml` 中找到，Lua 的转换模版则位于 `tools/bindings-generator/targets/lua/conversions.yaml`。在转换模版中，`to_native` 定义了从脚本对象转换为 C++ 对象的模版，`from_native` 定义了从 C++ 对象到脚本对象的转换模版。


编写绑定脚本和配置文件

# 编写绑定配置文件

编写绑定配置文件并不是非常简单直观的事情，不过由于引擎中有大量的绑定范例，开发者完全可以以此为模版进行修改。请参考引擎目录中 `tools/tojs` 和 `tools/tolua` 下的 `.ini` 文件，并结合前面一个章节中解释的定制属性来编写自己需要的绑定配置文件。


# 使用绑定生成脚本

自动绑定工具的主体是 `tools/bindings-generator/generator.py` 这个 python 脚本。当生成自动绑定的时候，针对每一个 `ini` 配置文件调用的 python 命令如下：

python generator.py config_file.ini -s module_name -t spidermonkey|lua -o output_dir -n output_file_name

当然，单独对每一个 `ini` 文件生成绑定是可以的。不过也可以通过编写自动生成脚本的方式来自动处理。

具体可以参考引擎的自动绑定生成脚本，`tools/tojs/genbindings.py` 和 `tools/tolua/genbindings.py`

在引擎的自动绑定生成脚本中，配置了下面的一些参数：

  1. NDK_ROOT 环境变量：指示 NDK 的根目录
  2. PYTHON_BIN 环境变量：指示 Python 命令的路径
  3. cocosdir：Cocos 引擎根目录，在用户工程下一般是 `frameworks/cocos2d-x/`
  4. jsbdir：JSB 目录，在用户工程下一般是 `frameworks/cocos2d-x/cocos/scripting/js-bindings`
  5. cxx_generator_root：自动绑定工具路径，在用户工程下一般是 `tools/bindings-generator`
  6. output_dir：生成的绑定文件存储路径
  7. cmd_args：所有配置文件，及其对应的模块名称和输出文件名称

最终支持批量自动化生成引擎的自动绑定代码。


绑定自己的 C++ 类

对于用户自己扩展的 C++ 类，通过上面的自动绑定原理解读，其实已经可以尝试自己编写绑定生成脚本生成扩展类的绑定了。不过引擎中的绑定生成脚本已经考虑到这种需求，提供了扩展的方法，开发者需要的就是遵循下面的步骤：

  1. 编写自定义 C++ 类的绑定配置文件并保存到 `tools/tojs` 或者 `tools/tolua` 文件夹中。
  2. 在 `tools/tojs/genbindings.py` 或 `tools/tolua/genbindings.py` 中找到 `custom_cmd_args`，在其中填写绑定模块。
  3. 运行 `genbindings.py` 即可生成自动绑定代码到 `frameworks/custom/auto` 文件夹中。

`custom_cmd_args` 的格式如下：

custom_cmd_args = {
    'custom_module1.ini' : ('custom_module1','jsb_custom_module1_auto'),\
    'custom_module2.ini' : ('custom_module2','jsb_custom_module2_auto'),}

其中键对应的是绑定配置文件文件名，括号中的第一个参数对应模块名，第二个参数对应输出文件的文件名。


结语

以上就是 Bindings Generator 自动绑定工具的原理介绍和使用方法，希望这篇文章对于理解 Cocos2d-x 的自动绑定原理有所帮助。

版权声明：本文内容由互联网用户自发贡献，该文观点与技术仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 dio@foxmail.com 举报，一经查实，本站将立刻删除。

相关推荐

如何使用CCRenderTexture创建动态纹理 Cocos2d-x 2 1 4
    本文实践自 RayWenderlich、Ali Hafizji 的文章《How To Create Dynamic Textures with CCRenderTexture in Cocos2D 2.X》，文中使用Cocos2D，我在这里使用Cocos2D-x 2.1.4进行学习和移植。在这篇文章，将会学习到如何创建实时纹理、如何用Gimp创建无缝拼接纹
Cocos-code-ide使用入门学习
Cocos-code-ide使用入门学习地点：杭州滨江邮箱：appdevzw@163.com微信公众号：HopToad 欢迎转载，转载标注出处：http://blog.csdn.netotbaron/article/details/424343991.  软件准备 下载地址：http://cn.cocos2d-x.org/download 2.  简介2.1         引用C
Cocos2D-x-3.0 编译(Win7)
第一次開始用手游引擎挺激动！！！进入正题。下载资源1：从Cocos2D-x官网上下载，进入网页http://www.cocos2d-x.org/download，点击Cocos2d-x以下的Download  v3.0，保存到自定义的文件夹2：从python官网上下载。进入网页https://www.python.org/downloads/，我当前下载的是3.4.0（当前最新
Cocos2d-x 2 0 在Windows平台下的使用
    Cocos2d-x是一款强大的基于OpenGLES的跨平台游戏开发引擎，易学易用，支持多种智能移动平台。官网地址：http://cocos2d-x.org/当前版本：2.0    有很多的学习资料，在这里我只做为自己的笔记记录下来，错误之处还请指出。在VisualStudio2008平台的编译：1.下载当前稳
quick-cocos2d-x实例之挑战记忆极限设计文档
1.  来源 QuickV3sample项目中的2048样例游戏，以及最近《最强大脑》娱乐节目。将2048改造成一款挑战玩家对数字记忆的小游戏。邮箱：appdevzw@163.com微信公众号：HopToadAPK下载地址：http://download.csdn.net/detailotbaron/8446223源码下载地址：http://download.csdn.net/
Cocos2d-x 3 X CMake MinGW版本编译运行
   Cocos2d-x3.x已经支持使用CMake来进行构建了，这里尝试以QtCreatorIDE来进行CMake构建。Cocos2d-x3.X地址：https://github.com/cocos2d/cocos2d-x1.打开QtCreator，菜单栏→"打开文件或项目..."，打开cocos2d-x目录下的CMakeLists.txt文件；2.弹出CMake向导，如下图所示：设置
vs 2013 编译cocos2d-x-3.9
 下载地址：链接:https://pan.baidu.com/s/1IkQsMU6NoERAAQLcCUMcXQ提取码:p1pb下载完成后，解压进入build目录使用vs2013打开工程设置平台工具集，打开设置界面设置： 点击开始编译等待编译结束编译成功在build文件下会出现一个新文件夹Debug.win32，里面就是编译
cocos2d-x游戏开发系列教程-超级玛丽01-前言
分享一下我老师大神的人工智能教程吧。零基础！通俗易懂！风趣幽默！还带黄段子！希望你也加入到我们人工智能的队伍中来！http://www.captainbed.net前言上次用象棋演示了cocos2dx的基本用法，但是对cocos2dx并没有作深入的讨论，这次以超级马里奥的源代码为线索，我们一起来学习超级马里奥的实
Cocos2d-x CCControlPotentiometer之圆形音量button及特效
1. 圆形音量button事实上作者的本意应该是叫做“电位计button”。可是我觉得它和我们的圆形音量button非常像，所以就这么叫它吧~先看效果：好了，不多解释，本篇到此为止。（旁白： 噗。就这样结束了？）啊才怪~我们来看看代码：[cpp] viewplaincopyprint?CCContro
Cocos2d-x入门教程二简单的静态显示对象
原文链接：http://www.cnblogs.com/physwf/archive/2013/04/26/3043912.html为了进一步深入学习贯彻Cocos2d，我们将自己写一个场景类，但我们不会走的太远，凡是都要循序渐进，哪怕只前进一点点，那也至少是前进了，总比贪多嚼不烂一头雾水的好。在上一节中我们建
cocos2d-x中CCScale9Sprite的另一种实现
2019独角兽企业重金招聘Python工程师标准>>>cocos2d2.0之后加入了一种九宫格的实现，主要作用是用来拉伸图片，这样的好处在于保留图片四个角不变形的同时，对图片中间部分进行拉伸，来满足一些控件的自适应（PS: 比如包括按钮，对话框，最直观的形象就是ios里的短信气泡了），这就要求图
Cocos2d-x v2.2.2版本+Win7+VS2010环境搭建
原文链接：http://www.cnblogs.com/linji/p/3599478.html1.环境和工具准备Win7VS2010/2012，至于2008v2版本之后似乎就不支持了。 2.安装pythonv.2.0版本之前是用vs模板创建工程的，到vs2.2之后就改用python创建了。到python官网下载版本2.7.5的，然后
Ubuntu14.04+eclipse下cocos2d-x3.0正式版环境的搭建
环境:ubuntu14.04adt-bundle-linux-x86_64android-ndk-r9d-linux-x86_64cocos2d-x-3.0正式版apache-ant1.9.3python2.7(ubuntu自带)加入环境变量exportANDROID_SDK_ROOT=/home/yangming/adt-bundle-linux/sdkexportPATH=${PATH}:/$ANDROID_SDK_ROOTools/export
分别基于WIN32 API界面编程和Cocos2d-x实现的两个版本FlappyBird游戏
1开发背景游戏程序设计涉及了学科中的各个方面，鉴于目的在于学习与进步，本游戏《FlappyBird》采用了两个不同的开发方式来开发本款游戏，一类直接采用win32底层API来实现，另一类采用当前火热的cocos2d-x游戏引擎来开发本游戏。2需求分析2.1数据分析本项目要开发的是一款游
Cocos2d-x 开发小记二：控件
原文链接：http://www.cnblogs.com/linji/p/3599912.html//纯色色块控件（锚点默认左下角）CCLayerColor*ccc=CCLayerColor::create(ccc4(255,0,0,128),200,100);//渐变色块控件CCLayerGradient*ccc=CCLayerGradient::create(ccc4(255,0,0,
Cocos2d-x 开发小记一：基本动作
原文链接：http://www.cnblogs.com/linji/p/3599488.html//载入一张图片CCSprite*leftDoor=CCSprite::create("loading/door.png");leftDoor->setAnchorPoint(ccp(1,0.5));//设置锚点为右边中心点leftDoor->setPosition(ccp(240,160));/
买Cocos2d-x视频课程送纸质图书
为了答谢广大学员对智捷课堂以及关老师的支持，现购买51CTO学院关老师的Cocos2d-x课程之一可以送智捷课堂编写图书一本（专题可以送3本）。一、Cocos2d-x课程列表：1、Cocos2d-x入门与提高视频教程__Part22、Cocos2d-x数据持久化与网络通信__Part33、Cocos2d-x架构设计与性能优化内存优
‎Cocos2d-x 学习笔记(11.10) Spawn
Spawn让多个action同时执行。Spawn有多种不同的create方法，最终都调用了createWithTwoActions(FiniteTimeAction*action1,FiniteTimeAction*action2)方法。createWithTwoActions调用initWithTwoActions方法：对两个action变量初始化：_one=action1;_two=action2;如果两个a
quick-cocos2d-x-develop资源打包环境安装
需要环境：php,luajit.昨天在cygwin上安装php和luajit环境，这真特么是一个坑。建议不要用虚拟环境安装打包环境，否则可能会出现各种莫名问题。折腾了一下午，最终将环境转向linux。其中，luajit的安装脚本已经在quick-cocos2d-x-develop/bin/中，直接luajit_install.sh即可。我的lin
Cocos2d-x 3.0心得01－图片载入与混合模式
v3.0相对v2.2来说，最引人注意的。应该是对触摸层级的优化。和lambda回调函数的引入（嗯嗯，不枉我改了那么多类名。话说，每次cocos2dx大更新。总要改掉一堆类名函数名）。这些特性应该有不少人研究了，所以今天说点跟图片有关的东西。v3.0在载入图片方面也有了非常大改变，仅仅只是
pythonJavaScriptjavaHTMLPHPreactjsC#AndroidCSSNode.jssqlrpython-3.xMysqLjQueryc++pandasFlutterangularIOSdjangolinuxswifttypescript路由器JSON路由器设置无线路由器h3c华三华三路由器设置华三路由器电脑软件教程arraysdocker软件图文教程Cvue.jslaravelspring-boot