bind.h (under-construction) — Emscripten 4.0.9-git (dev) documentation (original) (raw)

The C++ APIs in bind.h define

Guide documentation for this API can be found in Embind.

Table of Contents

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 std::add_pointer::type select_overload(typename std::add_pointer::type fn)

Parameters:

typename std::add_pointer::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 internal::CalculateLambdaSignature::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:

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:

value_array &element(index<Index>)

Parameters:

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:

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

Parameters:

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

Parameters:

Smart pointers

type default_smart_ptr_trait

//prototype template 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 struct smart_ptr_trait : public default_smart_ptr_trait

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 struct smart_ptr_trait<std::shared_ptr>

type PointerType

A typedef to std::shared_ptr, 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:

static PointerType *construct_null()

Classes

class wrapper : public T, public internal::WrapperBase

//prototype template 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)...) , wrapped(std::forward(wrapped))

Constructor.

Parameters:

~wrapper()

Destructor.

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

Constructor.

Parameters:

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 using Upcaster = BaseClass* ()(ClassType);

template using Downcaster = ClassType* ()(BaseClass);

static Upcaster<ClassType> getUpcaster()

//prototype template static Upcaster getUpcaster()

static Downcaster<ClassType> getDowncaster()

//prototype template static Downcaster 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

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

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:

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:

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:

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:

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::value>::type> EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, const FieldType ClassType::*field) const

Parameters:

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::value>::type> EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType ClassType::*field) const

Parameters:

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 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 Getteris not pointer-to-member-function, it must accept an instance of the ClassType as the this argument. WhenGetter 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:

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:

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

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 EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType *field) const

Parameters:

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 class_<std::vector> 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 class enum_

Registers an enum to export to JavaScript. This is called from within anEMSCRIPTEN_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:

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