Update NativeActivity to allow direct surface access.

No actual native API for using a surface, but it's a step.

Change-Id: I627f26b705abc7a05edf9117411abfacf0fae64a

1 files changed, 114 insertions, 1 deletions

diff --git a/native/include/android/native_activity.h b/native/include/android/native_activity.h
index c0f35f8..328a4b5 100644
--- a/native/include/android/native_activity.h
+++ b/native/include/android/native_activity.h
@@ -27,32 +27,145 @@
 extern "C" {
 #endif
 
+// Temporary until native surface API is defined.
+struct android_surface_t;
+typedef struct android_surface_t android_surface_t;
+
 struct android_activity_callbacks_t;
 
+/**
+ * This structure defines the native side of an android.app.NativeActivity.
+ * It is created by the framework, and handed to the application's native
+ * code as it is being launched.
+ */
 typedef struct android_activity_t {
+    /**
+     * Pointer to the callback function table of the native application.
+     * You can set the functions here to your own callbacks.  The callbacks
+     * pointer itself here should not be changed; it is allocated and managed
+     * for you by the framework.
+     */
     struct android_activity_callbacks_t* callbacks;
 
+    /**
+     * JNI context for the main thread of the app.
+     */
     JNIEnv* env;
+    
+    /**
+     * The NativeActivity Java class.
+     */
     jobject clazz;
 
+    /**
+     * This is the native instance of the application.  It is not used by
+     * the framework, but can be set by the application to its own instance
+     * state.
+     */
     void* instance;
 } android_activity_t;
 
+/**
+ * These are the callbacks the framework makes into a native application.
+ * All of these callbacks happen on the main thread of the application.
+ * By default, all callbacks are NULL; set to a pointer to your own function
+ * to have it called.
+ */
 typedef struct android_activity_callbacks_t {
+    /**
+     * NativeActivity has started.  See Java documentation for Activity.onStart()
+     * for more information.
+     */
     void (*onStart)(android_activity_t* activity);
+    
+    /**
+     * NativeActivity has resumed.  See Java documentation for Activity.onResume()
+     * for more information.
+     */
     void (*onResume)(android_activity_t* activity);
+    
+    /**
+     * Framework is asking NativeActivity to save its current instance state.
+     * See Java documentation for Activity.onSaveInstanceState() for more
+     * information.  The returned pointer needs to be created with malloc();
+     * the framework will call free() on it for you.  You also must fill in
+     * outSize with the number of bytes in the allocation.  Note that the
+     * saved state will be persisted, so it can not contain any active
+     * entities (pointers to memory, file descriptors, etc).
+     */
     void* (*onSaveInstanceState)(android_activity_t* activity, size_t* outSize);
+    
+    /**
+     * NativeActivity has paused.  See Java documentation for Activity.onPause()
+     * for more information.
+     */
     void (*onPause)(android_activity_t* activity);
+    
+    /**
+     * NativeActivity has stopped.  See Java documentation for Activity.onStop()
+     * for more information.
+     */
     void (*onStop)(android_activity_t* activity);
+    
+    /**
+     * NativeActivity is being destroyed.  See Java documentation for Activity.onDestroy()
+     * for more information.
+     */
     void (*onDestroy)(android_activity_t* activity);
 
-    void (*onLowMemory)(android_activity_t* activity);
+    /**
+     * Focus has changed in this NativeActivity's window.  This is often used,
+     * for example, to pause a game when it loses input focus.
+     */
     void (*onWindowFocusChanged)(android_activity_t* activity, int hasFocus);
+    
+    /**
+     * The drawing surface for this native activity has been created.  You
+     * can use the given surface object to start drawing.  NOTE: surface
+     * drawing API is not yet defined.
+     */
+    void (*onSurfaceCreated)(android_activity_t* activity, android_surface_t* surface);
+
+    /**
+     * The drawing surface for this native activity has changed.  The surface
+     * given here is guaranteed to be the same as the one last given to
+     * onSurfaceCreated.  This is simply to inform you about interesting
+     * changed to that surface.
+     */
+    void (*onSurfaceChanged)(android_activity_t* activity, android_surface_t* surface,
+            int format, int width, int height);
+
+    /**
+     * The drawing surface for this native activity is going to be destroyed.
+     * You MUST ensure that you do not touch the surface object after returning
+     * from this function: in the common case of drawing to the surface from
+     * another thread, that means the implementation of this callback must
+     * properly synchronize with the other thread to stop its drawing before
+     * returning from here.
+     */
+    void (*onSurfaceDestroyed)(android_activity_t* activity, android_surface_t* surface);
+
+    /**
+     * The system is running low on memory.  Use this callback to release
+     * resources you do not need, to help the system avoid killing more
+     * important processes.
+     */
+    void (*onLowMemory)(android_activity_t* activity);
 } android_activity_callbacks_t;
 
+/**
+ * This is the function that must be in the native code to instantiate the
+ * application's native activity.  It is called with the activity instance (see
+ * above); if the code is being instantiated from a previously saved instance,
+ * the savedState will be non-NULL and point to the saved data.
+ */
 typedef void android_activity_create_t(android_activity_t* activity,
         void* savedState, size_t savedStateSize);
 
+/**
+ * The name of the function that NativeInstance looks for when launching its
+ * native code.
+ */
 extern android_activity_create_t android_onCreateActivity;
 
 #ifdef __cplusplus