bind.h (正在建设中)

C++ API 在 bind.h 中定义

本 API 的指南文档可以在 Embind 中找到。

如何使用此 API

定义

EMSCRIPTEN_BINDINGS(name)

此定义用于将 C++ 类、函数和其他构造绑定到 JavaScript。根据要映射的构造的不同，它的使用方式也不同 - 请参阅 embind 指南 以获取示例。

参数

name – 这是一个标签，用于标记一组相关的绑定（例如 EMSCRIPTEN_BINDINGS(physics)，EMSCRIPTEN_BINDINGS(components) 等）

类型 sharing_policy
类型 sharing_policy::NONE
类型 sharing_policy::INTRUSIVE
类型 sharing_policy::BY_EMVAL

策略

目前只支持 allow_raw_pointers 策略。最终，我们希望为管理对象所有权实现类似于 Boost.Python 的原始指针策略。

类型 arg
静态 int index
// Prototype
static constexpr int index
类型 ret_val
静态 int index
// Prototype
static constexpr int index
类型 allow_raw_pointers

此策略用于允许原始指针。

类型 Transform::type
类型 allow_raw_pointer

select_overload 和 select_const

typename std::add_pointer<Signature>::type select_overload(typename std::add_pointer<Signature>::type fn)
// Prototype
template<typename Signature>
typename std::add_pointer<Signature>::type select_overload(typename std::add_pointer<Signature>::type fn)
参数

typename std::add_pointer<Signature>::type fn –

typename internal::MemberFunctionType<ClassType, Signature>::type select_overload()
// Prototype
template<typename Signature, typename ClassType>
typename internal::MemberFunctionType<ClassType, Signature>::type select_overload(Signature (ClassType::*fn))
参数

Signature (ClassType::*fn) –

auto select_const()
// Prototype
template<typename ClassType, typename ReturnType, typename... Args>
auto select_const(ReturnType (ClassType::*method)(Args...) const)
参数

ReturnType (ClassType::*method)(Args...) const –

typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType &fp)
// Prototype
template<typename LambdaType>
typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType& fp)
参数

const LambdaType& fp –

函数

void function()
//prototype
template<typename ReturnType, typename... Args, typename... Policies>
void function(const char* name, ReturnType (*fn)(Args...), Policies...)

注册一个函数以导出到 JavaScript。这从 EMSCRIPTEN_BINDINGS() 块内部调用。

例如，要导出函数 lerp()

// quick_example.cpp
#include <emscripten/bind.h>

using namespace emscripten;

float lerp(float a, float b, float t) {
   return (1 - t) * a + t * b;
}

EMSCRIPTEN_BINDINGS(my_module) {
   function("lerp", &lerp);
}
参数

  • const char* name – 要导出的函数的名称（例如 "lerp"）。

  • ReturnType (*fn)(Args...) – 要导出的函数的函数指针地址（例如 &lerp）。

  • Policies... – 策略 用于管理原始指针对象所有权。当前必须是 allow_raw_pointers。

值元组

类 value_array : public internal::noncopyable
类型 class_type

ClassType 的 typedef，即类的模板类型的类型名称。

value_array(const char *name)

构造函数。

参数

const char* name –

~value_array()

析构函数。

value_array &element(ElementType InstanceType::*field)
参数

ElementType InstanceType::*field – 请注意，ElementType 和 InstanceType 是类型名称（模板类型）。

value_array &element(Getter getter, Setter setter)
参数

  • Getter getter – 请注意，Getter 是一个类型名（模板类型）。

  • Setter setter – 请注意，Setter 是一个类型名（模板类型）。

value_array &element(index<Index>)
参数

index<Index> – 请注意，Index 是一个整数模板参数。

值结构

class value_object : public internal::noncopyable
type class_type

ClassType 的 typedef，即类的模板类型的类型名称。

value_object(const char *name)

构造函数。

参数

const char* name –

~value_object()

析构函数。

value_object &field(const char *fieldName, FieldType InstanceType::*field)
参数

  • const char* fieldName –

  • FieldType InstanceType::*field –

value_object &field(const char *fieldName, Getter getter, Setter setter)
参数

  • const char* fieldName –

  • Getter getter – 请注意，Getter 是一个类型名（模板类型）。

  • Setter setter – 请注意，Setter 是一个类型名（模板类型）。

value_object &field(const char *fieldName, index<Index>)
参数

  • const char* fieldName –

  • index<Index> – 请注意，Index 是一个整数模板参数。

智能指针

