Mercurial > MadButterfly

annotate dox/Android.h @ 1030:36a63287e1d4 refine_backend_if

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Migrate examples/dynamic to new definition of backend
author Thinker K.F. Li <thinker@codemud.net>
date Mon, 22 Nov 2010 17:43:22 +0800
parents 099d6f26dc05
children
rev   line source
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
1 /*! \page android Integrate MadButterfly with Android
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
2 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
3 * I think almost all technical guys know Android, the mobile OS
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
4 * project from Google. Once I know Android, my first idea is it is
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
5 * cool if Android programmers can be powered by MadButterfly.
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
6 * MadButterfly is very feasible for a lot of programs running on
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
7 * devices that Android be targeted for. This document is about how
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
8 * the MadButterfly is integrated with Android and power Android
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
9 * applications.
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
10 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
11 * \section android_jni Android Native Code
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
12 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
13 * Android applications are actually Java code running on Dalvik VM.
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
14 * Although, Java bytecode was translated into Dalvik bytecode. JNI
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
15 * is the bridge of bytecode and native code. Bytecode and native
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
16 * code can access each other through JNI interface. So, we must
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
17 * implement a set of JNI native function as the channel for
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
18 * communication between Android applications and MadButterfly.
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
19 * Following image is how the MadButterfly integrated with the
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
20 * Android.
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
21 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
22 * \image html Android-int.png
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
23 *
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
24 * MB JNI is a set of JNI native static methods that expose
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
25 * MadButterfly functions to Java code. Java application can call
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
26 * native static methods of MB JNI to access functions provided by
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
27 * MadButterfly.
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
28 *
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
29 * Android applications draw everything on Canvas obects (backed by a
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
30 * surface). A canvas is actually a wrapper for a SkCanvas of Skia.
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
31 * Drawing on a Canvas object means drawing on a SkCanvas object. To
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
32 * draw on the screen, MadButterfly draws on the SkCanvas.
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
33 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
34 * The idea is to make MadButterfly as a View of Android UI.
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
35 * SurfaceView is extended as MBView; the sub-type of View for showing
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
36 * graphics generated by MadButterfly. The SurfaceView own a surface.
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
37 * The surface is passed to MadButterfly as a SurfaceHolder. MB JNI
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
38 * can get Canvas objects from the SurfaceHolder, and get associated
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
39 * SkCanvas in turn. With SkCanvas objects, MadButterfly can draw for
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
40 * the MBView object.
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
41 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
42 * \section android_mem Memory Management for Android JNI Interface
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
43 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
44 * Some memory allocated and returned by MadButterfly should be
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
45 * managed by the application. These memory blocks should not be
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
46 * freed until they are no more used by MadButterfly engine. It means
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
47 * Android applications reponsible for managing memory blocks. To
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
48 * simplify implmentation of MB JNI, MB JNI always return the address
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
49 * of an allocated objects as a Java integer. Java code should
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
50 * take care about these addresses, and call proper functions for
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
51 * freeing objects specified by addresses at right time.
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
52 *
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
53 * A Java side framework should be designed to easy the work of
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
54 * Android application programmers. The framework should take care of
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
55 * tracking life-cycle of MadButterfly objects. The namespace of the
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
56 * framework is 'org.madbutterfly'.
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
57 *
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
58 * \section android_jni _jni
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
59 *
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
60 * org.madbutterfly._jni class is the placeholder to collect JNI
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
61 * native methods for all MadButterfly functions. All methods of _jni
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
62 * are static. A method usually maps to a MadButterfly function. For
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
63 * example, rdman_coord_new() mapes to the MadButterfly function with
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
64 * the same name.
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
65 *
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
66 * The object returned by a MadButterfly function, for ex. returned
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
67 * value of rdman_coord_new(), is casted to a int, the address of the
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
68 * object. So, type of an argument or return value of an object is
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
69 * declared as a int. For example,
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
70 * \code
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
71 * class _jni {
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
72 * native static int rdman_coord_new(void);
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
73 * }
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
74 * \endcode
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
75 * Java code should keep these integers carefully for maintaining
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
76 * life-cycle of objects.
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
77 *
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
78 * MadButterfly provides only initial function for some objects,
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
79 * application should allocate memory for these function by them-self.
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
80 * For these function, a new JNI native method are used instead of
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
81 * initial function. The new JNI method is responsible for allocating
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
82 * memory and calling initial function. For example, redraw_man_new()
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
83 * is defined as a JNI method instead of redraw_man_init().
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
84 * \code
487
099d6f26dc05 Change definition of redraw_man_new().
Thinker K.F. Li <thinker@branda.to>
parents: 486
diff changeset
85 * native static int redraw_man_new(Canvas cr, Canvas backend);
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
86 * \endcode
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
87 * First argument, rdman, of redraw_man_init() is replaced by a int
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
88 * returned value of redraw_man_new(). cr and backend, mbe_t type by
487
099d6f26dc05 Change definition of redraw_man_new().
Thinker K.F. Li <thinker@branda.to>
parents: 486
diff changeset
89 * MadButterfly, are, now, Canvas type by the JNI native method. The
099d6f26dc05 Change definition of redraw_man_new().
Thinker K.F. Li <thinker@branda.to>
parents: 486
diff changeset
90 * implementation of the JNI native mothod would retrieves the
099d6f26dc05 Change definition of redraw_man_new().
Thinker K.F. Li <thinker@branda.to>
parents: 486
diff changeset
91 * SkCanvas object, and casts it to mbe_t type.
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
92 *
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
93 * \section android_java_mb Java Likes MadButterfly
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
94 *
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
95 * Managing life-cycle for MadButterfly objects is not Java likes.
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
96 * To provie a Java style interface for MadButterfly, a framework to
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
97 * hide underlying life-cycle management is requried. Life-cycle is
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
98 * one major responsibility of the framework, it should keep integers
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
99 * of addresses of objects and free the associated resources with
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
100 * correct JNI methods and at right time.
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
101 *
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
102 * For example, org.madbutterfly.redraw_man is the respective Java
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
103 * class of redraw_man_t of MadButterfly engine. redraw_man has a
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
104 * private member variable redraw_man._rdman_addr. It is the address
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
105 * of the respective redraw_man_t object of MadButterfly. redraw_man
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
106 * would call _jni.redraw_man_destroy() to release associated
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
107 * resources and free the memory before it being recycled. So,
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
108 * redraw_man.finalize() is defined for releasing resources. It would
486
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
109 * be called before a redraw_man object being recycled.
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
110 *
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
111 * \section android_MBView MBView for Android MBView extends
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
112 *
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
113 * SurfaceView is a sub-class of View provided by Android. MBView
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
114 * inherits SurfaceView to implement a View controlled by
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
115 * MadButterfly. A MBView object owns a redraw_man, a.k.a
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
116 * redraw_man_t of MadButterfly. Android application programmers
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
117 * works on redraw_man to manipulate MadButterfly and changes content
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
118 * showed by the MBView object. Android applications call
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
119 * MBView.get_rdman() to retrieve the redraw_man object assocaited
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
120 * with a MBView object. MadButterfly would draw the content of a
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
121 * redraw_man object on the surface, inherited from the SurfaceView
64b994566efe Fix typo and talk more integration with Android.
Thinker K.F. Li <thinker@branda.to>
parents: 485
diff changeset
122 * class, associated with the MBView object.
485
80b8f0a4aeb9 more doc for Android
Thinker K.F. Li <thinker@branda.to>
parents: 484
diff changeset
123 *
484
5af3178ccdef Document integration of MadButterfly and Android.
Thinker K.F. Li <thinker@branda.to>
parents:
diff changeset
124 */