bind.h (under-construction)

The C++ APIs in bind.h define (HamishW-Replace with description.)

Guide documentation for this API can be found in Embind.

How to use this API

Defines

EMSCRIPTEN_BINDINGS(name)

HamishW Confirm this is correct.

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

HamishW-Replace with description. Note this is a strongly typed enum. I can’t see better way in Sphinx to represent it.

type sharing_policy::NONE

HamishW-Replace with description.

type sharing_policy::INTRUSIVE

HamishW-Replace with description.

type sharing_policy::BY_EMVAL

HamishW-Replace with description.

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

HamishW Add description.

type ret_val
static int index
// Prototype
static constexpr int index

HamishW Add description.

type allow_raw_pointers

This policy is used to whitelist raw pointers.

type Transform::type

HamishW Add description.

type allow_raw_pointer

HamishW Add description. Note from source: “This type is temporary, it will be changed when arg policies are reworked”

select_overload and select_const

HamishW Nicer title ?

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)

HamishW Add description.

:param typename std::add_pointer<Signature>::type fn: HamishW Add description.

Returns:HamishW Add description.
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))

HamishW Add description.

:param Signature (ClassType::fn): **HamishW* Add description.

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

HamishW Add description.

:param ReturnType (ClassType::method)(Args...) const: **HamishW* Add description.

Returns:HamishW Add description.
typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType& fp)
// Prototype
template<typename LambdaType>
typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType& fp)

HamishW Add description.

Parameters const LambdaType& fp:
 HamishW Add description.
Returns:HamishW Add description.

Functions

void* __getDynamicPointerType(void* p)

HamishW Add description.

Parameters void* p:
 HamishW Add description.
Returns:HamishW Add description.
void* __getDynamicPointerType(void* p)

HamishW Add description.

Parameters void* p:
 HamishW Add description.
Returns:HamishW Add description.
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);
}

HamishW Check description. Note that Sphinx could not cope with the prototype, so have moved it into the body above.

Parameters:
  • const char* name – The name of the function to export (e.g. "lerp") HamishW Check description.
  • 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

HamishW Add description.

type class_type

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

value_array(const char* name)

Constructor. HamishW Add description.

Parameters const char* name:
 HamishW Add description.
~value_array()

Destructor. HamishW Add description.

value_array& element(ElementType InstanceType::*field)

HamishW Add description.

:param ElementType InstanceType::field: **HamishW* Add description. Note that ElementType and InstanceType are typenames (templated types). :returns: HamishW Add description.

value_array& element(Getter getter, Setter setter)

HamishW Add description.

Parameters:
  • Getter getter – HamishW Add description. Note that Getter is a typename (templated type).
  • Setter setter – HamishW Add description. Note that Setter is a typename (templated type).
Returns:

HamishW Add description.
value_array& element(index<Index>)

HamishW Add description.

Parameters index<Index>:
 HamishW Add description. Note that Index is an integer template parameter.
Returns:HamishW Add description.

Value structs

class value_object : public internal::noncopyable

HamishW Add description.

type class_type

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

value_object(const char* name)

Constructor. HamishW Add description.

Parameters const char* name:
 HamishW Add description.
~value_object()

Destructor. HamishW Add description.

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

HamishW Add description.

Parameters const char* fieldName:
 HamishW Add description.

:param FieldType InstanceType::field: **HamishW* Add description.

Returns:HamishW Add description.
value_object& field(const char* fieldName, Getter getter, Setter setter)

HamishW Add description.

Parameters:
  • const char* fieldName – HamishW Add description.
  • Getter getter – HamishW Add description. Note that Getter is a typename (templated type).
  • Setter setter – HamishW Add description. Note that Setter is a typename (templated type).
Returns:

HamishW Add description.
value_object& field(const char* fieldName, index<Index>)

HamishW Add description.

Parameters:
  • const char* fieldName – HamishW Add description.
  • index<Index> – HamishW Add description. Note that Index is an integer template parameter.
Returns:

HamishW Add description.

Smart pointers

type default_smart_ptr_trait
//prototype
template<typename PointerType>
struct default_smart_ptr_trait

HamishW Add description.

static sharing_policy get_sharing_policy()

HamishW Add description.

