/*! \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.
 *
 */