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

typesharing_policy

typesharing_policy::NONE

typesharing_policy::INTRUSIVE

typesharing_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.

typearg

staticintindex

// Prototype
staticconstexprintindex

typeret_val

staticintindex

// Prototype
staticconstexprintindex

typeallow_raw_pointers

This policy is used to allow raw pointers.

typeTransform::type

typeallow_raw_pointer

select_overload and select_const 

typenamestd::add_pointer<Signature>::typeselect_overload(typenamestd::add_pointer<Signature>::typefn)

// Prototype
template<typenameSignature>
typenamestd::add_pointer<Signature>::typeselect_overload(typenamestd::add_pointer<Signature>::typefn)

Parameters:

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

typenameinternal::MemberFunctionType<ClassType,Signature>::typeselect_overload()

// Prototype
template<typenameSignature,typenameClassType>
typenameinternal::MemberFunctionType<ClassType,Signature>::typeselect_overload(Signature(ClassType::*fn))

Parameters:

Signature (ClassType::*fn) –

autoselect_const()

// Prototype
template<typenameClassType,typenameReturnType,typename...Args>
autoselect_const(ReturnType(ClassType::*method)(Args...)const)

Parameters:

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

typenameinternal::CalculateLambdaSignature<LambdaType>::typeoptional_override(constLambdaType&fp)

// Prototype
template<typenameLambdaType>
typenameinternal::CalculateLambdaSignature<LambdaType>::typeoptional_override(constLambdaType&fp)

Parameters:

const LambdaType& fp –

Functions 

voidfunction()

