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)

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

:param Signature (ClassType::*fn)

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

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

:param 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.

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

:param Getter getter. Note that Getter is a typename (templated type). :param Setter setter. Note that Setter is a typename (templated type).

value_array &element(index<Index>)

:param 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.

:param const char* name

~value_object()

Destructor.

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

:param const char* fieldName. :param FieldType InstanceType::*field.

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

:param const char* fieldName. :param Getter getter. Note that Getter is a typename (templated type). :param Setter setter. Note that Setter is a typename (templated type).

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

:param const char* fieldName. :param 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)

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

:param 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.

:param val&& wrapped :param Args&&… args: Note that Args is a typename (templated type).

~wrapper()

Destructor.

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

Constructor.

:param const char* name :param Args&&… args: Note that Args is a typename (templated type). :returns: Note that ReturnType is a typename (templated type).

EMSCRIPTEN_WRAPPER(T)

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

:param 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.

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

:param 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... policiesPolicy 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.

:param Callable callable Note that Callable may be either a member function pointer, function pointer, std::function or function object. :param 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

:param const char* smartPtrName :param SmartPtr (*factory)(Args…) :param 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

:param const char* wrapperClassName :param const char* pointerName :param 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

:param const char* wrapperClassName :param ::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));

:param const char* methodName :param Callable callable Note that Callable may be either a member function pointer, function pointer, std::function or function object. :param 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

:param const char* fieldName :param 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

:param const char* fieldName :param 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());

:param const char* fieldName :param 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());

:param const char* fieldName :param Getter getter: Note that Getter is a function template typename. :param 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).

:param const char* methodName :param ReturnType (*classMethod)(Args…) :param 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

:param const char* fieldName :param 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>.

:param 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>.

:param 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.

:param 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.