Mercurial > MadButterfly

comparison dox/Android.h @ 486:64b994566efe Android_Skia

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