type default_smart_ptr_trait
//prototype
template<typename PointerType>
struct default_smart_ptr_trait
static sharing_policy get_sharing_policy()
static void *share(void *v)
参数

void* v –

static PointerType *construct_null()
返回

请注意，返回的 PointerType 是一个类型名（模板类型）。

type smart_ptr_trait
//prototype
template<typename PointerType>
struct smart_ptr_trait : public default_smart_ptr_trait<PointerType>
typedef PointerType::element_type element_type
//prototype
typedef typename PointerType::element_type element_type;

对于 PointerType::element_type 的一个 typedef，其中 PointerType 是一个类型名（模板类型）。

static element_type *get(const PointerType &ptr)
参数

const PointerType& ptr – 请注意，PointerType 是一个类型名（模板类型）

template<typename PointeeType>
using smart_ptr_trait<std::shared_ptr<PointeeType>>
//prototype
template<typename PointeeType>
struct smart_ptr_trait<std::shared_ptr<PointeeType>>
type PointerType

对 std::shared_ptr<PointeeType> 的一个 typedef，其中 PointeeType 是一个类型名（模板类型）。

type element_type

对 PointerType::element_type 的一个 typedef。

static element_type *get(const PointerType &ptr)
参数

const PointerType& ptr –

static sharing_policy get_sharing_policy()
static std::shared_ptr<PointeeType> *share(PointeeType *p, EM_VAL v)
参数

  • PointeeType* p – 请注意，PointeeType 是一个类型名（模板类型）。

  • EM_VAL v –

static PointerType *construct_null()

类

class wrapper : public T, public internal::WrapperBase
//prototype
template<typename T>
class wrapper : public T, public internal::WrapperBase
type class_type

对 T 的一个 typedef，类模板类型的类型名。

wrapper(val &&wrapped, Args&&... args)
//prototype
template<typename... Args>
explicit wrapper(val&& wrapped, Args&&... args)
  : T(std::forward<Args>(args)...)
  , wrapped(std::forward<val>(wrapped))

构造函数。

参数

  • val&& wrapped –

  • Args&&... args – 请注意，Args 是一个类型名（模板类型）。

~wrapper()

析构函数。

ReturnType call(const char *name, Args&&... args) const

构造函数。

参数

  • const char* name –

  • Args&&... args – 请注意，Args 是一个类型名（模板类型）。

返回

请注意，ReturnType 是一个类型名（模板类型）。

EMSCRIPTEN_WRAPPER(T)
参数

T –

type base
type class_type

模板类类型名的类型定义 BaseClass。

static void verify()

注意，这是一个带类型参数的模板函数，该类型参数为 ClassType。

static internal::TYPEID get()
template<typename ClassType>
using Upcaster = BaseClass* (*)(ClassType*);

template<typename ClassType>
using Downcaster = ClassType* (*)(BaseClass*);
static Upcaster<ClassType> getUpcaster()
//prototype
template<typename ClassType>
static Upcaster<ClassType> getUpcaster()
static Downcaster<ClassType> getDowncaster()
//prototype
template<typename ClassType>
static Downcaster<ClassType> getDowncaster()
static To *convertPointer(From *ptr)
//prototype
template<typename From, typename To>
static To* convertPointer(From* ptr)
参数

From* ptr –

type pure_virtual
type Transform

注意，这是一个带类型参数的模板结构体，该类型参数为 InputType 和整数 Index。

type type

这是一个指向父结构体类型参数 InputType 的类型定义。

type constructor

注意，这是一个带类型参数的模板结构体，该类型参数为 ... ConstructorArgs。

class class_

注意，这是一个带类型参数的模板类，该类型参数为 ClassType 和 BaseSpecifier。

type class_type

对 ClassType (类的类型名) 的类型定义。

type base_specifier

对 BaseSpecifier (类的类型名) 的类型定义。

type HELPNEEDEDHERE
class_() = delete;
explicit class_(const char *name)
//prototype
EMSCRIPTEN_ALWAYS_INLINE explicit class_(const char* name)

构造函数。

参数

const char* name –

const class_ &smart_ptr(const char *name) const
//prototype
template<typename PointerType>
EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr(const char* name) const
参数

const char* name –

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &constructor() const
//prototype
template<typename... ConstructorArgs, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& constructor(Policies... policies) const

类构造函数的零参数形式。这将调用自然构造函数，该构造函数使用模板中指定的参数。有关更多信息，请参阅 外部构造函数。

参数

