Mercurial > MadButterfly

annotate dox/Android.h @ 848:702e4874a58a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use the center as the default transformaqtion point.
author wycc
date Mon, 20 Sep 2010 21:47:21 +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 */