bind.h (建構中)

bind.h 中的 C++ API 定義

此 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。

值組

class value_array : public internal::noncopyable
type 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 –

類型base
類型class_type

BaseClass 的 typedef，即類別的模板類型名稱。

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 –

類型pure_virtual
類型Transform

請注意，這是一個模板結構，採用類型名稱參數 InputType 和整數 Index。

類型type

這是父結構類型名稱參數 InputType 的 typedef。

類型constructor

請注意，這是一個模板結構，採用類型名稱 ... ConstructorArgs。

class class_

請注意，這是一個模板類別，帶有類型名稱參數 ClassType 和 BaseSpecifier。

類型class_type

ClassType 的 typedef（類別的類型名稱）。

類型base_specifier

BaseSpecifier 的 typedef（類別的類型名稱）。

類型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) 會將 myClassMember 綁定到 JavaScript 中的 MyClass.prototype.myClassMember。此方法將接受成員函式指標、函式指標、std::function 物件或函式物件。當 Callable 不是成員函式指標時，它必須接受 ClassType 作為第一個（this）參數。當 Callable 是一個函式物件時，函式簽章必須以 ReturnType (Args...) 的格式在 Signature 樣板參數中明確指定。對於函式物件以外的 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 – 用於管理原始指標物件所有權的Policy。目前必須是 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 –

  • const 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 是一個函式樣板 typename。

返回

目前物件的 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

這是一個接受 typename 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 是一個函式樣板 typename。

  • Setter setter – 請注意，Setter 是一個函式樣板 typename。

返回

目前物件的 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 的「列舉類別」。有關更多資訊，請參閱列舉。

type enum_type

EnumType (類別的 typename) 的 typedef。

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 已知的型別。