Cocos 中的自动绑定规则
|
Cocos 中的自动绑定依赖于 Bindings Generator 工具，这个 python 工具通过配置文件来解析需要绑定的类的头文件，并且按照一定规则生成类的 API 的绑定代码。 Bindings GeneratorBindings Generator 工具是自动绑定的核心工具，它可以将 C++ 类的公共方法和公共属性绑定到脚本层。自动绑定工具非常强大，不过它还是有以下几个限制： 1. 只能够针对类生成绑定，不可以绑定结构体，独立函数等。 2. 不能够生成 Delegate 类型的 API，因为脚本中的对象是无法继承 C++ 中的 Delegate 类并重写其中的 Delegate 函数的。 3. 子类中重写了父类的 API 的同时，又重载了这个 API。 4. 部分 API 实现内容并没有完全体现在其 API 定义中。 5. 在运行时由 C++ 主动调用的 API。 也就是说，除了这几种情况以外，都可以通过自动绑定工具将 C++ 类绑定到脚本层。 配置环境 # Mac OS X 环境配置
sudo easy_install pip
sudo pip install PyYAML
sudo pip install Cheetah
# Windows环境配置
至此绑定工具的基本环境已经配置成功。 基本原理 自动绑定工具最核心的工作原理是通过 libclang 分析 C++ 头文件，以一定的绑定规则和绑定代码模版，针对 C++ 类的公共方法和属性一一对应生成每个方法的绑定代码和每个属性的 Getter/Setter 方法。下面让我们用倒推法来分析这个过程： # 绑定结果最终，自动绑定的结果是一个 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++ 头文件进行语法分析。绑定的过程大致如下：
# 绑定规则和绑定模版 当然，绑定过程并不是不可控的，其实有很多可定制的规则是通过自动绑定的配置文件来配置的。有了这些配置，开发者就可以选择绑定的具体内容和方式。其中可定制的重要属性如下：
有了这些配置之后，自动绑定工具就知道哪些 API 要被绑定和以什么样的方式绑定。不过，还需要配合各种 API 的绑定代码模版才可以真正生成各种 API 的绑定函数。对于每一个特定的模版，它会读取 clang.cindex 解析出的类或 API 定义信息以及绑定配置信息，生成特定 API 的绑定代码。下面是目前自动绑定工具中的模版：
# 转换函数 从上文的调用过程中可以看出，脚本层和 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 为例，转换函数中包含
这里没有提到类实例对象的转换，是因为类对象的转换是自动完成的。所以，当开发者自己的 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` 在引擎的自动绑定生成脚本中，配置了下面的一些参数：
最终支持批量自动化生成引擎的自动绑定代码。 绑定自己的 C++ 类 对于用户自己扩展的 C++ 类，通过上面的自动绑定原理解读，其实已经可以尝试自己编写绑定生成脚本生成扩展类的绑定了。不过引擎中的绑定生成脚本已经考虑到这种需求，提供了扩展的方法，开发者需要的就是遵循下面的步骤：
`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 的自动绑定原理有所帮助。 （编辑：李大同） 【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容! |
