MadButterfly: dox/Android.h annotate

annotate dox/Android.h @ 1160:1a699dc00fa3

Fix the issue of not removing node in old scene when switching scenes. - When a timeline is playing and crossing two scenes (tween block), nodes, for the old scene, in duplicate group must be removed. But, it is not. - It is fixed by checking if nodes, in the duplicate group, are also in the key frame next to the new scene. All nodes that is not in next key frame are remove.

author	Thinker K.F. Li <thinker@codemud.net>
date	Tue, 28 Dec 2010 13:35:34 +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 */

Mercurial > MadButterfly

annotate dox/Android.h @ 1160:1a699dc00fa3