Inheritance

An optional bases<...> argument to the class_<...> template parameter list is used to represent the inheritance relationship, such as FBModel_Wrapper above.

class_<Derived, bases<Base1,Base2> >("Derived")
     ...

Derived automatically inherits all of Base's Python methods (wrapped C++ member functions), if Base is polymorphic, Derived objects which have been passed to Python via a pointer or reference to Base can be passed where a pointer or reference to Derived is expected. It's also possible to derive new Python classes from exposed C++ class instances.

Constructors

If one class has only an implicit default constructor, Boost.Python exposes the default constructor by default, in this case the initialization constructor is not necessary.

If the constructor is intended not to be exposed, the “no_init” can be specified.

A class may have additional constructors, these can be exposed as well by passing more instances of init<...> to def():

class_<ORModelUser_Wrapper,bases<FBModel_Wrapper>("ORModelUser",init<char*>())
	.def(init< char*, double>())
	;
    ...

Data members and properties

To expose Properties, you can expose them as attributes in Python as follows:

class_<ORShaderScreen_Wrapper,bases<FBShader_Wrapper>, ("ORShaderScreen",init<char*>())
	.add_property( "Intensity", &ORShaderScreen_Wrapper::GetIntensity, &ORShaderScreen_Wrapper::SetIntensity)
	;  

//.add_property( "attribute_name", &”getter member function”, //&”setter member function”)
// 	;  
  ...

If the data member is read only, the setter function pointer may not be provided.

If “Intensity’ is a publicly-accessible data member in the class ‘ORShaderScreen_Wrapper’, it also can be directly exposed as either read-only or read/write attributes:

class_<ORShaderScreen_Wrapper,bases<FBShader_Wrapper>, ("ORShaderScreen",init<char*>())
	. def_readonly("Intensity ", & ORShaderScreen_Wrapper::Intensity)
	;  
  ...

There is a set of Macro that simplifies the attribute exposing: DECLARE_ORSDK_PROPERTY_PYTHON_ACCESS, DEFINE_ORSDK_PROPERTY_PYTHON_ACCESS, and ADD_ORSDK_PROPERTY_PYTHON_ACCESS.

These macros can be used as follows:

DECLARE_ORSDK_PROPERTY_PYTHON_ACCESS(IsDeformable,  bool)
…

DEFINE_ORSDK_PROPERTY_PYTHON_ACCESS(FBModel, IsDeformable,  bool)

class_<FBModel_Wrapper,bases<FBBox_Wrapper>, boost::noncopyable >("FBModel",no_init)
	ADD_ORSDK_PROPERTY_PYTHON_ACCESS(FBModel, IsDeformable)
	…

Operator overloading

Boost.Python provides a concise mechanism for wrapping operator overloads. For example, when these operators are defined:

FBVector2d_Wrapper* operator+ (const FBVector2d_Wrapper &pVector2d);
FBVector2d_Wrapper& operator+= (const FBVector2d_Wrapper &pVector2d);

FBVector2d_Wrapper* operator+ (double pD);
FBVector2d_Wrapper& operator+= (double pD);

FBVector2d_Wrapper* operator- ();
…

They will be exposed as follows:

class_<FBVector2d_Wrapper>("FBVector2d")
	.def(self + self)
	.def(self += self)        
	.def(self + double())        
	.def(self += double())        
	.def(-self)
	…

Virtual functions

When new Python classes are derived from exposed C++ class instances, and the C++ virtual functions in the class are also exposed. Then the functions can be used polymorphically, if the Python method implementation overrides the implementation of C++ virtual functions. We must build a special derived class to dispatch a polymorphic class' virtual functions. Refer to Boost.Python online documentation for details. Both the pure virtual function and non-pure function can be exposed by a special derived class.

Special methods

Python has a few special methods. These special methods have fix meaning for Python class. A similar set of intuitive interfaces can also be used to wrap C++ functions that correspond to these Python special functions. For example, the predefined special method ‘__repr__’,’ __len__’,’ __getitem__’,’ __setitem__’ below:

std::ostream& operator <<(std::ostream& pStream,const FBColor_Wrapper& pRight);
boost::python::str FBColor_Repr(const FBColor_Wrapper& pFBColor_Wrapper);

