xrt: Add Android-specific features to xrt_instance.

Describe Android lifecycle callbacks

Co-authored-By: Jarvis Huang <quic_jarvhuan@quicinc.com>
Part-of: <https://gitlab.freedesktop.org/monado/monado/-/merge_requests/1655>

doc/changes/xrt/mr.1655.md

@@ -1,2 +1,3 @@
 - Move `xrt_instance_info` members to nested `xrt_application_info` struct, and add a parallel `xrt_platform_info`.
 - Add `xrt/xrt_android.h` header.
+- Add `xrt_instance_android` interface, optional aspect of `xrt_instance` when building on Android.

src/xrt/include/xrt/xrt_android.h

@@ -47,6 +47,153 @@ typedef bool (*xrt_android_lifecycle_event_handler_t)(struct xrt_instance_androi
                                                       enum xrt_android_lifecycle_event event,
                                                       void *userdata);
 
+#ifdef XRT_OS_ANDROID
+
+/*!
+ * @interface xrt_instance_android
+ *
+ * This is the interface to the Android-specific "aspect" of @ref xrt_instance.
+ *
+ * It is expected that your implementation of this interface will be nested in your
+ * implementation of @ref xrt_instance. It does not have a separate create or
+ * destroy function as it is an (optional) aspect of the instance.
+ */
+struct xrt_instance_android
+{
+
+	/*!
+	 * @name Interface Methods
+	 *
+	 * All Android-based implementations of the xrt_instance interface must additionally populate all these function
+	 * pointers with their implementation methods. To use this interface, see the helper functions.
+	 * @{
+	 */
+	/*!
+	 * Retrieve the stored Java VM instance pointer.
+	 *
+	 * @note Code consuming this interface should use xrt_instance_android_get_vm()
+	 *
+	 * @param xinst_android Pointer to self
+	 *
+	 * @return The VM pointer.
+	 */
+	struct _JavaVM *(*get_vm)(const struct xrt_instance_android *xinst_android);
+
+	/*!
+	 * Retrieve the stored activity android.content.Context jobject.
+	 *
+	 * For usage, cast the return value to jobject - a typedef whose definition
+	 * differs between C (a void *) and C++ (a pointer to an empty class)
+	 *
+	 * @note Code consuming this interface should use xrt_instance_android_get_context()
+	 *
+	 * @param xinst_android Pointer to self
+	 *
+	 * @return The activity context.
+	 */
+	void *(*get_context)(const struct xrt_instance_android *xinst_android);
+
+	/*!
+	 * Register a activity lifecycle event callback.
+	 *
+	 * @note Code consuming this interface should use xrt_instance_android_register_activity_lifecycle_callback()
+	 *
+	 * @param xinst_android Pointer to self
+	 * @param callback Function pointer for callback
+	 * @param event_mask bitwise-OR of one or more values from @ref xrt_android_lifecycle_event
+	 * @param userdata An opaque pointer for use by the callback. Whatever you pass here will be passed to the
+	 * callback when invoked.
+	 *
+	 * @return XRT_SUCCESS on success, other error code on error.
+	 */
+	xrt_result_t (*register_activity_lifecycle_callback)(struct xrt_instance_android *xinst_android,
+	                                                     xrt_android_lifecycle_event_handler_t callback,
+	                                                     enum xrt_android_lifecycle_event event_mask,
+	                                                     void *userdata);
+
+	/*!
+	 * Remove a activity lifecycle event callback that matches the supplied parameters.
+	 *
+	 * @note Code consuming this interface should use xrt_instance_android_remove_activity_lifecycle_callback()
+	 *
+	 * @param xinst_android Pointer to self
+	 * @param callback Function pointer for callback
+	 * @param event_mask bitwise-OR of one or more values from @ref xrt_android_lifecycle_event
+	 * @param userdata An opaque pointer for use by the callback. Whatever you pass here will be passed to the
+	 * callback when invoked.
+	 *
+	 * @return XRT_SUCCESS on success (at least one callback was removed), @ref XRT_ERROR_ANDROID on error.
+	 */
+	xrt_result_t (*remove_activity_lifecycle_callback)(struct xrt_instance_android *xinst_android,
+	                                                   xrt_android_lifecycle_event_handler_t callback,
+	                                                   enum xrt_android_lifecycle_event event_mask,
+	                                                   void *userdata);
+
+	/*!
+	 * @}
+	 */
+};
+
+/*!
+ * @copydoc xrt_instance_android::get_vm
+ *
+ * Helper for calling through the function pointer.
+ *
+ * @public @memberof xrt_instance_android
+ */
+static inline struct _JavaVM *
+xrt_instance_android_get_vm(struct xrt_instance_android *xinst_android)
+{
+	return xinst_android->get_vm(xinst_android);
+}
+
+/*!
+ * @copydoc xrt_instance_android::get_context
+ *
+ * Helper for calling through the function pointer.
+ *
+ * @public @memberof xrt_instance_android
+ */
+static inline void *
+xrt_instance_android_get_context(struct xrt_instance_android *xinst_android)
+{
+	return xinst_android->get_context(xinst_android);
+}
+
+/*!
+ * @copydoc xrt_instance_android::register_activity_lifecycle_callback
+ *
+ * Helper for calling through the function pointer.
+ *
+ * @public @memberof xrt_instance_android
+ */
+static inline xrt_result_t
+xrt_instance_android_register_activity_lifecycle_callback(struct xrt_instance_android *xinst_android,
+                                                          xrt_android_lifecycle_event_handler_t callback,
+                                                          enum xrt_android_lifecycle_event event_mask,
+                                                          void *userdata)
+{
+	return xinst_android->register_activity_lifecycle_callback(xinst_android, callback, event_mask, userdata);
+}
+
+/*!
+ * @copydoc xrt_instance_android::remove_activity_lifecycle_callback
+ *
+ * Helper for calling through the function pointer.
+ *
+ * @public @memberof xrt_instance_android
+ */
+static inline xrt_result_t
+xrt_instance_android_remove_activity_lifecycle_callback(struct xrt_instance_android *xinst_android,
+                                                        xrt_android_lifecycle_event_handler_t callback,
+                                                        enum xrt_android_lifecycle_event event_mask,
+                                                        void *userdata)
+{
+	return xinst_android->remove_activity_lifecycle_callback(xinst_android, callback, event_mask, userdata);
+}
+
+#endif // XRT_OS_ANDROID
+
 #ifdef __cplusplus
 }
 #endif

src/xrt/include/xrt/xrt_instance.h

@@ -22,6 +22,7 @@ extern "C" {
 
 struct xrt_prober;
 struct xrt_device;
+struct xrt_instance_android;
 struct xrt_space_overseer;
 struct xrt_system;
 struct xrt_system_devices;
@@ -114,7 +115,7 @@ struct xrt_instance
 	/*!
 	 * @name Interface Methods
 	 *
-	 * All implementations of the xrt_instance implementation must
+	 * All implementations of the xrt_instance interface must
 	 * populate all these function pointers with their implementation
 	 * methods. To use this interface, see the helper functions.
 	 * @{
@@ -178,6 +179,13 @@ struct xrt_instance
 	struct xrt_instance_info instance_info;
 
 	uint64_t startup_timestamp;
+
+	/*!
+	 * An "aspect" of the xrt_instance interface, used only on Android.
+	 *
+	 * @see xrt_instance_android
+	 */
+	struct xrt_instance_android *android_instance;
 };
 
 /*!