| [ Web Proxy ] |
| Viewing: https://emscripten.org/docs/api_reference/../porting/guidelines/../../api_reference/bind.h.html | [Back] [Original] |
The C++ APIs in bind.h define
Guide documentation for this API can be found in Embind.
Table of Contents
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.
name This is a label to mark a group of related bindings (for example EMSCRIPTEN_BINDINGS(physics), EMSCRIPTEN_BINDINGS(components), etc.)
Currently only allow_raw_pointers policy is supported.
Eventually we hope to implement Boost.Python-like raw pointer policies for managing
object ownership.
![[Emscripten]](https://emscripten.org/docs/api_reference/../porting/guidelines/../../api_reference/../../_static/emscripten_logo_full.svg){kind=link}
// Prototype
template<typename Signature>
typename std::add_pointer<Signature>::type select_overload(typename std::add_pointer<Signature>::type fn)
typename std::add_pointer<Signature>::type fn
// Prototype
template<typename Signature, typename ClassType>
typename internal::MemberFunctionType<ClassType, Signature>::type select_overload(Signature (ClassType::*fn))
Signature (ClassType::*fn)
// Prototype
template<typename ClassType, typename ReturnType, typename... Args>
auto select_const(ReturnType (ClassType::*method)(Args...) const)
ReturnType (ClassType::*method)(Args...) const
// Prototype
template<typename LambdaType>
typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType& fp)
const LambdaType& fp
//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);
}
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.
ElementType InstanceType::*field Note that ElementType and InstanceType are typenames (templated types).
Getter getter Note that Getter is a typename (templated type).
Setter setter Note that Setter is a typename (templated type).
index<Index> Note that Index is an integer template parameter.
const char* fieldName
FieldType InstanceType::*field
const char* fieldName
Getter getter Note that Getter is a typename (templated type).
Setter setter Note that Setter is a typename (templated type).
const char* fieldName
index<Index> Note that Index is an integer template parameter.
//prototype
template<typename PointerType>
struct default_smart_ptr_trait
void* v
//prototype
template<typename PointerType>
struct smart_ptr_trait : public default_smart_ptr_trait<PointerType>
//prototype
typedef typename PointerType::element_type element_type;
A typedef for the PointerType::element_type, where PointerType is a typename (templated type).
const PointerType& ptr Note that PointerType is a typename (templated type)
//prototype
template<typename PointeeType>
struct smart_ptr_trait<std::shared_ptr<PointeeType>>
A typedef to std::shared_ptr<PointeeType>, where PointeeType is a typename (templated type).
A typedef for the PointerType::element_type.
const PointerType& ptr
PointeeType* p Note that PointeeType is a typename (templated type).
EM_VAL v
//prototype
template<typename T>
class wrapper : public T, public internal::WrapperBase
template<typename ClassType>
using Upcaster = BaseClass* (*)(ClassType*);
template<typename ClassType>
using Downcaster = ClassType* (*)(BaseClass*);
//prototype
template<typename ClassType>
static Upcaster<ClassType> getUpcaster()
Note that this is a templated class with typename parameters ClassType and BaseSpecifier.
//prototype
EMSCRIPTEN_ALWAYS_INLINE explicit class_(const char* name)
Constructor.
const char* name
//prototype
template<typename PointerType>
EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr(const char* name) const
const char* name
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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.
Policies... policies Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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.
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.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//prototype
template<typename SmartPtr, typename... Args, typename... Policies>
EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr_constructor(const char* smartPtrName, SmartPtr (*factory)(Args...), Policies...) const
const char* smartPtrName
SmartPtr (*factory)(Args...)
Policies... policies Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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
const char* wrapperClassName
const char* pointerName
emscripten::constructor<ConstructorArgs...> constructor)
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//prototype
template<typename WrapperType, typename... ConstructorArgs>
EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass(
const char* wrapperClassName,
::emscripten::constructor<ConstructorArgs...> constructor = ::emscripten::constructor<>()
) const
const char* wrapperClassName
::emscripten::constructor<ConstructorArgs...> constructor)
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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));
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.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
// prototype
template<typename ElementType>
EMSCRIPTEN_ALWAYS_INLINE const class_& iterable(const char* sizeMethodName, const char* getMethodName) const
Makes a bound class iterable in JavaScript by installing Symbol.iterator.
This enables use with for...of loops, Array.from(), and spread syntax.
ElementType The type of elements yielded by the iterator.
sizeMethodName Name of the bound method that returns the number of elements.
getMethodName Name of the bound method that retrieves an element by index.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
class_<MyContainer>("MyContainer")
.function("size", &MyContainer::size)
.function("get", &MyContainer::get)
.iterable<int>("size", "get");
const container = new Module.MyContainer();
for (const item of container) { /* ... */ }
const arr = Array.from(container);
//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
const char* fieldName
const FieldType ClassType::*field
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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
const char* fieldName
FieldType ClassType::*field
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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());
const char* fieldName
Getter getter Note that Getter is a function template typename.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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());
const char* fieldName
Getter getter Note that Getter is a function template typename.
Setter setter Note that Setter is a function template typename.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//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).
const char* methodName
ReturnType (*classMethod)(Args...)
Policies... Policy for managing raw pointer object ownership. Currently must be allow_raw_pointers.
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//prototype
template<typename FieldType>
EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType *field) const
const char* fieldName
FieldType ClassType::*field
A const reference to the current object. This allows chaining of the class_ functions that define the binding in the EMSCRIPTEN_BINDINGS() block.
//prototype
template<typename T>
class_<std::vector<T>> register_vector(const char* name)
A function to register a std::vector<T>.
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>.
const char* name
//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.
Constructor.
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.
Registers an enum value.
const char* name The name of the enumerated value.
EnumType value The enumerated value.
A reference to the current object. This allows chaining of
multiple enum values in the EMSCRIPTEN_BINDINGS()
block.
//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);
}
const char* name The name of the constant.
const ConstantType& v The constant type. This can be any type known to embind.
Copyright © 2015, Emscripten Contributors.
Made with Sphinx and Shibuya theme.
| Web Proxy Viewer | New URL | Original Page |