Policies... policies – 策略 用于管理原始指针对象所有权。目前必须是 allow_raw_pointers。

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &constructor(Callable callable, Policies...) const
//prototype
template<typename Signature = internal::DeduceArgumentsTag, typename Callable, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& constructor(Callable callable, Policies...) const

用于使用工厂函数创建对象的类构造函数。此方法将接受函数指针、std::function 对象或函数对象，这些对象将返回一个新构造的对象。当 Callable 是函数对象时，必须在 Signature 模板参数中以 ReturnType (Args...) 格式显式指定函数签名。对于 Callable 类型的函数对象以外的类型，方法签名将被推断。

以下是对 constructor 的所有有效调用

using namespace std::placeholders;
myClass1.constructor(&my_factory);
myClass2.constructor(std::function<ClassType2(float, float)>(&class2_factory));
myClass3.constructor<ClassType3(const val&)>(std::bind(Class3Functor(), _1));

有关更多信息，请参阅 外部构造函数。

参数

  • Callable callable – 注意，Callable 可以是成员函数指针、函数指针、std::function 或函数对象。

  • Policies... policies – 策略 用于管理原始指针对象所有权。目前必须是 allow_raw_pointers。

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &smart_ptr_constructor() const
//prototype
template<typename SmartPtr, typename... Args, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr_constructor(const char* smartPtrName, SmartPtr (*factory)(Args...), Policies...) const
参数

  • const char* smartPtrName –

  • SmartPtr (*factory)(Args...) –

  • Policies... policies – 策略 用于管理原始指针对象所有权。目前必须是 allow_raw_pointers。

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &allow_subclass() const
//prototype
 template<typename WrapperType, typename PointerType, typename... ConstructorArgs>
EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass(
  const char* wrapperClassName,
  const char* pointerName,
  ::emscripten::constructor<ConstructorArgs...> = ::emscripten::constructor<>()
) const
参数

  • const char* wrapperClassName –

  • const char* pointerName –

  • emscripten::constructor<ConstructorArgs...> constructor) –

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &allow_subclass(const char *wrapperClassName, emscripten::constructor<ConstructorArgs...> constructor) const
//prototype
template<typename WrapperType, typename... ConstructorArgs>
EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass(
  const char* wrapperClassName,
  ::emscripten::constructor<ConstructorArgs...> constructor = ::emscripten::constructor<>()
) const
参数

  • const char* wrapperClassName –

  • ::emscripten::constructor<ConstructorArgs...> constructor) –

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &function() const
//prototype
template<typename Signature = internal::DeduceArgumentsTag, typename Callable, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& function(const char* methodName, Callable callable, Policies...) const

此方法用于声明属于类的某个方法。

在 JavaScript 端，这是一个绑定为原型属性的函数。例如，.function("myClassMember", &MyClass::myClassMember) 将在 JavaScript 中将 myClassMember 绑定到 MyClass.prototype.myClassMember。此方法将接受成员函数指针、函数指针、std::function 对象或函数对象。当 Callable 不是成员函数指针时，它必须接受 ClassType 作为第一个 (this) 参数。当 Callable 是函数对象时，必须在 Signature 模板参数中以 ReturnType (Args...) 格式显式指定函数签名。对于 Callable 类型的函数对象以外的类型，方法签名将被推断。

以人类可读的通用符号格式指定的方法名称（例如，@@iterator）使用 JavaScript 中的命名 Symbol 绑定（例如，Symbol.iterator）。

以下是对 function 的所有有效调用

using namespace std::placeholders;
myClass.function("myClassMember", &MyClass::myClassMember)
    .function("myFreeFunction", &my_free_function)
    .function("myStdFunction", std::function<float(ClassType&, float, float)>(&my_function))
    .function<val(const MyClass&)>("myFunctor", std::bind(&my_functor_taking_this, _1));
参数

  • const char* methodName –

  • Callable callable – 注意，Callable 可以是成员函数指针、函数指针、std::function 或函数对象。

  • typename... Policies – 策略 用于管理原始指针对象所有权。目前必须是 allow_raw_pointers。

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &property() const
//prototype
template<typename FieldType, typename = typename std::enable_if<!std::is_function<FieldType>::value>::type>
EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, const FieldType ClassType::*field) const
参数

  • const char* fieldName –

  • FieldType ClassType::*field –

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &property(const char *fieldName, FieldType ClassType::*field) const
//prototype
template<typename FieldType, typename = typename std::enable_if<!std::is_function<FieldType>::value>::type>
EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType ClassType::*field) const
参数

  • const char* fieldName –

  • FieldType ClassType::*field –

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &property(const char *fieldName, Getter getter) const
//prototype
template<typename PropertyType = internal::DeduceArgumentsTag, typename Getter>
EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, Getter getter) const;