Returns:HamishW Add description.
static void* share(void* v)

HamishW Add description.

Parameters void* v:
 HamishW Add description.
Returns:HamishW Add description.
static PointerType* construct_null()

HamishW Add description.

Returns:HamishW Add description. 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>

HamishW Add description. Note from source is: // specialize if you have a different pointer type

type PointerType::element_type element_type
//prototype
typedef typename PointerType::element_type element_type;

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

static element_type* get(const PointerType& ptr)

HamishW Add description.

Parameters const PointerType& ptr:
 HamishW Add description. Note that PointerType is a typename (templated type)
Returns:HamishW Add description.
type smart_ptr_trait<std::shared_ptr<PointeeType>>
//prototype
template<typename PointeeType>
struct smart_ptr_trait<std::shared_ptr<PointeeType>>

HamishW Add description.

type PointerType

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

type element_type

HamishW Add description. A typedef for the PointerType::element_type.

static element_type* get(const PointerType& ptr)

HamishW Add description.

Parameters const PointerType& ptr:
 HamishW Add description.
Returns:HamishW Add description.
static sharing_policy get_sharing_policy()

HamishW Add description.

Returns:HamishW Add description.
static std::shared_ptr<PointeeType>* share(PointeeType* p, internal::EM_VAL v)

HamishW Add description.

Parameters PointeeType* p:
 HamishW Add description. Note that PointeeType is a typename (templated type).

:param internal::EM_VAL v: HamishW Add description. :returns: HamishW Add description.

static PointerType* construct_null()

HamishW Add description.

Returns:HamishW Add description.

HamishW Note, did not include private class val_deleter. I am assuming all private classes are internal. Delete this Chad when read!

Classes

HamishW Add description if needed. Note from source “// abstract classes”

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

HamishW Add description.

type class_type

HamishW Add description. 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. HamishW Add description.

Parameters:
  • val&& wrapped – HamishW Add description.
  • Args&&... args – HamishW Add description. Note that Args is a typename (templated type).
Returns:

HamishW Add description.
~wrapper()

Destructor. HamishW Add description.

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

Constructor. HamishW Add description.

Parameters:
  • const char* name – HamishW Add description.
  • Args&&... args – HamishW Add description. Note that Args is a typename (templated type).
Returns:

HamishW Add description. Note that ReturnType is a typename (templated type).
EMSCRIPTEN_WRAPPER(T)

HamishW Add description. Note that this is actually a define, but I’ve implemented it as a function, because that is how it behaves, and it allows me to have the T as shown, which isn’t possible on Sphinx type declaration.

Parameters T:HamishW Add description.
type base

HamishW Add description.

type class_type

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

static void verify()

HamishW Add description. Note, is templated function which takes typename ClassType.

static internal::TYPEID get()

HamishW Add description.

Returns:HamishW Add description.
HAMISHW_ HELP_Needed

HamishW I don’t understand this C++, so not sure how to document. Putting code here for Chad to advise on how to document

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

HamishW Add description.

Returns:HamishW Add description.
static Downcaster<ClassType> getDowncaster()
//prototype
template<typename ClassType>
static Downcaster<ClassType> getDowncaster()

HamishW Add description.

Returns:HamishW Add description.
static To* convertPointer(From* ptr)
//prototype
template<typename From, typename To>
static To* convertPointer(From* ptr)

HamishW Add description.

Parameters From* ptr:
 HamishW Add description.
Returns:HamishW Add description.
type pure_virtual

HamishW Add description.

type Transform

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

type type

HamishW Add description. This is a typdef to the parent struct typename parameter InputType.

type constructor

HamishW Add description. Note that this is a template struct taking typename ... ConstructorArgs.

class class_

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

type class_type

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

type base_specifier

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

type HELPNEEDEDHERE

HamishW Don’t know what do do with this:

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

Constructor. HamishW Add description.

Parameters const char* name:
 HamishW Add description.
Returns:HamishW Add description.
const class_& smart_ptr(const char* name) const
//prototype
template<typename PointerType>
EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr(const char* name) const

HamishW Add description.

Parameters const char* name:
 HamishW Add description.
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.

HamishW Check description. Note that prototype moved into block as was breaking Sphinx.

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() const
//prototype
template<typename... Args, typename ReturnType, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& constructor(ReturnType (*factory)(Args...), Policies...) const

