bind.h (under-construction)

The C++ APIs in bind.h define

Guide documentation for this API can be found in Embind.

How to use this API

Defines

EMSCRIPTEN_BINDINGS(name)

This define is used to bind C++ classes, functions and other constructs to JavaScript. It is used differently depending on the construct being mapped β€” see the embind guide for examples.

Parameters:

name – This is a label to mark a group of related bindings (for example EMSCRIPTEN_BINDINGS(physics), EMSCRIPTEN_BINDINGS(components), etc.)

type sharing_policy
type sharing_policy::NONE
type sharing_policy::INTRUSIVE
type sharing_policy::BY_EMVAL

Policies

Currently only allow_raw_pointers policy is supported. Eventually we hope to implement Boost.Python-like raw pointer policies for managing object ownership.

type arg
static int index
// Prototype
static constexpr int index
type ret_val
static int index
// Prototype
static constexpr int index
type allow_raw_pointers

This policy is used to allow raw pointers.

type Transform::type
type allow_raw_pointer

select_overload and 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)
Parameters:

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))
Parameters:

Signature (ClassType::*fn) –

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

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)
Parameters:

const LambdaType& fp –

Functions

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

Registers a function to export to JavaScript. This is called from within an EMSCRIPTEN_BINDINGS() block.

For example to export the function 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);
}
Parameters:

  • const char* name – The name of the function to export (e.g. "lerp").

  • ReturnType (*fn)(Args...) – Function pointer address for the exported function (e.g. &lerp).

  • Policies... – Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.

Value tuples

class value_array : public internal::noncopyable
type class_type

A typedef of ClassType, the typename of the templated type for the class.

value_array(const char *name)

Constructor.

Parameters:

const char* name –

~value_array()

Destructor.

value_array &element(ElementType InstanceType::* field)
Parameters:

ElementType InstanceType::*field – Note that ElementType and InstanceType are typenames (templated types).

value_array &element(Getter getter, Setter setter)
Parameters:

  • Getter getter – Note that Getter is a typename (templated type).

  • Setter setter – Note that Setter is a typename (templated type).

value_array &element(index<Index>)
Parameters:

index<Index> – Note that Index is an integer template parameter.

Value structs

class value_object : public internal::noncopyable
type class_type

A typedef of ClassType, the typename of the templated type for the class.

value_object(const char *name)

Constructor.

Parameters:

const char* name –

~value_object()

Destructor.

value_object &field(const char *fieldName, FieldType InstanceType::* field)
Parameters:

  • const char* fieldName –

  • FieldType InstanceType::*field –

value_object &field(const char *fieldName, Getter getter, Setter setter)
Parameters:

  • const char* fieldName –

  • Getter getter – Note that Getter is a typename (templated type).

  • Setter setter – Note that Setter is a typename (templated type).

value_object &field(const char *fieldName, index<Index>)
Parameters:

  • const char* fieldName –

  • index<Index> – Note that Index is an integer template parameter.

Smart pointers

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)
Parameters:

void* v –

static PointerType *construct_null()
Returns:

Note that the PointerType returned is a typename (templated type).

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;

A typedef for the PointerType::element_type, where PointerType is a typename (templated type).

static element_type *get(const PointerType &ptr)
Parameters:

const PointerType& ptr – Note that PointerType is a typename (templated type)

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

A typedef to std::shared_ptr<PointeeType>, where PointeeType is a typename (templated type).

type element_type

A typedef for the PointerType::element_type.

static element_type *get(const PointerType &ptr)
Parameters:

const PointerType& ptr –

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

  • PointeeType* p – Note that PointeeType is a typename (templated type).

  • EM_VAL v –

static PointerType *construct_null()

Classes

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

A typedef of T, the typename of the templated type for the class.

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))

Constructor.

Parameters:

  • val&& wrapped –

  • Args&&... args – Note that Args is a typename (templated type).

~wrapper()

Destructor.

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

Constructor.

Parameters:

  • const char* name –

  • Args&&... args – Note that Args is a typename (templated type).

Returns:

Note that ReturnType is a typename (templated type).

EMSCRIPTEN_WRAPPER(T)
Parameters:

T –

type base
type class_type

A typedef of BaseClass, the typename of the templated type for the class.

static void verify()

Note, is templated function which takes typename 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)
Parameters:

From* ptr –

type pure_virtual
type Transform

Note that this is a templated struct taking typename parameter InputType and integer Index.

type type

This is a typedef to the parent struct typename parameter InputType.

type constructor

Note that this is a template struct taking typename ... ConstructorArgs.

class class_

Note that this is a templated class with typename parameters ClassType and BaseSpecifier.

type class_type

A typedef of ClassType (a typename for the class).

type base_specifier

A typedef of BaseSpecifier (a typename for the class).

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

Constructor.

Parameters:

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
Parameters:

const char* name –

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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