使用指定的 getter 在类上声明一个具有指定 fieldName 的只读属性以检索属性值。 Getter 可以是类方法、函数、std::function 或函数对象。当 Getter 不是指向成员函数的指针时，它必须接受 ClassType 的实例作为 this 参数。当 Getter 是一个函数对象时，必须将属性类型指定为模板参数，因为它不能被推断，例如：myClass.property<int>("myIntProperty", MyIntGetterFunctor());

参数

  • const char* fieldName –

  • Getter getter – 请注意，Getter 是一个函数模板类型名。

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &property(const char *fieldName, Getter getter, Setter setter) const
//prototype
template<typename PropertyType = internal::DeduceArgumentsTag, typename Getter, typename Setter>
EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, Getter getter, Setter setter) const

这是一个使用类型名 Setter 和 Getter 的函数模板：template<typename Getter, typename Setter>，它在类上声明一个具有指定 fieldName 的读写属性。 Getter 和 Setter 可以是类方法、函数、std::function 或函数对象。当 Getter 或 Setter 不是指向成员函数的指针时，它必须接受 ClassType 的实例作为 this 参数。当 Getter 或 Setter 是一个函数对象时，必须将属性类型指定为模板参数，因为它不能被推断，例如：myClass.property<int>("myIntProperty", MyIntGetterFunctor(), MyIntSetterFunctor());

参数

  • const char* fieldName –

  • Getter getter – 请注意，Getter 是一个函数模板类型名。

  • Setter setter – 请注意，Setter 是一个函数模板类型名。

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &class_function() const
//prototype
template<typename ReturnType, typename... Args, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& class_function(const char* methodName, ReturnType (*classMethod)(Args...), Policies...) const

此方法用于声明属于类的静态函数。

在 JavaScript 端，这是一个作为构造函数属性绑定的函数。例如 .class_function("myStaticFunction", &MyClass::myStaticFunction) 将 myStaticFunction 绑定到 MyClass.myStaticFunction。

在人类可读的众所周知的符号格式（例如，@@species）中指定的函数名使用 JavaScript 的命名 Symbol 绑定（例如，Symbol.species）。

参数

  • const char* methodName –

  • ReturnType (*classMethod)(Args...) –

  • Policies... – 策略 用于管理原始指针对象所有权。当前必须是 allow_raw_pointers。

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

const class_ &class_property(const char *fieldName, FieldType *field) const
//prototype
template<typename FieldType>
EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType *field) const
参数

  • const char* fieldName –

  • FieldType ClassType::*field –

返回

对当前对象的 const 引用。这允许在 EMSCRIPTEN_BINDINGS() 块中定义绑定的 class_ 函数的链式调用。

向量

class_<std::vector<T>> register_vector(const char *name)
//prototype
template<typename T>
class_<std::vector<T>> register_vector(const char* name)

用于注册 std::vector<T> 的函数。

参数

const char* name –

映射

class_<std::map<K, V>> register_map(const char *name)
//prototype
template<typename K, typename V>
class_<std::map<K, V>> register_map(const char* name)

用于注册 std::map<K, V> 的函数。

参数

const char* name –

枚举

class enum_
//prototype
template<typename EnumType>
class enum_

注册要导出到 JavaScript 的枚举。这在 EMSCRIPTEN_BINDINGS() 块中调用，适用于 C++98 枚举和 C++11 “enum classes”。有关更多信息，请参见 枚举。

type enum_type

EnumType（类类型名）的类型定义。

enum_(const char *name)

构造函数。

参数

const char* name –

enum_ &value(const char *name, EnumType value)

注册枚举值。

参数

  • const char* name – 枚举值的名称。

  • EnumType value – 枚举值的类型。

返回

对当前对象的引用。这允许在 EMSCRIPTEN_BINDINGS() 块中链接多个枚举值。

常量

void constant(const char *name, const ConstantType &v)
//prototype
template<typename ConstantType>
void constant(const char* name, const ConstantType& v)

注册要导出到 JavaScript 的常量。这在 EMSCRIPTEN_BINDINGS() 块中调用。

EMSCRIPTEN_BINDINGS(my_constant_example) {
  constant("SOME_CONSTANT", SOME_CONSTANT);
}
参数

  • const char* name – 常量的名称。

  • const ConstantType& v – 常量类型。这可以是 embind 知道的任何类型。