Mercurial > MadButterfly
view dox/Android.h @ 656:38c720272dd5
Change prefix for the code generated by generator
author | Thinker K.F. Li <thinker@branda.to> |
---|---|
date | Sat, 31 Jul 2010 14:11:01 +0800 |
parents | 099d6f26dc05 |
children |
line wrap: on
line source
/*! \page android Integrate MadButterfly with Android * * I think almost all technical guys know Android, the mobile OS * project from Google. Once I know Android, my first idea is it is * cool if Android programmers can be powered by MadButterfly. * MadButterfly is very feasible for a lot of programs running on * devices that Android be targeted for. This document is about how * the MadButterfly is integrated with Android and power Android * applications. * * \section android_jni Android Native Code * * Android applications are actually Java code running on Dalvik VM. * Although, Java bytecode was translated into Dalvik bytecode. JNI * is the bridge of bytecode and native code. Bytecode and native * code can access each other through JNI interface. So, we must * implement a set of JNI native function as the channel for * communication between Android applications and MadButterfly. * Following image is how the MadButterfly integrated with the * Android. * * \image html Android-int.png * * MB JNI is a set of JNI native static methods that expose * MadButterfly functions to Java code. Java application can call * native static methods of MB JNI to access functions provided by * MadButterfly. * * Android applications draw everything on Canvas obects (backed by a * surface). A canvas is actually a wrapper for a SkCanvas of Skia. * Drawing on a Canvas object means drawing on a SkCanvas object. To * draw on the screen, MadButterfly draws on the SkCanvas. * * The idea is to make MadButterfly as a View of Android UI. * SurfaceView is extended as MBView; the sub-type of View for showing * graphics generated by MadButterfly. The SurfaceView own a surface. * The surface is passed to MadButterfly as a SurfaceHolder. MB JNI * can get Canvas objects from the SurfaceHolder, and get associated * SkCanvas in turn. With SkCanvas objects, MadButterfly can draw for * the MBView object. * * \section android_mem Memory Management for Android JNI Interface * * Some memory allocated and returned by MadButterfly should be * managed by the application. These memory blocks should not be * freed until they are no more used by MadButterfly engine. It means * Android applications reponsible for managing memory blocks. To * simplify implmentation of MB JNI, MB JNI always return the address * of an allocated objects as a Java integer. Java code should * take care about these addresses, and call proper functions for * freeing objects specified by addresses at right time. * * A Java side framework should be designed to easy the work of * Android application programmers. The framework should take care of * tracking life-cycle of MadButterfly objects. The namespace of the * framework is 'org.madbutterfly'. * * \section android_jni _jni * * org.madbutterfly._jni class is the placeholder to collect JNI * native methods for all MadButterfly functions. All methods of _jni * are static. A method usually maps to a MadButterfly function. For * example, rdman_coord_new() mapes to the MadButterfly function with * the same name. * * The object returned by a MadButterfly function, for ex. returned * value of rdman_coord_new(), is casted to a int, the address of the * object. So, type of an argument or return value of an object is * declared as a int. For example, * \code * class _jni { * native static int rdman_coord_new(void); * } * \endcode * Java code should keep these integers carefully for maintaining * life-cycle of objects. * * MadButterfly provides only initial function for some objects, * application should allocate memory for these function by them-self. * For these function, a new JNI native method are used instead of * initial function. The new JNI method is responsible for allocating * memory and calling initial function. For example, redraw_man_new() * is defined as a JNI method instead of redraw_man_init(). * \code * native static int redraw_man_new(Canvas cr, Canvas backend); * \endcode * First argument, rdman, of redraw_man_init() is replaced by a int * returned value of redraw_man_new(). cr and backend, mbe_t type by * MadButterfly, are, now, Canvas type by the JNI native method. The * implementation of the JNI native mothod would retrieves the * SkCanvas object, and casts it to mbe_t type. * * \section android_java_mb Java Likes MadButterfly * * Managing life-cycle for MadButterfly objects is not Java likes. * To provie a Java style interface for MadButterfly, a framework to * hide underlying life-cycle management is requried. Life-cycle is * one major responsibility of the framework, it should keep integers * of addresses of objects and free the associated resources with * correct JNI methods and at right time. * * For example, org.madbutterfly.redraw_man is the respective Java * class of redraw_man_t of MadButterfly engine. redraw_man has a * private member variable redraw_man._rdman_addr. It is the address * of the respective redraw_man_t object of MadButterfly. redraw_man * would call _jni.redraw_man_destroy() to release associated * resources and free the memory before it being recycled. So, * redraw_man.finalize() is defined for releasing resources. It would * be called before a redraw_man object being recycled. * * \section android_MBView MBView for Android MBView extends * * SurfaceView is a sub-class of View provided by Android. MBView * inherits SurfaceView to implement a View controlled by * MadButterfly. A MBView object owns a redraw_man, a.k.a * redraw_man_t of MadButterfly. Android application programmers * works on redraw_man to manipulate MadButterfly and changes content * showed by the MBView object. Android applications call * MBView.get_rdman() to retrieve the redraw_man object assocaited * with a MBView object. MadButterfly would draw the content of a * redraw_man object on the surface, inherited from the SurfaceView * class, associated with the MBView object. * */