c_cpp_api.rst 3.57 KB
Newer Older
André Anjos's avatar
André Anjos committed
1
2
3
4
5
6
7
8
.. vim: set fileencoding=utf-8 :
.. Andre Anjos <andre.dos.anjos@gmail.com>
.. Tue 15 Oct 14:59:05 2013

=========
 C++ API
=========

André Anjos's avatar
André Anjos committed
9
10
The C++ API of ``bob.learn.activation`` allows users to leverage from
automatic converters for classes in :py:class:`bob.learn.activation`.  To use
André Anjos's avatar
André Anjos committed
11
the C API, clients should first, include the header file
André Anjos's avatar
André Anjos committed
12
13
``<bob.learn.activation/api.h>`` on their compilation units and then, make
sure to call once ``import_bob_learn_activation()`` at their module
André Anjos's avatar
André Anjos committed
14
instantiation, as explained at the `Python manual
André Anjos's avatar
André Anjos committed
15
16
17
18
19
20
21
<http://docs.python.org/2/extending/extending.html#using-capsules>`_.

Here is a dummy C example showing how to include the header and where to call
the import function:

.. code-block:: c++

André Anjos's avatar
André Anjos committed
22
   #include <bob.learn.activation/api.h>
André Anjos's avatar
André Anjos committed
23
24
25
26
27
28
29

   PyMODINIT_FUNC initclient(void) {

     PyObject* m Py_InitModule("client", ClientMethods);

     if (!m) return;

30
     // imports dependencies
André Anjos's avatar
André Anjos committed
31
     if (import_bob_blitz() < 0) {
32
33
34
35
36
       PyErr_Print();
       PyErr_SetString(PyExc_ImportError, "cannot import module");
       return 0;
     }

André Anjos's avatar
André Anjos committed
37
     if (import_bob_io_base() < 0) {
38
39
40
41
42
       PyErr_Print();
       PyErr_SetString(PyExc_ImportError, "cannot import module");
       return 0;
     }

André Anjos's avatar
André Anjos committed
43
     if (import_bob_learn_activation() < 0) {
44
45
46
47
       PyErr_Print();
       PyErr_SetString(PyExc_ImportError, "cannot import module");
       return 0;
     }
André Anjos's avatar
André Anjos committed
48

André Anjos's avatar
André Anjos committed
49
50
     // imports bob.learn.activation C-API
     import_bob_learn_activation();
André Anjos's avatar
André Anjos committed
51
52
53
54

   }


André Anjos's avatar
André Anjos committed
55
56
Activation Functors
-------------------
André Anjos's avatar
André Anjos committed
57

André Anjos's avatar
André Anjos committed
58
.. c:type:: PyBobLearnActivationObject
André Anjos's avatar
André Anjos committed
59

André Anjos's avatar
André Anjos committed
60
61
62
63
64
   The pythonic object representation for a
   ``bob::learn::activation::Activation`` object. It is the base class of all
   activation functors available in |project|. In C/C++ code, we recommend you
   only manipulate objects like this to keep your code agnostic to the
   activation type being used.
André Anjos's avatar
André Anjos committed
65
66
67
68
69

   .. code-block:: cpp

      typedef struct {
        PyObject_HEAD
André Anjos's avatar
André Anjos committed
70
        bob::learn::activation::Activation* base;
André Anjos's avatar
André Anjos committed
71
      } PyBobLearnActivationObject;
André Anjos's avatar
André Anjos committed
72

André Anjos's avatar
André Anjos committed
73
   .. cpp:member:: bob::learn::activation::Activation* base
André Anjos's avatar
André Anjos committed
74

André Anjos's avatar
André Anjos committed
75
76
77
      A pointer to the activation functor virtual implementation.


André Anjos's avatar
André Anjos committed
78
.. cpp:function:: int PyBobLearnActivation_Check(PyObject* o)
André Anjos's avatar
André Anjos committed
79

André Anjos's avatar
André Anjos committed
80
   Checks if the input object ``o`` is a ``PyBobLearnActivationObject``.
André Anjos's avatar
André Anjos committed
81
82
83
   Returns ``1`` if it is, and ``0`` otherwise.


André Anjos's avatar
André Anjos committed
84
.. cpp:function:: PyObject* PyBobLearnActivation_NewFromActivation(boost::shared_ptr<bob::learn::activation::Activation> a)
85
86

   Constructs a new :c:type:`PyBobLearnActivationObject` starting from a shared
André Anjos's avatar
André Anjos committed
87
88
89
90
91
   pointer to a pre-allocated `bob::learn::activation::Activation` instance.
   This API is available so that return values from actuall C++ machines can be
   mapped into Python. It is the sole way to build an object of type
   :py:class:`bob.learn.activation.Activation` without recurring to the derived
   classes.
92

André Anjos's avatar
André Anjos committed
93
94
95
96
97
98
99
100
101
102
103
.. note::

   Other object definitions exist for each of the specializations for
   activation functors found in |project|. They are exported through the module
   C-API, but we don't recommend using them since you'd loose generality. In
   case you do absolutely need to use any of these derivations, they have all
   the same object configuration:

   .. code-block:: c++

      typedef struct {
André Anjos's avatar
André Anjos committed
104
        PyBobLearnActivationObject parent;
André Anjos's avatar
André Anjos committed
105
        bob::learn::activation::<Subtype>Activation* base;
André Anjos's avatar
André Anjos committed
106
      } PyBobLearn<Subtype>ActivationObject;
André Anjos's avatar
André Anjos committed
107
108
109
110
111
112
113
114
115
116

   Presently, ``<Subtype>`` can be one of:

     * Identity
     * Linear
     * Logistic
     * HyperbolicTangent
     * MultipliedHyperbolicTangent

   Type objects are also named consistently like
André Anjos's avatar
André Anjos committed
117
   ``PyBobLearn<Subtype>Activation_Type``.
André Anjos's avatar
André Anjos committed
118
119

.. include:: links.rst