//prototype
template<typenameReturnType,typename...Args,typename...Policies>
voidfunction(constchar*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>
usingnamespaceemscripten;
floatlerp(floata,floatb,floatt){
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 

classvalue_array:publicinternal::noncopyable

typeclass_type

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

value_array(constchar*name)

Constructor.

Parameters:

const char* name –

~value_array()

Destructor.

value_array &element(ElementTypeInstanceType::*field)

Parameters:

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

value_array &element(Gettergetter, Settersetter)

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 

classvalue_object:publicinternal::noncopyable

typeclass_type

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

value_object(constchar*name)

Constructor.

Parameters:

const char* name –

~value_object()

Destructor.

value_object &field(constchar*fieldName, FieldTypeInstanceType::*field)

Parameters:

• const char* fieldName –

• FieldType InstanceType::*field –

value_object &field(constchar*fieldName, Gettergetter, Settersetter)

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(constchar*fieldName, index<Index>)

Parameters:

• const char* fieldName –

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

Smart pointers 

typedefault_smart_ptr_trait

//prototype
template<typenamePointerType>
structdefault_smart_ptr_trait

staticsharing_policy get_sharing_policy()

staticvoid*share(void*v)

Parameters:

void* v –

staticPointerType*construct_null()

Returns:

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

typesmart_ptr_trait

//prototype
template<typenamePointerType>
structsmart_ptr_trait:publicdefault_smart_ptr_trait<PointerType>

typedefPointerType::element_typeelement_type

//prototype
typedeftypenamePointerType::element_typeelement_type;

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

staticelement_type *get(constPointerType&ptr)

Parameters:

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

template<typenamePointeeType>
usingsmart_ptr_trait<std::shared_ptr<PointeeType >>

//prototype
template<typenamePointeeType>
structsmart_ptr_trait<std::shared_ptr<PointeeType>>

typePointerType

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

typeelement_type

A typedef for the PointerType::element_type.

staticelement_type *get(constPointerType &ptr)

Parameters:

const PointerType& ptr –

staticsharing_policy get_sharing_policy()

staticstd::shared_ptr<PointeeType >*share(PointeeType *p, EM_VALv)

Parameters:

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

• EM_VAL v –

staticPointerType *construct_null()

Classes 

classwrapper:publicT,publicinternal::WrapperBase

//prototype
template<typenameT>
classwrapper:publicT,publicinternal::WrapperBase

typeclass_type

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

wrapper(val&&wrapped, Args&&...args)

//prototype
template<typename...Args>
explicitwrapper(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.

ReturnTypecall(constchar*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 –

typebase

typeclass_type

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

staticvoidverify()

Note, is templated function which takes typename ClassType.

staticinternal::TYPEIDget()

template<typenameClassType>
usingUpcaster=BaseClass*(*)(ClassType*);
template<typenameClassType>
usingDowncaster=ClassType*(*)(BaseClass*);

staticUpcaster<ClassType>getUpcaster()

//prototype
template<typenameClassType>
staticUpcaster<ClassType>getUpcaster()

staticDowncaster<ClassType>getDowncaster()

//prototype
template<typenameClassType>
staticDowncaster<ClassType>getDowncaster()

staticTo*convertPointer(From*ptr)

//prototype
template<typenameFrom,typenameTo>
staticTo*convertPointer(From*ptr)

Parameters:

From* ptr –

typepure_virtual

typeTransform

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

typetype

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

typeconstructor

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

classclass_

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

typeclass_type

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

typebase_specifier

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

typeHELPNEEDEDHERE

class_() = delete;

explicitclass_(constchar*name)

//prototype
EMSCRIPTEN_ALWAYS_INLINEexplicitclass_(constchar*name)

Constructor.

Parameters:

const char* name –

constclass_ &smart_ptr(constchar*name)const

//prototype
template<typenamePointerType>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&smart_ptr(constchar*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.

constclass_ &constructor()const

//prototype
template<typename...ConstructorArgs,typename...Policies>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&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.

constclass_ &constructor(Callablecallable, Policies...)const

//prototype
template<typenameSignature=internal::DeduceArgumentsTag,typenameCallable,typename...Policies>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&constructor(Callablecallable,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:

usingnamespacestd::placeholders;
myClass1.constructor(&my_factory);
myClass2.constructor(std::function<ClassType2(float,float)>(&class2_factory));
myClass3.constructor<ClassType3(constval&)>(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.

constclass_ &smart_ptr_constructor()const

//prototype
template<typenameSmartPtr,typename...Args,typename...Policies>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&smart_ptr_constructor(constchar*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.

constclass_ &allow_subclass()const

//prototype
template<typenameWrapperType,typenamePointerType,typename...ConstructorArgs>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&allow_subclass(
constchar*wrapperClassName,
constchar*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.

constclass_ &allow_subclass(constchar*wrapperClassName, ::emscripten::constructor<ConstructorArgs...>constructor)const

//prototype
template<typenameWrapperType,typename...ConstructorArgs>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&allow_subclass(
constchar*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.

constclass_ &function()const

//prototype
template<typenameSignature=internal::DeduceArgumentsTag,typenameCallable,typename...Policies>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&function(constchar*methodName,Callablecallable,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:

usingnamespacestd::placeholders;
myClass.function("myClassMember",&MyClass::myClassMember)
.function("myFreeFunction",&my_free_function)
.function("myStdFunction",std::function<float(ClassType&,float,float)>(&my_function))
.function<val(constMyClass&)>("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.

constclass_ &property()const

//prototype
template<typenameFieldType,typename=typenamestd::enable_if<!std::is_function<FieldType>::value>::type>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&property(constchar*fieldName,constFieldTypeClassType::*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.

constclass_ &property(constchar*fieldName, FieldTypeClassType::*field)const

//prototype
template<typenameFieldType,typename=typenamestd::enable_if<!std::is_function<FieldType>::value>::type>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&property(constchar*fieldName,FieldTypeClassType::*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.

constclass_ &property(constchar*fieldName, Gettergetter)const

//prototype
template<typenamePropertyType=internal::DeduceArgumentsTag,typenameGetter>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&property(constchar*fieldName,Gettergetter)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.

constclass_ &property(constchar*fieldName, Gettergetter, Settersetter)const

//prototype
template<typenamePropertyType=internal::DeduceArgumentsTag,typenameGetter,typenameSetter>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&property(constchar*fieldName,Gettergetter,Settersetter)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.

constclass_ &class_function()const

//prototype
template<typenameReturnType,typename...Args,typename...Policies>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&class_function(constchar*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.

constclass_ &class_property(constchar*fieldName, FieldType*field)const

//prototype
template<typenameFieldType>
EMSCRIPTEN_ALWAYS_INLINEconstclass_&property(constchar*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(constchar*name)

//prototype
template<typenameT>
class_<std::vector<T>>register_vector(constchar*name)

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

Parameters:

const char* name –

Maps 

class_ <std::map<K,V>>register_map(constchar*name)

//prototype
template<typenameK,typenameV>
class_<std::map<K,V>>register_map(constchar*name)

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

Parameters:

const char* name –

Enums 

classenum_

//prototype
template<typenameEnumType>
classenum_

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.

typeenum_type

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

enum_(constchar*name, enum_value_typevalueType=enum_value_type::object)

Constructor.

Parameters:

• const char* name – Name of the enum in JavaScript.

• enum_value_type valueType –

  Determines how the enumerated values are represented in JavaScript.

  Possible values:

  • enum_value_type::object (default): Values are JavaScript objects with a .value field.

  • enum_value_type::number: Values are plain numbers matching their corresponding C++ values.

  • enum_value_type::string: Values are strings containing their name.

enum_ &value(constchar*name, EnumTypevalue)

Registers an enum value.

Parameters:

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

• EnumType value – The enumerated value.

Returns:

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

Constants 

voidconstant(constchar*name, constConstantType&v)

//prototype
template<typenameConstantType>
voidconstant(constchar*name,constConstantType&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.