Zero-argument form of the class constructor. This invokes the natural constructor with the arguments specified in the template. See External constructors for more information.

Parameters:

Policies... policies – Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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

Class constructor for objects that use a factory function to create the object. This method will accept either a function pointer, std::function object or function object which will return a newly constructed object. When the Callable is a function object the function signature must be explicitly specified in the Signature template parameter in the format ReturnType (Args...). For Callable types other than function objects the method signature will be deduced.

The following are all valid calls to 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));

See External constructors for more information.

Parameters:

  • Callable callable – Note that Callable may be either a member function pointer, function pointer, std::function or function object.

  • Policies... policies – Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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
Parameters:

  • const char* smartPtrName –

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

  • Policies... policies – Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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
Parameters:

  • const char* wrapperClassName –

  • const char* pointerName –

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

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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
Parameters:

  • const char* wrapperClassName –

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

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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

This method is for declaring a method belonging to a class.

On the JavaScript side this is a function that gets bound as a property of the prototype. For example .function("myClassMember", &MyClass::myClassMember) would bind myClassMember to MyClass.prototype.myClassMember in the JavaScript. This method will accept either a pointer-to-member-function, function pointer, std::function object or function object. When the Callable is not a pointer-to-member-function it must accept the ClassType as the first (this) parameter. When the Callable is a function object the function signature must be explicitly specified in the Signature template parameter in the format ReturnType (Args...). For Callable types other than function objects the method signature will be deduced.

A method name specified in the human-readable well-known symbol format (e.g., @@iterator) is bound using the named Symbol for JavaScript (e.g., Symbol.iterator).

The following are all valid calls to 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));
Parameters:

  • const char* methodName –

  • Callable callable – Note that Callable may be either a member function pointer, function pointer, std::function or function object.

  • typename... Policies – Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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
Parameters:

  • const char* fieldName –

  • const FieldType ClassType::*field –

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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
Parameters:

  • const char* fieldName –

  • FieldType ClassType::*field –

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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;

Declare a read-only property with the specified fieldName on the class using the specified getter to retrieve the property value. Getter may be either a class method, a function, a std::function or a function object. When Getter is not pointer-to-member-function, it must accept an instance of the ClassType as the this argument. When Getter is a function object, the property type must be specified as a template parameter as it cannot be deduced, e.g.: myClass.property<int>("myIntProperty", MyIntGetterFunctor());

Parameters:

  • const char* fieldName –

  • Getter getter – Note that Getter is a function template typename.

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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

This is a function template taking typenames Setter and Getter: template<typename Getter, typename Setter> which declares a read-write property with the specified fieldName on the class. Getter and Setter may be either a class method, a function, a std::function or a function object. When Getter or Setter is not pointer-to-member-function, it must accept an instance of the ClassType as the this argument. When Getter or Setter is a function object, the property type must be specified as a template parameter as it cannot be deduced, e.g.: myClass.property<int>("myIntProperty", MyIntGetterFunctor(), MyIntSetterFunctor());

Parameters:

  • const char* fieldName –

  • Getter getter – Note that Getter is a function template typename.

  • Setter setter – Note that Setter is a function template typename.

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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

This method is for declaring a static function belonging to a class.

On the JavaScript side this is a function that gets bound as a property of the constructor. For example .class_function("myStaticFunction", &MyClass::myStaticFunction) binds myStaticFunction to MyClass.myStaticFunction.

A method name specified in the human-readable well-known symbol format (e.g., @@species) is bound using the named Symbol for JavaScript (e.g., Symbol.species).

Parameters:

  • const char* methodName –

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

  • Policies... – Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

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
Parameters:

  • const char* fieldName –

  • FieldType ClassType::*field –

Returns:

A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.

Vectors

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

A function to register a std::vector<T>.

Parameters:

const char* name –

Maps

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)

A function to register a std::map<K, V>.

Parameters:

const char* name –

Enums

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

Registers an enum to export to JavaScript. This is called from within an EMSCRIPTEN_BINDINGS() block and works with both C++98 enums and C++11 β€œenum classes”. See Enums for more information.

type enum_type

A typedef of EnumType (a typename for the class).

enum_(const char *name)

Constructor.

Parameters:

const char* name –

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

Registers an enum value.

Parameters:

  • const char* name – The name of the enumerated value.

  • EnumType value – The type of the enumerated value.

Returns:

A reference to the current object. This allows chaining of multiple enum values in the EMSCRIPTEN_BINDINGS() block.

Constants

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

Registers a constant to export to JavaScript. This is called from within an EMSCRIPTEN_BINDINGS() block.

EMSCRIPTEN_BINDINGS(my_constant_example) {
  constant("SOME_CONSTANT", SOME_CONSTANT);
}
Parameters:

  • const char* name – The name of the constant.

  • const ConstantType& v – The constant type. This can be any type known to embind.