class_<FBColor_Wrapper>("FBColor")
	.def("__repr__",FBColor_Repr)
	.def("__len__",&FBColor_Wrapper::GetCount)
	.def("__getitem__",&FBColor_Wrapper::Get)
	.def("__setitem__",&FBColor_Wrapper::Set)
	…

Overloading

When overloading functions, we have other things to consider. Here is how to manually wrap overloaded functions:

double FBLength_Wrapper( FBVertex_Wrapper& pQ );
double FBLength_Wrapper( FBVector4d_Wrapper& pV );

Exposing code goes here:

double (*FBLength_Wrapper_1)( FBVector4d_Wrapper& pV) = FBLength_Wrapper;

double (*FBLength_Wrapper_2)( FBVertex_Wrapper& pQ ) = FBLength_Wrapper;


def("FBLength", FBLength_Wrapper_1);
def("FBLength", FBLength_Wrapper_2);

The same technique can be applied to wrapping overloaded member functions:

void ApplyUniqueShader(FBShader_Wrapper& pShader);
	void ApplyUniqueShader(ORShaderType pShaderType);

Exposing code goes here:

void (ORModelUser_Wrapper::*ApplyUniqueShader_1)(FBShader_Wrapper& pShader) = &ORModelUser_Wrapper::ApplyUniqueShader;

void (ORModelUser_Wrapper::*ApplyUniqueShader_2)(ORShaderType pShaderType) = &ORModelUser_Wrapper::ApplyUniqueShader;

class_<ORModelUser_Wrapper,bases<FBModel_Wrapper>, >("ORModelUser",init<char*>())
	.def("ApplyUniqueShader",ApplyUniqueShader_1)
	.def("ApplyUniqueShader",ApplyUniqueShader_2)
	;

Default Arguments

When encountering functions with default arguments, such as this:

object FBFindModelByName_Wrapper( char* pName, FBModel_Wrapper* pParent=NULL )

Use the Macro BOOST_PYTHON_FUNCTION_OVERLOADS to handle this situation:

BOOST_PYTHON_FUNCTION_OVERLOADS(global__FBFindModelByName_Wrapper_Overloads, FBFindModelByName_Wrapper, 1, 2)

def("FBFindModelByName",FBFindModelByName_Wrapper,global__FBFindModelByName_Wrapper_Overloads());

For member functions:

// in class FBTime_Wrapper
kLongLong GetFrame(bool pCummul = false, FBTimeMode pTimeMode = kFBTimeModeDefault, double pFramerate = 0.0)

Use the Macro BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS:

BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(FBTime_Wrapper__GetFrame_Overloads, FBTime_Wrapper::GetFrame,0,3)

class_<FBTime_Wrapper >("FBTime",init<optional<kLongLong> >())
	.def("GetFrame",&FBTime_Wrapper::GetFrame,FBTime_Wrapper__GetFrame_Overloads())
	;

Call policies

There are some predefined call policies specified when a function is defined. These policies manage the lifetimes and references among the parameters and the return values to make safe function calls. The most frequently used is the return_value_policy< manage_new_object> , which indicates that the function return a pointer to an Python instance that needs to be adopted by Python.

// in class FBTimeSpan_Wrapper
FBTime_Wrapper* GetStart()	;
…
class_<FBTimeSpan_Wrapper >("FBTimeSpan")	.def("GetStart",&FBTimeSpan_Wrapper::GetStart,return_value_policy<manage_new_object>())
	;

Object interface

Boost.Python provides a class object to enable the conversion to Python from C++ objects of arbitrary type.

object s("hello, world");  // s manages a Python string

The extract<T> class template can be used to convert Python objects to C++ types:

double x = extract<double>(o);

The object type is accompanied by a set of derived types that mirror the Python built-in types such as list, dict, tuple, str, long_, enum, etc. They look and work like regular Python code.

REGISTER_FBWRAPPER

There is a Macro used when defining an exposed class.

REGISTER_FBWRAPPER( ORModelUser );

This registers the factory function to the Wrapper Factory. The factory function makes the conversion from internal class to the Wrapper class easy. It also registers the Wrapper class to the Boost shared_ptr mechanism and defines the type information for the exposed class.