xrt_android.h

Go to the documentation of this file.

// Copyright 2021-2024, Collabora, Ltd.
// SPDX-License-Identifier: BSL-1.0
/*!
 * @file
 * @brief  Header holding Android-specific details.
 * @author Rylie Pavlik <rylie.pavlik@collabora.com>
 * @ingroup xrt_iface
 */
 
#pragma once
 
#include "xrt/xrt_config_os.h"
#include "xrt/xrt_compiler.h"
#include "xrt/xrt_results.h"
 
#include <stdbool.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct _JavaVM;
struct xrt_instance_info;
 
 
/*!
 * @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;
 
/*!
 * Distinguishes the possible Android lifecycle events from each other.
 *
 * Used as a bitmask when registering for callbacks.
 */
enum xrt_android_lifecycle_event
{
        XRT_ANDROID_LIVECYCLE_EVENT_ON_CREATE = 1 << 0,
        XRT_ANDROID_LIVECYCLE_EVENT_ON_DESTROY = 1 << 1,
        XRT_ANDROID_LIVECYCLE_EVENT_ON_PAUSE = 1 << 2,
        XRT_ANDROID_LIVECYCLE_EVENT_ON_RESUME = 1 << 3,
        XRT_ANDROID_LIVECYCLE_EVENT_ON_START = 1 << 4,
        XRT_ANDROID_LIVECYCLE_EVENT_ON_STOP = 1 << 5,
};
 
/*!
 * A callback type for a handler of Android lifecycle events.
 *
 * Return true to be removed from the callback list.
 */
typedef bool (*xrt_android_lifecycle_event_handler_t)(struct xrt_instance_android *xinst_android,
                                                      enum xrt_android_lifecycle_event event,
                                                      void *userdata);
 
#ifdef XRT_OS_ANDROID
 
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