Class constructor for objects that use a factory function to create the object. See External constructors for more information.

Parameters:
  • ReturnType (*factory)(Args...) – The address of the class factory function.
  • 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

HamishW Add description. Note that Sphinx could NOT cope with the prototype, so have pulled it into the body of the text.

Parameters:
  • const char* smartPtrName – HamishW Add description.
  • SmartPtr (*factory)(Args...) – HamishW Add description.
  • 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

HamishW Add description.

Parameters:
  • const char* wrapperClassName – HamishW Add description.
  • const char* pointerName – HamishW Add description.

:param ::emscripten::constructor<ConstructorArgs...> constructor): HamishW Add description. :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... ConstructorArgs>
EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass(
  const char* wrapperClassName,
  ::emscripten::constructor<ConstructorArgs...> constructor = ::emscripten::constructor<>()
) const

HamishW Add description. Explain how this constructor differs from other one.

Parameters const char* wrapperClassName:
 HamishW Add description.

:param ::emscripten::constructor<ConstructorArgs...> constructor): HamishW Add description.

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 ReturnType, typename... Args, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& function(const char* methodName, ReturnType (ClassType::*memberFunction)(Args...), 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.

HamishW Check description. Note prototype moved to “prototype” block above because syntax broke Sphinx. Also explain how this method differs from the other overloads.

Parameters const char* methodName:
 HamishW Add description.

:param ReturnType (ClassType::memberFunction)(Args...): **HamishW* Add description. Note that ReturnType is a template typename for this function and ClassType is a template typename for the class. :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_& function() const
//prototype
template<typename ReturnType, typename... Args, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& function(const char* methodName, ReturnType (ClassType::*memberFunction)(Args...) const, Policies...) const

HamishW Add description. Note, prototype moved into block above as it broke Sphinx. Also this only differs by a const on the ReturnType from the previous function

Parameters const char* methodName:
 HamishW Add description.

:param ReturnType (ClassType::memberFunction)(Args...) const: **HamishW* Add description. Note that ReturnType is a template typename for this function and ClassType is a template typename for the class. :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_& function() const
//prototype
template<typename ReturnType, typename ThisType, typename... Args, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& function(const char* methodName, ReturnType (*function)(ThisType, Args...), Policies...) const

HamishW Add description. Note, prototype moved into block above as it broke Sphinx.

Parameters:
  • const char* methodName – HamishW Add description.
  • ReturnType (*function)(ThisType, Args...) – HamishW Add description.
  • 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

HamishW Add description. Note, signature copied to prototype block above because proper signature broke Sphinx. Also because it is useful to include the template information.

Parameters const char* fieldName:
 HamishW Add description.

:param const FieldType ClassType::field: **HamishW* Add description.

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

HamishW Add description.

Parameters const char* fieldName:
 HamishW Add description.

:param FieldType ClassType::field: **HamishW* Add description.

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

HamishW Add description.

Parameters:
  • const char* fieldName – HamishW Add description.
  • Getter getter – HamishW Add description. 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 Getter, typename Setter>
EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, Getter getter, Setter setter) const

HamishW Add description. Note that this is a function template taking typenames Setter and Getter: template<typename Getter, typename Setter>

Parameters:
  • const char* fieldName – HamishW Add description.
  • Getter getter – HamishW Add description. Note that Getter is a function template typename.
  • Setter setter – HamishW Add description. 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.

HamishW Check description. Note prototype moved to “prototype” block above because syntax broke Sphinx.

Parameters:
  • const char* methodName – HamishW Add description.
  • ReturnType (*classMethod)(Args...) – HamishW Add description.
  • 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.

Vectors

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

HamishW Check description.

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

Parameters const char* name:
 HamishW Add description.
Returns:HamishW Add description.

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)

HamishW Check description.

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

Parameters const char* name:
 HamishW Add description.
Returns:HamishW Add description.

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

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

enum_(const char* name)

Constructor. HamishW Add description.

Parameters const char* name:
 HamishW Add description.
Returns:HamishW Add description.
enum_& value(const char* name, EnumType value)

Registers an enum value. HamishW Check description.

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)

HamishW Check description.

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.